forge-delegate

MCP server that delegates coding work from your primary agent (Claude Code, Codex, or opencode) to other AI models, so your main agent's context stays small. The high-volume typing happens in another model's context, usually a cheaper or free one, and only a summary comes back. Full agentic delegation via opencode for real work; direct API calls for second opinions.

Your main agent (the expensive one) keeps architecture, critical logic, and hard decisions. The cheap model grinds through the high-volume, low-risk work (boilerplate, repetitive edits, tests, lint/type fixes) and reports back.

┌──────────────────┐   MCP (stdio)   ┌──────────────────┐   opencode run   ┌──────────────────┐
│ Claude / Codex / │ ──────────────► │ forge-delegate   │ ───────────────► │ opencode + cheap  │
│ opencode (primary)│                │  (this server)   │    --model cheap │      model        │
└──────────────────┘ ◄────────────── └──────────────────┘ ◄─────────────── └──────────────────┘
        result: text + session + token usage

Quick start

Web configurator — pick model/targets/scope and get a ready-to-paste command (https://muhamadbarzani.github.io/forge-delegate/). The model picker is backed by the live models.dev catalog — searchable, with free/cheap filters and real prices, so you're picking from actual available models rather than guessing.

npx (recommended — works everywhere, no bash needed):

npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex,opencode"

That's it — npx bootstraps the package, and setup registers the MCP server with the agents you chose, sets your default model, and installs a small launcher that keeps the server up to date. Works on Windows (cmd/PowerShell), macOS, and Linux — no bash needed.

Run setup without flags and it walks you through the choices interactively (defaults in [brackets], Enter accepts). For the default model it lists every model your opencode can run and you pick one by number or name; pass any of the flags to skip that prompt. In an automated/non-terminal run it just uses sensible defaults.

GitHub Pages: enable it with Settings → Pages → Deploy from a branch → main / /docs. The configurator lives at docs/index.html. install.sh's FORGE_DELEGATE_REPO default (and the raw URL inside it) matters only if you self-host the fallback installer.

Working on a checkout yourself? node cli.mjs setup does the same thing.

setup will:

1. Register the MCP server with each agent you chose (--targets claude,codex,opencode).
2. Set your default model (--model) so calls can omit model.
3. Install the auto-update launcher (published installs; skipped for a git checkout).
4. For Codex, raise the MCP timeouts (startup_timeout_sec, tool_timeout_sec) above Codex's 10s/60s defaults so inline delegations aren't cut off.

Routing and cost-policy guidance is injected by the MCP server itself into the agent's context via MCP instructions — no memory-file (CLAUDE.md/AGENTS.md) editing needed.

Then restart your agent and confirm the server is connected: /mcp in Claude Code, codex mcp, or opencode.

What you need

• Node.js ≥ 18 and opencode v2 or newer installed (the installer can fetch opencode for you). v2 removed the CLI flags older versions relied on for working directories and variants, and an unknown flag makes opencode run print help and exit successfully — so a pre-v2 binary fails silently. The server checks at startup and warns instead.
• Free opencode/* models (e.g. opencode/deepseek-v4.1-flash-free) need no auth — zero setup.
• Any other provider (deepseek, openai, google, ollama, …) must be logged into your opencode first — that's a step you do in your own opencode, not something forge-delegate handles: opencode auth login <provider>. forge-delegate reuses your opencode's credentials and never stores API keys. (Ollama needs no key, just the Ollama app running.)

Windows

Use the npx route — no bash needed (works in cmd/PowerShell). All three targets, including native Windows Codex CLI, are supported.

Scope

| --scope | Claude Code | Codex | opencode | |---|---|---|---| | user (default) | ~/.claude.json — all projects | ~/.codex/config.toml — all projects | ~/.config/opencode/opencode.json — all projects | | project | .mcp.json in the project (needs one-time approval) | .codex/config.toml in the project (loads for trusted projects only) | opencode.json in the project |

Try it free — zero signup

opencode ships free no-auth models under opencode/:

npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex"

Other free options: opencode/mimo-v2.6-flash-free, opencode/nemotron-3.5-lightning-free. Free tiers are rate-limited; switch anytime with forge-delegate config set --model <m>.

Tools

| Tool | What it does | Context cost | |---|---|---| | ask_model | Second opinion from another model (direct API, no file access) | Small | | delegate | Model works autonomously via opencode's own tool loop — inline by default; background:true returns a job id to poll via check_delegation | Tiny→Medium | | check_delegation | Poll a background job (or list all with no id) | Tiny | | list_models | List local/keyless, direct-API, and agentic models | Small | | get_delegate_config | Read current configuration (default model, directory, autoApprove, profiles) | Tiny | | set_delegate_config | Change configuration at runtime — no reinstall | Tiny |

delegate is the context-saver: the external model gets its own tool loop executed by opencode locally. File contents never touch your main agent's context. Fast tasks return inline; long ones are auto-backgrounded by Claude Code (past ~2 min). Other hosts wait for an inline call, so the agent is told to pass background:true there for anything long.

Each delegation's result ends with the tokens it used and, when the provider reports prices, its cost. forge-delegate stats totals both per model.

When to delegate

| ✅ Delegate — high volume, low risk | ⛔ Keep on the primary agent | |---|---| | Tests for well-specified behavior | Architecture, system design, choosing abstractions | | Boilerplate & scaffolding (CRUD, DTOs, fixtures, mocks) | Security-sensitive code (auth, crypto, secrets, permissions) | | Mechanical edits across many files (renames, prop propagation, imports) | Concurrency, performance-critical paths, subtle correctness | | Lint / formatting / type-error fixes | Ambiguous / underspecified requirements needing judgment | | Docstrings, comments, README / changelog sections | Public API / interface design, breaking changes | | Straightforward data transforms / migrations with a clear spec | Debugging unknown root causes | | Obvious glue code / format conversions | Anything costly or hard to detect if wrong |

Full guide: docs/DELEGATION.md

The delegate-work skill

Setup also installs the skill for Claude Code (~/.claude/skills/delegate-work/, or <project>/.claude/skills/ under --scope project) and for Codex (~/.agents/skills/delegate-work/, or <project>/.agents/skills/). Skip it with --no-skill.

It exists because MCP server instructions are injected once at session start and get buried as the context fills — by turn 30 they lose to whatever is in front of the model. A skill description is re-matched against every user turn, so the delegation triggers ("write tests for", "rename X everywhere", "fix the lint errors") stay live for the whole session instead of decaying.

Configuration

Stored in ~/.forge-delegate/config.json, read fresh on every call — change it anytime without reinstalling. Four ways:

1. From your agent via the MCP tools get_delegate_config / set_delegate_config.
2. Terminal CLI: forge-delegate config get, forge-delegate config set --model <m> --timeout <s> --dir <path> --autoApprove false, forge-delegate config path.
3. setup flags: --model, --targets, --scope, --project-dir.
4. Edit the file directly.

| Field | Description | Default | |---|---|---| | defaultModel | provider/model used when a call omits model | unset | | defaultAgent | opencode agent used for delegations | unset | | defaultVariant | default reasoning-effort variant | unset | | autoApprove | auto-approve permissions so headless delegations don't block | true | | timeoutMs | per-delegation timeout | 900000 (env FORGE_OPENCODE_TIMEOUT) | | defaultDirectory | default working directory for delegations | unset (server cwd) | | profiles | named presets { name: { model, agent, variant, autoApprove, directory } } | {} |

Every delegation tool also accepts per-call model, directory, agent, autoApprove, and profile overrides. Per-call values beat profile values beat config defaults.

Models

• opencode provider — free no-auth models (opencode/deepseek-v4.1-flash-free, ...) plus anything you have logged in via opencode auth login <provider>.
• Direct API from opencode logins — provider/model for OpenAI-compatible providers.
• Custom providers — OpenAI-compatible providers defined in opencode.json (@ai-sdk/openai-compatible + baseURL), callable as provider/model.
• Ollama (local) — ollama:llama3, local:qwen2.5-coder, no key needed.

Safety notes

• autoApprove: true runs delegations non-interactively with tool permissions granted — point them at repositories you trust and review the diffs. Set autoApprove: false to require manual approval.
• This server never stores API keys — provider auth lives in opencode's own auth store.
• Usage is logged to ~/.forge-delegate/usage.jsonl; see forge-delegate stats.

CLI

forge-delegate --version  Print the installed version
forge-delegate setup      Register with Claude Code / Codex / opencode
forge-delegate serve      Start the MCP server (used internally)
forge-delegate config     get | set | path
forge-delegate status     Show version, update mode, opencode logins, usage
forge-delegate stats      Show detailed usage statistics

setup on a published install writes ~/.forge-delegate/launcher.mjs and registers that path instead of npx. The launcher keeps a private install under ~/.forge-delegate/pkg, asks npm for the newest release at most every 6 hours, and installs newer same-major versions automatically. Installs use npm install --ignore-scripts, go through a staging directory, and fall back to the last good version if anything fails. A new version lands on the next agent start; the download itself happens in the background so startup is never delayed.

Disable automatic updates with FORGE_AUTO_UPDATE=0. A major release (2.0.0) is never installed automatically — re-run npx -y forge-delegate setup to take it deliberately.

The launcher is also the CLI entry point: node ~/.forge-delegate/launcher.mjs status reports the running version and update mode, and --version prints the version.

npx installs configured by hand are not covered by the launcher: npx keeps its cached copy forever, so clear it with rm -rf ~/.npm/_npx and restart. Running npx -y forge-delegate@latest setup migrates an npx install to the launcher; @latest gets its own npx cache slot, and if it still starts an old version, clear the cache first.

Publishing (npm)

The primary install is npx -y forge-delegate setup, so the package must be on npm. Checklist:

1. npm run prepublishOnly — syntax-checks all entry files (runs automatically on publish).
2. npm pack --dry-run — confirm the tarball contains only launcher.mjs, cli.mjs, server.mjs, lib.mjs, install.sh, docs/, skills/, README.md (via the files field), not node_modules.
3. Bump