Forge-delegate
Allows Google models authenticated in opencode to be used as delegation or second-opinion targets.
Enables delegating coding tasks to local Ollama models without API keys, using models such as ollama:llama3 or local:qwen2.5-coder.
Enables delegation and second-opinion requests to OpenAI models through opencode logins or direct API access, returning model output with usage and cost details.
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 usageQuick 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 atdocs/index.html.install.sh'sFORGE_DELEGATE_REPOdefault (and the raw URL inside it) matters only if you self-host the fallback installer.Working on a checkout yourself?
node cli.mjs setupdoes the same thing.
setup will:
Register the MCP server with each agent you chose (
--targets claude,codex,opencode).Set your default model (
--model) so calls can omitmodel.Install the auto-update launcher (published installs; skipped for a git checkout).
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 runprint 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
| Claude Code | Codex | opencode |
|
|
|
|
|
|
|
|
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>.
Related MCP server: GPT Proxy MCP Server
Tools
Tool | What it does | Context cost |
| Second opinion from another model (direct API, no file access) | Small |
| Model works autonomously via opencode's own tool loop — inline by default; | Tiny→Medium |
| Poll a background job (or list all with no id) | Tiny |
| List local/keyless, direct-API, and agentic models | Small |
| Read current configuration (default model, directory, autoApprove, profiles) | Tiny |
| 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:
From your agent via the MCP tools
get_delegate_config/set_delegate_config.Terminal CLI:
forge-delegate config get,forge-delegate config set --model <m> --timeout <s> --dir <path> --autoApprove false,forge-delegate config path.setupflags:--model,--targets,--scope,--project-dir.Edit the file directly.
Field | Description | Default |
| provider/model used when a call omits | unset |
| opencode agent used for delegations | unset |
| default reasoning-effort variant | unset |
| auto-approve permissions so headless delegations don't block |
|
| per-delegation timeout |
|
| default working directory for delegations | unset (server cwd) |
| named presets |
|
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 viaopencode auth login <provider>.Direct API from opencode logins —
provider/modelfor OpenAI-compatible providers.Custom providers — OpenAI-compatible providers defined in
opencode.json(@ai-sdk/openai-compatible+baseURL), callable asprovider/model.Ollama (local) —
ollama:llama3,local:qwen2.5-coder, no key needed.
Safety notes
autoApprove: trueruns delegations non-interactively with tool permissions granted — point them at repositories you trust and review the diffs. SetautoApprove: falseto 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; seeforge-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 statisticssetup 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:
npm run prepublishOnly— syntax-checks all entry files (runs automatically on publish).npm pack --dry-run— confirm the tarball contains onlylauncher.mjs,cli.mjs,server.mjs,lib.mjs,install.sh,docs/,skills/,README.md(via thefilesfield), notnode_modules.Bump
versioninpackage.json(and the rootversioninpackage-lock.json).npm login && npm publish— thebinfield makesnpx forge-delegate …work.
Also make sure the GitHub repo exists at MuhamadBarzani/forge-delegate with Pages enabled on
/docs (configurator) — the raw.githubusercontent.com install URL and the configurator's
hardcoded URL point there.
License
MIT
Available Tools
6 toolsask_modelA
Get a second opinion from a different model — on a design, an approach, or a tricky snippet — or ask one when the user requests it. Sends a one-shot prompt over a direct API call and returns the raw response. The model has no file access and cannot take actions; for anything touching files use delegate. Don't use it for syntax or API details you already know: a cheap model is usually less reliable than you on those. Omit model to use the configured default.
Inputs: prompt (required), model, system.
check_delegationA
Check a delegation started with background:true. Returns RUNNING, DONE or TIMED OUT, the elapsed time, the session id, and the last 8,000 characters of the agent's output. Each poll costs context, so wait between polls instead of checking in a tight loop. Call with no id to list all jobs.
Inputs: id.
delegateA
Hand a coding task to another AI model running as a full agent via local opencode: it reads the project, explores, and writes the code in its own tool loop, none of which enters your context. Use it instead of writing the code yourself for: tests for code that already exists; a mechanical refactor (rename, signature change, import rewrite, API migration); lint/type/build errors (paste the error output); boilerplate or scaffolding (CRUD endpoints, config, schemas, adapters, fixtures); a port between languages or frameworks; the same edit repeated across 3 or more files; reading a large file or directory to answer one narrow question; the survey half of an audit. Runs inline by default and returns when done; Claude Code backgrounds calls past 2 minutes, other hosts wait. Pass background:true to get a job id at once, then poll check_delegation. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Name file paths in task; never paste their contents. model/directory/agent/autoApprove default from config — omit them. Review what comes back before reporting it done.
Inputs: task (required), agent, files, model, +5 more.
get_delegate_configA
Read the current forge-delegate configuration: defaultModel, defaultAgent, defaultVariant, autoApprove, timeoutMs, defaultDirectory, and named profiles — plus the installed version and whether it updates automatically. Call this to see what will be used when a model/directory is omitted, or when the user asks which version is running.
Inputs: no named parameters.
list_modelsA
List the models available for delegation: local/keyless ones, direct-API models from opencode logins, and agentic models from the local opencode installation. Call it when the user asks what's available or wants to change the default model, not before an ordinary delegation — those use the configured default.
Inputs: no named parameters.
set_delegate_configA
Change forge-delegate configuration at runtime — no reinstall. Only change settings when the user asks; never raise defaultModel to a premium tier on your own. Pass any subset of {defaultModel, defaultAgent, defaultVariant, autoApprove, timeoutMs, defaultDirectory, profiles}. Set a field to null to clear it. To edit a profile, pass the whole profiles object (e.g. profiles: {tests: {model: "..."}}); set a profile to null to delete it. Only provided keys change; others are preserved.
Inputs: profiles, timeoutMs, autoApprove, defaultAgent, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a sharply bounded purpose: ask_model is a stateless one-shot API call, delegate is a full agentic loop with file access, and the descriptions explicitly steer the agent between them ('for anything touching files use delegate'). Config read/write (get_delegate_config vs set_delegate_config), model discovery, and job polling are all cleanly separated.
Five of six names follow a clear verb_noun snake_case pattern (ask_model, list_models, set_delegate_config, get_delegate_config, check_delegation). The exception is the bare verb 'delegate', which breaks the pattern but is still unambiguous.
Six tools is well-scoped for a delegation server: one dispatch path, one async-poll path, one second-opinion path, and read/write config plus model listing. Nothing looks redundant or padded.
The lifecycle is largely covered — configure, discover models, delegate (inline or background), poll, and consult a second model. The notable gap is the inability to cancel or kill a running background job, so a runaway delegation can only be waited out.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Hosted X Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted OpenAI Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that allows Claude Code to interact with the OpenAI Codex CLI.40 npm20MIT
- AlicenseBqualityDmaintenanceMCP server that proxies GPT API calls for Claude Code, supporting multiple GPT models with both standard and streaming responses.2MIT
- AlicenseAqualityBmaintenanceMCP server for opencode that queries GitHub Copilot models via a persistent opencode server, requiring no API keys.288 npm3MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that lets Claude Code offload simple tasks like code explanation, writing tests, and adding comments to a local Ollama model, saving Claude API tokens.-