polycode

An agentic coding CLI. Runs on your machine, writes a SHA-256 chained session log to disk, and ships with a free hosted tier so you can start in one command. Your history is auditable, replayable, and portable across machines.

As of v1.2.0, polycode is a substrate router, not a single agent loop. Every prompt is classified and dispatched to the right substrate: questions stream like ChatGPT, image requests call the image API directly, vague website prompts ask a clarifying question before building. Full parity with the web playground at polylogicai.com/polycode/play.

Install and run

One command, no setup, any platform:

npx @polylogicai/polycode@latest

That is the entire install. The first run provisions a per-install ID under ~/.polycode/ and opens an interactive session. On the free hosted tier you get 60 turns per hour for free, routed through polylogicai.com/api/polycode/inference. For unlimited use, set GROQ_API_KEY (see below) and polycode will talk to Groq directly and skip the proxy.

For repeated use, install globally:

npm install -g @polylogicai/polycode
polycode

One-shot mode

Pass your prompt as an argument:

npx @polylogicai/polycode@latest "read README.md and summarize it in one sentence"

Unlimited use with your own key

Grab a free key from console.groq.com, then:

# macOS and Linux
export GROQ_API_KEY=gsk_...
npx @polylogicai/polycode@latest

# Windows PowerShell
$env:GROQ_API_KEY = "gsk_..."
npx @polylogicai/polycode@latest

Configuration

polycode reads configuration from environment variables and optionally from a ~/.polycode/secrets.env file (chmod 600 recommended).

How polycode keeps costs low

polycode defaults to Groq's free developer tier. Every turn routes through moonshotai/kimi-k2-instruct on Groq, which has zero per-token cost. The hosted proxy at polylogicai.com forwards requests to Groq using a server-side key, so you do not need any API key to start.

This means prompt caching (Anthropic's 90% input-token discount) is not relevant to the default path. There are no input tokens to cache because Groq's free tier does not charge for them.

For users who set ANTHROPIC_API_KEY for higher-quality reasoning on complex tasks, the Anthropic path uses Claude Haiku for context compilation (selecting which session-log rows matter for this turn) and the primary model for the agentic loop. The system prompt is static across turns, which preserves Anthropic's prompt cache. Each turn adds incrementally to the conversation prefix, so cache hit rates remain high.

Context window: polycode chains every turn into a SHA-256 linked session log at ~/.polycode/history/. The compiler (lib/compiler.mjs) selects only the most relevant prior turns for each new request, so the model never receives the full history. This keeps each call well within the model's context window while preserving cross-session continuity through the chain.

How polycode decides what to do (v1.2.0 substrate router)

Every prompt you send goes through a fast regex classifier that picks one of four substrates:

• Chat -- EXPLAIN prompts ("how do React hooks work", "what is a closure") stream a plain-text answer. No files, no tools.
• Image -- BUILD prompts that name a concrete image ("generate a cat image", "make me a logo for a coffee shop") call the image API directly. The image is downloaded to your current working directory.
• Ask-on-vague -- BUILD prompts that are too vague to start ("make me a website") print a clarifying question and wait for your next message.
• Agent -- everything else dispatches into the agent loop with a subtype-aware system prompt. A bakery website request gets the premium website template; a monthly revenue chart gets the Recharts data template; a food truck menu gets the printable document template.

The classifier is pure regex, deterministic, <1ms, no network round-trip. Pass --force-build on one-shot mode to skip the chat-mode branch when your shell script knows better.

Usage

polycode runs a standard agentic loop: you ask, it thinks, it uses tools, it returns a result. Available tools are:

• bash run a shell command in the working directory
• read_file read a file relative to the working directory
• write_file write a file to the working directory
• edit_file replace a substring in a file
• glob list files matching a pattern (cross-platform, pure Node.js)
• grep search for a regex in files (cross-platform, pure Node.js)
• describe_image analyze an image file via a vision model
• fetch_url fetch a URL and return the body as readable text
• web_search search the web and return titles, URLs, and snippets

All file tool calls are sandboxed to the working directory. polycode refuses any path that escapes it. fetch_url refuses loopback and private network addresses.

Session history

Every turn polycode takes is appended to a SHA-256 chained JSONL file at ~/.polycode/history/YYYY-MM-DD.jsonl. You own this file. You can:

• Read it to see exactly what the agent did
• Back it up by copying it
• Hand it to a teammate, who can replay the session on their machine
• Run polycode --verify to confirm the chain is intact

Slash commands

Inside the REPL:

/help      show all commands
/key       save an API key (Groq, Anthropic, OpenAI). Input is masked on real terminals.
/clear     clear the terminal
/history   show the session history file path and row count
/verify    verify session history integrity
/exit      leave polycode

Paste handling

When you paste multi-line content into polycode, the terminal collapses it to a marker like [Pasted #1 (20 lines)] in the prompt line. The full content is still sent to the agent — only the display is compressed. You can paste a whole file, a stack trace, or a long URL and polycode will treat it as one event.

Saving API keys (never in chat)

polycode never accepts API keys pasted into the chat — the local secret scrubber blocks any message that matches a key pattern before it reaches the model. To save a key the right way:

# Inside the REPL
/key

# Or from your shell
polycode login

Both flows read the key through a masked prompt and save it to ~/.polycode/secrets.env with chmod 600. The model never sees it. Auto-detects Groq, Anthropic, and OpenAI from the key prefix.

Command-line flags

polycode                    interactive REPL
polycode "<prompt>"         one-shot mode
polycode --version          print version
polycode --help             print help
polycode --history          print session history status
polycode --verify           verify session history integrity

Safety rules

polycode enforces a small set of non-negotiable safety rules out of the box:

• Shell commands referencing system paths (/etc/passwd, ~/.ssh, private key files) are refused
• Code patterns that evaluate untrusted input are refused
• Tool output containing recognized secret patterns (AWS, GitHub, Stripe, Anthropic, Groq, PEM blocks) is redacted before it reaches the model or the terminal

Rules live in ~/.polycode/rules.yaml. You can add your own.

Requirements

• Node.js 20 or newer
• macOS, Linux, or Windows
• No API key required for the free hosted tier. Set GROQ_API_KEY for unlimited use.

Releasing (for maintainers)

polycode ships through a gated publish pipeline. Do not run npm publish by hand — that path can silently ship a broken tarball the way the web-app chat substrate env-var bug reached production on 2026-04-17. Use the gated flow instead:

npm run publish:gated

What it does: (1) publishes the tarball to the @next dist-tag, so users running npm install -g @polylogicai/polycode still get the previous known-good build; (2) installs that tarball into a scratch temp directory; (3) runs four smoke probes against the installed binary — version match, --help render, a chat-substrate arithmetic check, and an identity-gate leak check; (4) only promotes the version to @latest if every probe passes. If any probe fails, @next keeps the broken snapshot for post-mortem and @latest stays pinned to the previous release.

npm run publish:gated -- --dry-run runs the full pipeline against whatever version is currently on @latest, minus the real publish and promote commands. Useful before a real release.

Pushing a v*.*.* git tag triggers the same flow in CI via .github/workflows/publish-on-tag.yml, using the NPM_TOKEN repo secret.

Documentation and support

• Install and usage: polylogicai.com/polycode
• Issues and questions: ajs10845@psu.edu

License

MIT. See LICENSE. Built by Polylogic AI.

polycode is inspired by Claude Code's public architecture at docs.claude.com. polycode is not affiliated with Anthropic. No Claude Code code or system prompts are copied.