Why This Agent? β’
Install β’
Usage β’
CLI β’
Web β’
π Guide
An interactive AI coding assistant that runs in your terminal or web browser β powered by free cloud APIs and local models (Ollama, LM Studio, Llama.cpp). It reads, writes, searches, copies, moves, and deletes files, and runs shell commands β all through natural language tool calling. Includes MCP (Model Context Protocol) and LSP (Language Server Protocol) support for extensibility and deep code understanding.
π‘ Offline-ready: With a local server, the agent works fully offline β no internet required, no data leaves your machine.
| Problem | Solution |
|---|---|
| Coding assistants cost $20/month (ChatGPT+, Claude Pro) | 100% free β uses free-tier OpenRouter, Groq, Google, DeepSeek, Mistral + local models |
| One provider goes down / rate-limited | 13 providers β auto-fallback on 429 + auto-routing (auto/coding, auto/fast, etc.) + manual /model <n> |
| No internet access / restricted region | Local models (Ollama, LM Studio, Llama.cpp) β fully offline |
| Privacy concerns with cloud APIs | Run local models only β zero data leaves your machine |
| Setup is too complex | npm run setup β interactive wizard, no manual .env editing |
| AI runs dangerous commands | Safe mode (/safe) β whitelist-only shell commands |
| Agent gets stuck in loops | Smart detection β stops after 3Γ identical tool calls |
| Agent needs to research before editing | Build/Plan modes β auto-switches to read-only plan mode for research, full build mode for changes |
| Want to ask a quick code question without context switch | @explore subagent β spawn a read-only agent mid-conversation for instant code research |
| Provider rate-limited | Auto-fallback β switches provider automatically on 429 |
| Long tool results waste tokens | Token compression β head+tail truncation + duplicate removal |
| Want to extend with external tools | MCP support β connect any Model Context Protocol server |
| Need deep code understanding | LSP support β go to definition, find references, hover info |
| Want to use your IDE with free models | OpenAI-compatible API β npm run setup-ide connects Cline, Continue.dev, Cursor |
- 13 providers β OpenRouter, Groq, Google, DeepSeek, Mistral, Anthropic, Together AI, Perplexity, xAI (Grok), Cohere + Ollama, LM Studio, Llama.cpp
- MCP (Model Context Protocol) β connect external tools (filesystem, GitHub API, databases, custom servers). Stdio + HTTP/SSE transports.
/mcp list/connect/disconnect/toggle - LSP (Language Server Protocol) β
code_definition,code_references,code_hovertools. Supports TypeScript, JavaScript, Python (pyright), Rust (rust-analyzer), Go (gopls)./lsptoggle - Multi-session management β named sessions in
sessions/directory, auto-title, modelPreset metadata. Work on multiple projects independently and switch between them at any time./session list/new/rename/delete - 7 built-in presets β start with
openrouter/free(auto-discovers working free models), plus Google Gemini and Ollama for local/offline use - Build/Plan modes β switch between
build(full tool access) andplan(read-only) modes manually via/modeor let the agent auto-switch viaswitch_modetool. Plan mode filters write/edit/run tools; agent can escalate autonomously @exploresubagent β type@explore <query>to spawn a read-only agent for instant code research, results injected into conversation- Auto-routing β 6 quality-filtered routes (
auto/coding,auto/fast,auto/cheap,auto/reasoning,auto/vision,auto/offline) with automatic API key detection; user-editable viaroute-presets.json - Usage tracking β per-session and aggregated token/request counts via API (
GET /api/usage) - Collapsible fallback errors β failed fallback attempts shown as expandable
β οΈ N fallback(s) banner inside the assistant message - Model discovery β auto-detect available models from each provider on invalid model names (400 error); manual
/discovercommand andGET /api/discoverendpoint - User presets β save/add/remove your own models with
/save,/add,/remove - Fallback chain β auto-fallback across providers on rate limit (429), plus model-level fallbacks
- 17 built-in tools β read, write, list, create_folder, delete_file, delete_folder, append_file, copy_file, move_file, file_info, search_content, replace_in_file, run_command, git_diff, git_commit, git_log, web_search
- Token compression β head+tail truncation + automatic duplicate removal
- Sliding window context β keeps the last 20 exchanges, auto-trims (configurable)
- Smart loop detection β stops after 3Γ identical or 5Γ consecutive tool calls
- Safe mode (
--safe//safe) β whitelist-only shell commands - Setup wizard β
npm run setupinteractively configures .env - Automatic retry β exponential backoff + 120s timeout (300s for local models)
- Zod validation β runtime type-checking of every tool input and output
- CLI & Web unified β shared model config, system prompt, tool engine
- AGENTS.md support β drop
AGENTS.mdin project root for project-specific context - Session disk persistence (Web UI) β sessions saved to
sessions/dir, survive restarts - Session rename β rename sessions in Web UI via βοΈ button or API
- Collapsible tool calls β βΆ/βΌ toggle for streaming & history in Web UI
- Stop button β abort AI generation mid-stream via AbortController
- Per-message copy β π button on every user/assistant message
- Copy session β π Copy session as markdown via button or Ctrl+Shift+C
- Keyboard shortcuts β Ctrl+N/D/K/B/L, PgUp/PgDn, Home/End, Escape
- Settings panel β font-size slider, compact mode, auto-scroll (localStorage)
- Auto-scroll toggle β floating β¬ button when scrolled up
- Toast notifications β 3s auto-dismiss feedback
- Welcome screen β empty-state guide, removed on first message
- Diff Viewer (Web UI) β line-level LCS diffs for file operations
- Git tools β
git_diff,git_commit,git_logbuilt-in tools for source control operations - Docker sandbox β optional isolation; set
DOCKER_SANDBOX_ENABLED=trueto run commands inside a container - Session export/import β πΎ export / π₯ import sessions in Web UI
- Session cleanup β tool messages stripped from persisted sessions, empty sessions not saved, test-like sessions filtered from list
- Delete-all safety β Web UI requires typing "DELETE", CLI requires "yes"
- Standalone binary β compile with
npm run build:binary(no Node.js required)
- Node.js 18+ (or use the standalone binary β no Node.js needed)
- npm (comes with Node.js)
- Optional: One or more API keys (see Environment Variables)
- Optional for local models: Ollama, LM Studio, or Llama.cpp
- Optional for LSP:
typescript-language-server,pyright,rust-analyzer,gopls,clangd,solargraph,lua-language-server
git clone https://github.com/maz557/coding-agent-free.git
cd coding-agent-free
npm installOption A β Interactive wizard (recommended):
npm run setupThe wizard also offers to install LSP servers (typescript-language-server, pyright, sql-language-server) globally for code intelligence (definition, references, hover).
Option B β Manual .env (pick at least one provider):
# OpenRouter (easiest β single key for 18+ free tool-calling models)
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env
# Optional providers:
echo "GROQ_API_KEY=gsk_..." >> .env # Ultra-fast inference
echo "GOOGLE_API_KEY=AIza..." >> .env # Gemini models
echo "DEEPSEEK_API_KEY=sk-..." >> .env # DeepSeek
echo "MISTRAL_API_KEY=..." >> .env # Mistral modelsOption C β Local only (fully offline):
# Skip API keys β just start your local model server
ollama run qwen3:14b # or LM Studio, Llama.cpp
npm start # Inside agent: /add 6 ollama:auto && /model 6Build a single executable for Windows, Linux, or macOS:
npm run build:binary # All platforms
npm run build:binary:win # Windows only
npm run build:binary:web # Web server binary
node scripts/build-binary.js node18-win-x64 coding-agent.exe # Or via helpernpm run setup-ideConfigures Cline, Continue.dev, and Cursor to use the local API proxy at http://localhost:3000/v1/chat/completions.
| Variable | Required? | Free Tier | Description |
|---|---|---|---|
OPENROUTER_API_KEY |
No* | 18+ free models, 1 key | https://openrouter.ai/keys |
GROQ_API_KEY |
No* | 30 req/min on many models | https://console.groq.com/keys |
GOOGLE_API_KEY |
No* | 60 req/min, generous free tier | https://aistudio.google.com/apikey |
DEEPSEEK_API_KEY |
No* | Credit-based free tier | https://platform.deepseek.com |
MISTRAL_API_KEY |
No* | Free tier available | https://console.mistral.ai |
ANTHROPIC_API_KEY |
No* | Limited free tier | https://console.anthropic.com |
TOGETHER_API_KEY |
No* | 25 free API calls/day | https://api.together.xyz/settings/api-keys |
PERPLEXITY_API_KEY |
No* | $5 free credit | https://www.perplexity.ai/settings/api |
XAI_API_KEY |
No* | Free tier (limited) | https://console.x.ai |
COHERE_API_KEY |
No* | Free tier (1000 req/month) | https://dashboard.cohere.com/api-keys |
OLLAMA_HOST |
No | β | Ollama server URL (default: http://localhost:11434/v1) |
LMSTUDIO_HOST |
No | β | LM Studio URL (default: http://localhost:1234/v1) |
LLAMACPP_HOST |
No | β | Llama.cpp URL (default: http://localhost:8080/v1) |
ALLOWED_DIR |
No | β | Write operations scope (default: ./workspace) |
READ_ALLOWED_DIR |
No | β | Read operations scope (default: . = everywhere) |
SCRATCH_DIR |
No | β | Extra directory allowed for temp/file scratch (no default) |
LOCAL_TIMEOUT |
No | Timeout (ms) for local models (default: 600000 = 10 min) |
|
CLOUD_TIMEOUT |
No | Timeout (ms) for cloud models (default: 120000 = 2 min) |
|
LOG_LEVEL |
No | β | debug, info, warn, error (default: info) |
MAX_EXCHANGES |
No | β | Max exchanges in sliding window (default: 20) |
MAX_TOOL_RESULT_LENGTH |
No | β | Max chars before truncation (default: 5000) |
DOCKER_SANDBOX_ENABLED |
No | β | Enable Docker sandbox for command isolation (default: false) |
DOCKER_IMAGE |
No | β | Docker image for sandboxed execution (default: ubuntu:22.04) |
* At least one API key required (not needed for local providers).
See docs/GUIDE.md for step-by-step key registration guides.
All hardware/network settings go in .env (project root) β this is the only file you need to edit for your machine-specific setup:
| Variable | Default | Description |
|---|---|---|
LOCAL_TIMEOUT |
600000 (10 min) |
Max wait for local model responses. Increase if running on slow hardware |
CLOUD_TIMEOUT |
120000 (2 min) |
Max wait for cloud API responses |
OLLAMA_HOST |
http://localhost:11434/v1 |
Ollama server URL |
LMSTUDIO_HOST |
http://localhost:1234/v1 |
LM Studio URL |
LLAMACPP_HOST |
http://localhost:8080/v1 |
Llama.cpp URL |
ALLOWED_DIR |
./workspace |
Write operations scope |
READ_ALLOWED_DIR |
. (everywhere) |
Read operations scope |
SCRATCH_DIR |
β | Extra directory allowed for temp/scratch files |
The timeout resets on each streaming token β it only fires when no data arrives for the full duration.
MCP & LSP server configuration still goes in
.coding-agent.json(project root) since it uses structured JSON. Everything else is in.env.
Optionally run commands inside a Docker container for isolation:
| Variable | Default | Description |
|---|---|---|
DOCKER_SANDBOX_ENABLED |
false |
Set to true to enable Docker sandbox |
DOCKER_IMAGE |
ubuntu:22.04 |
Docker image to use for sandboxed execution |
When enabled, run_command, git_diff, git_commit, and git_log execute inside the container.
Route priorities and model lists go in route-presets.json. Built-in model definitions are in presets.json. See Changing the default local model below.
coding-agent-free/
βββ src/
β βββ agent.ts # CLI entry point
β βββ CodingAgent.ts # Agent loop, tool execution, stuck detection
β βββ ConversationState.ts # Sliding window, context trimming
β βββ server.ts # Express web server (SSE, sessions, API)
β βββ persistence.ts # Multi-session save/load
β βββ config/models.ts # Provider definitions, presets, system prompt (no tool names)
β βββ config/userConfig.ts # User configuration loader (.env)
β βββ validation.ts # Zod schemas for tool I/O validation
β βββ tools/
β β βββ fileManager.ts # 13 file/shell tools + safe mode
β β βββ toolRegistry.ts # Central registry (builtin + MCP + LSP)
β βββ mcp/ # MCP support
β β βββ types.ts # JSON-RPC types, Tool, Transport interface
β β βββ transport.ts # StdioTransport (subprocess)
β β βββ HTTPTransport.ts # HTTP/SSE transport
β β βββ MCPManager.ts # Multi-server management
β β βββ config.ts # Load MCP servers from .coding-agent.json
β βββ lsp/ # LSP support
β β βββ LSPClient.ts # JSON-RPC LSP client over stdio
β β βββ LSPManager.ts # Multi-language LSP server management (entries[] w/ filePatterns)
β β βββ config.ts # Load LSP servers from .coding-agent.json
β β βββ index.ts # Tool definitions: code_definition/references/hover/lookup_symbol/get_diagnostics
β βββ __tests__/ # 13 test files, 220+ unit tests
βββ public/index.html # Web UI (plain JS)
βββ sessions/ # Session storage
βββ workspace/ # Default working directory
βββ scripts/ # Setup, build, test, cleanup scripts
βββ examples/mcp-echo-server.js # Minimal MCP server example
βββ .env # API keys, timeouts, host ports (gitignored)
βββ .env.example # Template with all variables explained
βββ .coding-agent.json # MCP + LSP server configuration (structured JSON)
βββ AGENTS.md # Auto-loaded project context
βββ tsconfig.json
βββ package.json
npm startOn Windows, double-click
run-cli.bat. For RTL languages (Persian, Arabic, Urdu), userun-cli-rtl.bat(requires WezTerm).
The agent automatically connects MCP and LSP servers on startup, loads project context from AGENTS.md, and restores the last session.
Best for: Quick tasks, terminal-centric workflows, CI/CD automation, RTL language support, low resource usage. Has: Full session CRUD, all slash commands, MCP/LSP management.
npm run web
# Open http://localhost:3000 in your browserOn Windows, double-click
run-web.bat.
Best for: Visual diff review, session management with persistence, keyboard shortcuts, team collaboration, settings customization β this interface has the most features overall. Has: All CLI capabilities + visual diff viewer, settings panel, collapsible tool calls, stop button, auto-scroll toggle, per-message & session copy, welcome screen, toast notifications, keyboard shortcuts, LSP/MCP toggle indicators, route badge, collapsible fallback errors banner.
Web UI features:
- Streaming responses β token-by-token via SSE
- Diff Viewer β line-level LCS diffs for write/replace/append operations
- Session Manager β create, switch, list, rename, export (πΎ), import (π₯), delete (β) sessions; disk persistence across restarts; tool messages stripped from persisted sessions
- Settings Panel β font-size slider, compact mode, auto-scroll toggle (localStorage)
- Keyboard Shortcuts β Ctrl+N (new), Ctrl+D/B (sessions), Ctrl+K (focus), Ctrl+L (reset), Ctrl+Shift+C (copy session), Escape (close), PgUp/PgDn/Home/End
- Collapsible Tool Calls β βΆ/βΌ toggle header + body for streaming and history
- Stop Button β abort streaming via AbortController
- Auto-scroll Toggle β floating β¬ button when scrolled up
- Per-message Copy β π button on every user/assistant message (preserved during streaming)
- Copy Session β π button + Ctrl+Shift+C formats conversation as markdown
- Toast Notifications β 3s auto-dismiss feedback
- Welcome Screen β shown on empty chat, removed on first message
- Route Badge β blue pill showing current auto-route (e.g. "Coding", "Fast") with provider:model tooltip
- Collapsible Fallback Errors β
β οΈ N fallback(s) banner inside assistant message, expandable to show error details - LSP Toggle β π’ON/β«OFF status with active languages
- MCP Toggle β π’ON/β«OFF status
- Slash Commands β
/active,/model <n>,/safe,/allow,/reset,/models,/exit,/mcp list/toggle,/lsp - Help Modal β click
?for usage guide, commands reference, keyboard shortcuts - OpenAI-compatible API β
http://localhost:3000/v1/chat/completions
Example session:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π¬ Coding Agent [π Safe] [π P] β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β You: create a hello.py that prints "Hello from Web UI" β
β β³ Thinking... β
β π write_file(path="hello.py", content="...") β
β β File written (25 bytes) β
β π run_command(command="python hello.py") β
β β Hello from Web UI β
β Done! Created hello.py and verified it prints. β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β [Message input... ] [Send] β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Tool | Description |
|---|---|
read_file |
Read contents of a file |
write_file |
Write content to a file (creates/overwrites) |
list_files |
List directory contents. Use details:true for size + timestamps |
create_folder |
Create a new folder |
delete_file |
Delete a single file |
delete_folder |
Delete a folder. Set recursive:true for non-empty folders |
append_file |
Append content to an existing file |
copy_file |
Copy a file from source to destination |
move_file |
Move or rename a file |
file_info |
Get detailed metadata (size, permissions, timestamps) |
search_content |
Search for exact text in files. Supports filePattern and maxResults |
replace_in_file |
Replace the first occurrence of exact text (case-sensitive) |
run_command |
Run a shell command in the workspace |
git_diff |
Show diff between working tree and HEAD, or between two commits |
git_commit |
Create a new git commit with a message |
git_log |
Show commit history with optional file path filter |
switch_mode |
Switch between build (full) and plan (read-only) mode β agent-controlled |
| Tool | Description |
|---|---|
code_definition |
Find where a symbol is defined (file:line:column) |
code_references |
Find all references to a symbol across the project |
code_hover |
Get type signature, documentation, and inline hints |
lookup_symbol |
Search for symbols by name (e.g., "find all classes named User*") |
get_diagnostics |
Get live errors/warnings for a file (like a linter on demand) |
Tools from connected MCP servers appear automatically alongside built-in tools. See MCP section.
| Command | Description |
|---|---|
/model <n> |
Switch to preset n (/model 5) or auto-route (/model auto/coding, /model auto/fast, etc.) |
/save <n> |
Save current model as preset n |
/add <n> <m> |
Add model m as preset n (provider:model or just model) |
/remove <n> |
Remove a user preset |
/allow <p> |
Allow model to access a path outside workspace |
/safe |
Toggle safe mode |
/models |
Show all presets |
/active |
Show current active model |
/reset |
Clear conversation history |
/session list |
List all sessions |
/session new <name> |
Create a new session |
/session rename <old> <new> |
Rename a session |
/session delete <name> |
Delete a session |
/mcp list |
List connected MCP servers and their tools |
/mcp connect <name> <cmd> |
Connect a new MCP server |
/mcp disconnect <name> |
Disconnect an MCP server |
/mcp toggle |
Enable / disable all MCP tools |
/lsp |
Toggle LSP tools |
/mode build|plan |
Switch between build (full access) and plan (read-only) mode |
@explore <query> |
Spawn a read-only subagent for instant code research |
/discover |
Fetch available models from providers (auto-corrects stale names) |
/list-providers |
Show providers with valid keys |
/exit |
Quit |
Connect external tools to the agent via MCP servers β filesystem, GitHub API, databases, custom tools, and more. Supports both stdio (subprocess) and HTTP/SSE (remote) transports.
Quick start:
- Install an MCP server:
npm install -g @modelcontextprotocol/server-filesystem - Add to
.coding-agent.json:{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"] } } } - Start the agent β it connects automatically:
π MCP "filesystem" connected (2 tools)
Example MCP servers:
| Server | Install | Purpose |
|---|---|---|
| Filesystem | @modelcontextprotocol/server-filesystem |
Safe file operations with path boundaries |
| GitHub | @modelcontextprotocol/server-github |
Repository management, PRs, issues |
| PostgreSQL | @modelcontextprotocol/server-postgres |
Read-only database queries |
| Puppeteer | @modelcontextprotocol/server-puppeteer |
Browser automation, screenshots |
Create your own MCP server β see
examples/mcp-echo-server.jsfor a minimal example.
Deep code understanding via code_definition, code_references, and code_hover tools. Auto-detects project files and starts appropriate LSP servers.
Supported languages (default):
| Language | LSP Server | File Patterns |
|---|---|---|
| TypeScript/TSX | typescript-language-server |
**/*.ts, **/*.tsx |
| JavaScript/JSX | typescript-language-server |
**/*.js, **/*.jsx, **/*.mjs |
| Python | pyright |
**/*.py |
| Rust | rust-analyzer |
**/*.rs |
| Go | gopls |
**/*.go |
| SQL | sql-language-server |
**/*.sql |
| C | clangd |
**/*.c, **/*.h |
| C++ | clangd |
**/*.cpp, **/*.hpp, **/*.cc, **/*.cxx |
| Ruby | solargraph |
**/*.rb |
| Lua | lua-language-server |
**/*.lua |
Custom LSP servers β add to .coding-agent.json:
{
"lspServers": [
{
"command": "clangd",
"args": [],
"languageId": "cpp",
"filePatterns": ["**/*.cpp", "**/*.h"]
}
]
}Toggle LSP at any time with /lsp. Falls back gracefully if no LSP server binary is installed.
# Add a model from any provider
/add 10 groq:llama-3.3-70b-versatile
/add 11 google:gemini-2.0-flash-exp
# Use auto-routes (intelligently selects best available model)
/model auto/coding
/model auto/fast
# Switch presets
/model 10Auto-fallback: if a provider returns 429, the agent automatically tries the next model in the auto-route chain. The quality-filtered routes (auto/coding, auto/fast, auto/cheap, auto/reasoning, auto/vision, auto/offline) detect which API keys are available and skip unavailable providers. Edit route priorities in route-presets.json.
No API key required. The model must support tool calling (function calling).
Three server options β llama.cpp recommended for large-context agent work:
llama-server -m "MyModel-Q4_K_M.gguf" -c 65536 --port 8080 --flash-attn on --cache-type-k q4_0 --cache-type-v q4_0
| Flag | Why it matters for agents |
|---|---|
-c 65536 |
64K context β agent sessions can grow long (tool calls, file reads, diffs). Without this, you'll hit context limits mid-task. |
--flash-attn on |
Speeds up processing linearly with context length. Essential for 32K+ contexts. |
--cache-type-k q4_0 |
Quantized KV cache β cuts memory usage per token by ~4Γ, letting you fit 64K context in 16β24 GB VRAM. |
Download models from Hugging Face (look for GGUF files). You need at least 8 GB RAM (16 GB+ recommended for 64K context). Example β search for tool-calling fine-tunes like
Llama-3.2orQwen2.5instruct models.
Replace with a different GGUF: just change the -m path and update the model name in the agent (use provider:llamacpp):
/add 9 llamacpp:my-model-name
Access from a different machine: set LLAMACPP_HOST in .env:
LLAMACPP_HOST=http://192.168.1.100:8080/v1
If you want auto/offline (or the fallback chain) to use your model automatically, edit:
route-presets.jsonβ change theoffline.presetsand/orcoding.presets/reasoning.presetsentries. Each entry isprovider:model:"offline": { "presets": ["llamacpp:MyModel"], "minQuality": "low" }
.envβ set timeout and server URL for your hardware:LOCAL_TIMEOUT=600000 LLAMACPP_HOST=http://localhost:8080/v1
presets.json(built-in defaults, overridden by route-presets.json) β change preset entries if you rebuild withnpm run build.
Alternatively, just /add <n> llamacpp:MyModel during a session and /model <n> β changes are immediate and don't persist across server restarts unless you edit the files above.
# Ollama
ollama pull llama3.2 && ollama serve
/add 10 ollama:auto
# LM Studio
lms get llama-3.2-3b-instruct && lms server start --port 1234
/add 11 lmstudio:autoBy default, the agent can only access files inside ./workspace. Change with:
ALLOWED_DIR=.in.env(access everything)/allow "C:\path"during a session (temporary)
| # | Model | Provider | Notes |
|---|---|---|---|
| 1 | openrouter/free |
OpenRouter | Auto-routes to available free models |
| 2 | Qwen 3 Next 80B | OpenRouter | Good general purpose |
| 3 | Nemotron 3 Super 120B | OpenRouter | 1M context |
| 4 | OpenAI GPT-OSS 120B | OpenRouter | Strong reasoning |
| 5 | Nemotron 3 Ultra 550B | OpenRouter | Largest free model with tools |
| 6 | Gemini 2.0 Flash | Fast, strong coding β needs GOOGLE_API_KEY |
|
| 7 | Ornith Agent | Llama.cpp | Local offline model β no API key needed |
Auto-routes (
/model auto/coding,/model auto/fast, etc.) intelligently select the best available model based on quality tiers and API keys. Edit priorities inroute-presets.json.
Groq (fastest):
/add 10 groq:openai/gpt-oss-120b # 120B, 500 t/s
/add 11 groq:llama-3.3-70b-versatile # 70B, 280 t/s
Mistral:
/add 12 mistral:codestral-latest # Dedicated coding model
/add 13 mistral:mistral-large-latest # Best quality
Google:
/add 14 google:gemini-2.0-flash-exp # Fast, good coding
Note: presets 6-7 are reserved for built-in Google Gemini and local offline models. User presets start at 8+ by convention.
You: /model auto/coding
β
Switched to Auto (Coding) β automatically picks best available model
You: create a folder named demo and write a hello.py
β³ Thinking... [Model: openai/gpt-oss-120b:free]
π§ create_folder({"path":"demo"})
π§ write_file({"path":"demo/hello.py","content":"print('Hello, world!')\n"})
Agent: Done! Created demo/hello.py with a Hello World script.
You: run the file
π§ run_command({"command":"python demo/hello.py"})
Agent: Hello, world! β the script runs correctly.
You: /model 6
β
Switched to preset 6: [Groq] openai/gpt-oss-120b
(now using Groq β same model, 500 t/s)
| Error | Likely Cause | Fix |
|---|---|---|
403 Forbidden |
API key missing or invalid | Check .env has the right key |
429 Rate limit |
Free tier daily limit hit | Wait or use auto-fallback. Manual: /model <n> |
Agent stopped: stuck detected |
Same tool called 3Γ+ consecutively | Recovery message injected automatically |
All 3 attempts failed |
Model unreachable or too slow | Try smaller model or local model |
400 not a valid model |
Model name changed/deprecated | Auto-corrected via discovery module β or run /discover + /add <n> provider:new-model |
tool_calls empty arguments |
Model doesn't support tool calling | Use a different model |
ENOTFOUND / ECONNREFUSED |
Internet restrictions or proxy needed | Enable VPN/proxy or use local models |
Request timed out (120s) |
Cloud timeout too short for response | Use local model or provider with faster response |
Request timed out (600s) |
Local model too slow on this hardware | Increase LOCAL_TIMEOUT in .env |
Quick checks: /list-providers β shows configured keys. /safe β toggle safe mode. npm run setup β re-run wizard.
- System prompt adherence: Some free models may ignore or partially follow system instructions
- Rate limits: Free-tier API keys have daily limits. Retry with backoff (max 3 attempts)
- Token window: With 128K context and 20-exchange window, large codebases may hit limits. Increase
MAX_EXCHANGESandMAX_TOOL_RESULT_LENGTH - Stuck detection: Stops after 3Γ identical or 5Γ consecutive tool calls β rephrase your request to continue
- Windows shell: PowerShell pipeline operators may trigger permission prompts under strict rules
- LSP availability: Requires the LSP server binary to be installed (e.g.,
typescript-language-server,pyright) - MCP servers: Some servers require internet (GitHub API, etc.) and proper configuration
- All file operations restricted to
ALLOWED_DIRβ path traversal prevented - Shell commands run inside the workspace directory
- API keys stored in
.env(gitignored, never committed) - Safe mode (
/safe) restricts commands to a whitelist - Dangerous commands blocked by denylist (
rm -rf,dd,mkfs,wget, etc.)
For medium-to-large projects, increase in .env:
MAX_EXCHANGES=50
MAX_TOOL_RESULT_LENGTH=20000Reset mid-session with /reset if context gets stale.
π‘ New to Coding Agent Free? Check the Comprehensive User Guide for step-by-step tutorials, 5 hands-on example projects, and a complete walkthrough from beginner to advanced.
npm run test:unitβ 334 unit tests (19 files)npm run test:integrationβ 26 provider integration testsnpm testβ 35 integration tests (provider connectivity)- CI:
.github/workflows/ci.ymlruns all tests on Windows (Node 22) β Linux/macOS also supported but tested manually
Contributions welcome! Open an issue or submit a pull request. Star the repo if you find it useful.
MIT