Skip to content

Repository files navigation

Coding Agent Free

Stars License Last Commit TypeScript CI
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.


🧠 Why Coding Agent Free?

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

Key Features

  • 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_hover tools. Supports TypeScript, JavaScript, Python (pyright), Rust (rust-analyzer), Go (gopls). /lsp toggle
  • 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) and plan (read-only) modes manually via /mode or let the agent auto-switch via switch_mode tool. Plan mode filters write/edit/run tools; agent can escalate autonomously
  • @explore subagent β€” 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 via route-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 /discover command and GET /api/discover endpoint
  • 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 setup interactively 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.md in 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_log built-in tools for source control operations
  • Docker sandbox β€” optional isolation; set DOCKER_SANDBOX_ENABLED=true to 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)

πŸ› οΈ Requirements & Installation

Prerequisites

  • 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

Quick Install

git clone https://github.com/maz557/coding-agent-free.git
cd coding-agent-free
npm install

Setup

Option A β€” Interactive wizard (recommended):

npm run setup

The 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 models

Option 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 6

Standalone Binary (no Node.js)

Build 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 helper

IDE Integration

npm run setup-ide

Configures Cline, Continue.dev, and Cursor to use the local API proxy at http://localhost:3000/v1/chat/completions.

Environment Variables

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.

User Configuration (.env)

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.

Docker Sandbox

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.

User Presets (presets.json)

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.

Project Structure

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

πŸ“– Usage Guide

⌨️ CLI Interface

npm start

On Windows, double-click run-cli.bat. For RTL languages (Persian, Arabic, Urdu), use run-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.

🌐 Web Interface

npm run web
# Open http://localhost:3000 in your browser

On 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]       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Available Tools

Built-in Tools (always available)

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

LSP Tools (toggle with /lsp)

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)

MCP Tools (from connected servers)

Tools from connected MCP servers appear automatically alongside built-in tools. See MCP section.

Commands

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

🧩 MCP (Model Context Protocol)

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:

  1. Install an MCP server: npm install -g @modelcontextprotocol/server-filesystem
  2. Add to .coding-agent.json:
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
        }
      }
    }
  3. 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.js for a minimal example.

πŸ”¬ LSP (Language Server Protocol)

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.

Multi-Provider & Auto-Routing

# 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 10

Auto-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.

Local Models

No API key required. The model must support tool calling (function calling).

Three server options β€” llama.cpp recommended for large-context agent work:

Llama.cpp (recommended)

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.2 or Qwen2.5 instruct 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

Changing the default local model

If you want auto/offline (or the fallback chain) to use your model automatically, edit:

  1. route-presets.json β€” change the offline.presets and/or coding.presets / reasoning.presets entries. Each entry is provider:model:
    "offline": { "presets": ["llamacpp:MyModel"], "minQuality": "low" }
  2. .env β€” set timeout and server URL for your hardware:
    LOCAL_TIMEOUT=600000
    LLAMACPP_HOST=http://localhost:8080/v1
  3. presets.json (built-in defaults, overridden by route-presets.json) β€” change preset entries if you rebuild with npm 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.

Other backends

# 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:auto

Workspace & Permissions

By default, the agent can only access files inside ./workspace. Change with:

  • ALLOWED_DIR=. in .env (access everything)
  • /allow "C:\path" during a session (temporary)

Built-in Presets

# 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 Google 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 in route-presets.json.

Recommended Free Coding Models

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.

Example Interactions

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)

Troubleshooting

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.

Limitations

  • 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_EXCHANGES and MAX_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

Security

  • 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.)

Large Projects

For medium-to-large projects, increase in .env:

MAX_EXCHANGES=50
MAX_TOOL_RESULT_LENGTH=20000

Reset 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.

Tests

  • npm run test:unit β€” 334 unit tests (19 files)
  • npm run test:integration β€” 26 provider integration tests
  • npm test β€” 35 integration tests (provider connectivity)
  • CI: .github/workflows/ci.yml runs all tests on Windows (Node 22) β€” Linux/macOS also supported but tested manually

Contributing

Contributions welcome! Open an issue or submit a pull request. Star the repo if you find it useful.

License

MIT

Releases

Packages

Contributors

Languages