polycode

An open-source, model-agnostic terminal coding agent — like Claude Code, but with free, open-source models. Use DeepSeek, GLM, Qwen, Llama and more via OpenRouter's free tier, run them locally with Ollama, or bring your own GPT/Claude/Gemini keys — all from one terminal UI.

›  add input validation to the signup form

● read   src/auth/signup.ts
● edit   src/auth/signup.ts
● run    npm test
I added validation and the tests pass.

Features

• Free, open-source models, your choice of provider. Use DeepSeek, GLM, Qwen, Llama, gpt-oss and more for free via OpenRouter, or switch to Groq / Cerebras for much higher free limits (about 1,000 requests/day vs OpenRouter's ~200) and faster responses. All free, no credit card.
• Fully local & keyless option. Run open models on your own machine with Ollama — no key, no limits.
• Any model. Built on the Vercel AI SDK — also works directly with OpenAI, Anthropic, Google, and any OpenAI-compatible endpoint using your own keys.
• In-terminal model picker. Run /model for a Claude-Code-style menu pre-loaded with the live list of all tool-capable models (250+) — free ones marked ·free and listed first; type to filter, arrow keys to select.
• Real coding tools. Read, write, and edit files; multi_edit to apply several edits to one file in a single approval; list the directory tree; find_files by glob (src/**/*.ts); search the codebase; run shell commands; and fetch_url to pull docs or API references straight into context.
• Parallel sub-agents. The agent can spawn_agents to fan out several read-only investigations at once (each in its own context) and get back concise reports. Big questions get answered faster, and all that digging stays out of your main conversation.
• MCP client built in. Connect Model Context Protocol servers (local stdio or remote SSE) and their tools join the agent's toolset automatically. Plug in databases, browsers, search, your own tooling. Each MCP call is permission-gated like any write. See /mcp.
• Sector plugins. /plugins opens a selector of expert "skills" you can download, enable, and disable: Frontend, Backend, and DevOps to start. An enabled plugin loads focused domain guidance into the agent (and persists across launches). Downloaded plugins live as editable markdown in ~/.config/polycode/plugins/, so you can tweak them or drop in your own.
• Working modes. normal asks before each change, plan and question are read-only (investigate or discuss, nothing is touched), and auto runs writes and commands end to end. Switch with /mode or cycle with Shift+Tab.
• Task checklist. For multi-step work the agent keeps a live to-do list in view, so you can see the plan and watch it tick off.
• Attach context with @. Mention @path/to/file or @dir to inline a file (or a directory listing) into your message. Tab completes the path.
• Inline shell with !. Type !npm test or !git status to run a command directly, no model turn spent.
• Undo/redo file changes. /undo reverts the last write or edit (or deletes a newly created file); /redo re-applies it. /diff shows what changed.
• Save & resume sessions. /save, /resume, and /sessions persist a conversation across runs. /compact summarizes history to free up context; /export writes the transcript to markdown.
• Project memory. Drops a POLYCODE.md, AGENTS.md, or CLAUDE.md in your repo into the system prompt automatically, so the agent follows your conventions.
• Live token counter in the status bar, plus /retry to resend the last message after a hiccup.
• Permission prompts. Approve each file write and command (y / a always / n deny), or run with --yolo to auto-approve.
• The agent asks you back. When a request is ambiguous, polycode pauses and asks a clarifying question, with arrow-key options or free text, then continues with your answer.
• Rich terminal UI built with Ink: streaming output, colored diffs, live tool status.
• Switch models on the fly with /model <name> — your conversation is kept.
• Adjustable thinking speed. Reasoning models can be slow; /think off|low|medium|high dials reasoning effort (default low for speed). Press Esc to cancel a slow turn.

Install

One command (anyone, anywhere)

npm install -g openpoly

That's it — no cloning, no folders. Now open any terminal, cd into a project, and run polycode (or openpoly). It works on whatever directory you're in. Update with npm i -g openpoly@latest; remove with npm rm -g openpoly.

Install from source (for development)

# from anywhere — point npm at the project folder; it builds and installs globally
npm install -g /absolute/path/to/polycode

# Windows PowerShell
npm install -g "C:\path\to\polycode"

Now open any terminal, cd into a project you want help with, and run:

polycode

To update later, re-run the install command. To remove it: npm rm -g polycode.

Run from source (no global install)

cd polycode
npm install
npm run dev

Configure

Recommended: free models via OpenRouter

1. Create a free OpenRouter API key (no credit card) at openrouter.ai/keys.
2. Run polycode. On first run it prompts you to paste the key right in the terminal (masked) and saves it for next time — no env-var setup needed. Type /key anytime to enter or change it.
3. The default model is gpt-oss (OpenAI gpt-oss-120b, free). Run /model (or /models) to open a picker populated with all 250+ tool-capable models — free ones marked ·free and shown first; type to filter, arrow keys to move, enter to select. The free set rotates; DeepSeek/GLM/Kimi show up whenever they're offered free.

Prefer env vars? Set OPENROUTER_API_KEY (PowerShell: $env:OPENROUTER_API_KEY="sk-or-...") and the prompt is skipped. The terminal-entered key is stored at ~/.config/polycode/auth.json.

Free models are rate-limited (≈20 requests/min, ≈200/day) and shared, so they can be slower or briefly unavailable.

Fully local & free with Ollama (no key)

Install Ollama, pull a model, then pick a *-local model:

ollama pull qwen3        # or: ollama pull deepseek-r1 / glm4
polycode --model=qwen-local

No API key, no rate limits — it runs on your machine.

Config file

On first run, polycode seeds ~/.config/polycode/config.json (older configs are auto-migrated; the previous file is kept as config.json.bak):

{
  "version": 2,
  "defaultModel": "qwen-coder",
  "models": [
    { "name": "qwen-coder", "provider": "openrouter", "model": "qwen/qwen3-coder:free" },
    { "name": "llama", "provider": "openrouter", "model": "meta-llama/llama-3.3-70b-instruct:free" },
    { "name": "gpt-oss", "provider": "openrouter", "model": "openai/gpt-oss-120b:free" },
    { "name": "deepseek-local", "provider": "openai-compatible", "model": "deepseek-r1", "baseURL": "http://localhost:11434/v1" },
    { "name": "claude-direct", "provider": "anthropic", "model": "claude-3-5-sonnet-latest" }
  ]
}

You can also switch directly with a provider:model ref, without editing config:

/model groq:llama-3.3-70b-versatile
/model cerebras:gpt-oss-120b
/model zenmux:anthropic/claude-fable-5       # ZenMux aggregator (paid)
/model deepseek/deepseek-chat-v3.1:free      # bare id = OpenRouter

Add a Groq, Cerebras, or ZenMux key (via /key <provider> or env var) and the /model picker automatically lists all of that provider's models too, tagged by provider, free ones first. ZenMux is an OpenAI-compatible gateway: one key unlocks 100+ models (Claude, GPT, DeepSeek, GLM, and more).

API keys (env vars, never written to disk)

| Provider | Env var | Free tier | | ------------------- | -------------------------------- | --------- | | openrouter | OPENROUTER_API_KEY | free, ~200 req/day | | groq | GROQ_API_KEY | free, ~1,000 req/day, very fast | | cerebras | CEREBRAS_API_KEY | free, ~1,000 req/day, fastest | | zenmux | ZENMUX_API_KEY | paid gateway, one key for 100+ models | | openai-compatible | none for local Ollama/LM Studio | unlimited (local) | | openai | OPENAI_API_KEY | paid | | anthropic | ANTHROPIC_API_KEY | paid | | google | GOOGLE_GENERATIVE_AI_API_KEY | free tier |

Get free keys at openrouter.ai/keys, console.groq.com/keys, or cloud.cerebras.ai.

You can also drop a project-level .polycode.json in any repo to override or add models for that project.

MCP servers (optional)

Connect Model Context Protocol servers to give the agent extra tools (databases, browsers, search, your own tooling). The easiest way is right from the chat, no config editing or restart:

/mcp                                                    # list servers (and the syntax)
/mcp add fetch npx -y @modelcontextprotocol/server-fetch
/mcp add github npx -y @modelcontextprotocol/server-github GITHUB_TOKEN=ghp_…
/mcp add docs https://your-server.example.com/sse       # remote SSE server
/mcp remove fetch

/mcp add connects the server immediately, attaches its tools to the running session, and saves it so it reconnects on the next launch. An https:// target is a remote SSE server; anything else is a local command (an npx shim works on Windows too). Tokens shaped like NAME=value become environment variables for the server.

Prefer a file? Add an mcpServers block to ~/.config/polycode/config.json (global) or a project .polycode.json (project servers merge on top):

{
  "mcpServers": {
    "fetch":  { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"] },
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } },
    "remote": { "url": "https://your-mcp-server.example.com/sse", "headers": { "Authorization": "Bearer ..." } }
  }
}

• stdio servers: give a command (and optional args / env).
• SSE servers: give a url (and optional headers).
• Set "disabled": true to keep a server in the file without connecting.

Each server's tools are namespaced on any name collision. A server that fails or times out is skipped without blocking startup. Run /mcp to see what connected. MCP tool calls go through the same approval prompt as file writes (auto-approved under --yolo / auto mode).

Usage

polycode                      # start with the default model
polycode --model=llama        # start with a specific model
polycode --yolo               # auto-approve writes and commands

In-session commands

Type / to see them inline with autocomplete; Tab completes. Full list:

Models & keys

| Command | Description | | ---------------- | -------------------------------------------------------------- | | /model | open the model picker (free models first, recents on top) | | /model <name> | switch directly (configured name or provider:model ref) | | /model - | switch back to the previously used model | | /models | browse every available model | | /key [provider]| set an API key (current model, or e.g. /key groq) | | /keys | show which provider keys are set | | /think <lvl> | reasoning effort: off/low/medium/high (lower = faster) |

Files & changes

| Command | Description | | ---------------- | -------------------------------------------------------------- | | /files | list files changed this session | | /diff [file] | show this session's changes to a file | | /undo | revert the last file change | | /redo | re-apply the last undone change | | /edit [file] | open a file in your default editor | | /init | generate a POLYCODE.md project guide |

Run & inspect

| Command | Description | | ---------------- | -------------------------------------------------------------- | | /run <cmd> | run a shell command (same as !cmd) | | /mode [name] | switch mode: normal/plan/question/auto (or Shift+Tab) | | /tools | list the tools the agent can use | | /mcp | show connected MCP servers and their tools | | /plugins | download, enable, or disable sector plugins (frontend, etc.) | | /system | show the active system prompt | | /stats | session stats: messages, tools, files, time | | /cost | token usage this session | | /yolo | toggle auto-approving writes & commands |

Conversation

| Command | Description | | ---------------- | -------------------------------------------------------------- | | /copy | copy the last reply to your clipboard | | /paste | paste the clipboard into the prompt | | /last | reprint the last reply | | /history | show recent prompts | | /compact | summarize history to free up context | | /retry | resend the last message (handy after a rate limit) | | /export [file] | save the conversation to a markdown file | | /clear, /new | clear the conversation |

Sessions & misc

| Command | Description | | ---------------- | -------------------------------------------------------------- | | /save [name] | save this session to resume later | | /resume [name] | restore a saved session | | /sessions | list saved sessions | | /pwd | print the working directory | | /welcome | show the starting tips again | | /version | show the polycode version | | /help | show help | | /exit, /quit | quit polycode |

Keyboard & input shortcuts

| Shortcut | Description | | ----------------- | ------------------------------------------------------------- | | !<cmd> | run a shell command without the model | | @<path> | attach a file or directory to your message (Tab completes it) | | Tab | complete a slash command or @path | | ↑ / ↓ | browse prompt history (also Ctrl+P / Ctrl+N) | | Ctrl+U | clear the input line | | Ctrl+L | clear the screen | | Esc | cancel a running reply, or clear the input | | Ctrl+C | cancel a turn; press twice to quit |

Architecture

src/
  cli.tsx            entry point — args, wiring, render
  config/            load/merge config (versioned, auto-migrating), resolve keys
  providers/         map a config entry → a Vercel AI SDK model; list free models
  tools/             read / write / edit / multi_edit / find_files / run_command / search_code / fetch_url + permission broker
  mcp/               connect MCP servers (stdio + SSE), merge their tools
  agent/             the agentic loop (streamText + tools, multi-step) + read-only sub-agents
  tui/               Ink components — transcript, permission dialog, status bar

The agent loop leans on the Vercel AI SDK's multi-step tool calling so behavior is uniform across providers. Tools request approval through a PermissionBroker that bridges tool execution and the UI.

License

MIT