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.

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.

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.

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.