Delegates Claude Code subagent tasks like refactoring and bug fixes to cheaper opencode models while maintaining native tool parity.
Also known as sebstaq/opencode-subagent-mcp, opencode-subagent-mcp
- Stars
- 2
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.1.4
- Last commit
- Nov 3, 2026
- License
- MIT
What is opencode subagents MCP?
opencode subagents delegates Claude Code subagent tasks like refactoring and bug fixes to cheaper opencode models while maintaining native tool parity. It exposes 5 tools, such as agent, send_message, wait.
Summary generated from the project's README
About opencode subagents MCP server
Delegating heavy lifting like refactoring, bug fixes, and research to cheaper models while keeping your main Claude Code session connected to Anthropic is what this MCP server enables. It allows developers to run subagent tasks using opencode models, such as deepseek-v4.1-flash, which cost significantly less than Opus or Sonnet. The server operates as a stdio MCP server that manages a private opencode serve instance on a local port to execute these delegated tasks.
Users set this up by installing it as a Claude Code plugin or a plain MCP server using npx. It requires Node 22+, git, and a logged-in opencode CLI. The server maintains parity with native Claude Code features, including worktree isolation, permission prompts, and the ability to resume tasks via send_message. It respects your existing .claude/agents definitions and permission rules to ensure that background agents and structured outputs function as expected within your local development environment.
What you can do with it
- 1Reduce costs for repetitive tasksHand off time-consuming refactoring or testing tasks to a more economical model provider.
- 2Isolate agent work in git worktreesRun subagents in a dedicated git worktree to prevent them from affecting your main working directory.
- 3Resume interrupted agent sessionsContinue a task that was previously finished or interrupted by using the full conversation history.
- 4Manage background agent executionTrigger a long-running agent to run in the background and wait for its completion notification.
Written from the project's README. Every use case is checked against a quote from it.
How to install opencode subagents MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall opencode subagents MCP in Claude Code
$ claude mcp add opencode-subagent-mcp -- npx -y opencode-subagent-mcpInstall opencode subagents MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"opencode-subagent-mcp": {
"command": "npx",
"args": [
"-y",
"opencode-subagent-mcp"
]
}
}
}Install opencode subagents MCP in VS Code
.vscode/mcp.json
{
"servers": {
"opencode-subagent-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"opencode-subagent-mcp"
]
}
}
}Install opencode subagents MCP in VS Code CLI
$ code --add-mcp '{"name":"opencode-subagent-mcp","type":"stdio","command":"npx","args":["-y","opencode-subagent-mcp"]}'Install opencode subagents MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"opencode-subagent-mcp": {
"command": "npx",
"args": [
"-y",
"opencode-subagent-mcp"
]
}
}
}Install opencode subagents MCP in Codex
$ codex mcp add opencode-subagent-mcp -- npx -y opencode-subagent-mcpInstall opencode subagents MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.opencode-subagent-mcp] command = "npx" args = ["-y", "opencode-subagent-mcp"]
Install opencode subagents MCP in Gemini CLI
$ gemini mcp add -s user opencode-subagent-mcp npx -- -y opencode-subagent-mcpInstall opencode subagents MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"opencode-subagent-mcp": {
"command": "npx",
"args": [
"-y",
"opencode-subagent-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for opencode-subagent-mcp 0.1.4 in an isolated container with no network and no keys. It answered and listed 5 tools.
opencode subagents MCP tools 5
Read from the server with tools/listagentLaunch a subagent that runs on an opencode model (default opencode-go/deepseek-v4.1-flash) in the current project. Mirrors the built-in Agent tool: give a self-contained task prompt; the agent starts with no conversation context and returns only its final report. subagent_type accepts Claude agent definitions from .claude/agents/ (their prompt, tools, permissionMode and maxTurns apply) or opencode agents (general, explore, plan, build). isolation 'worktree' runs it in a temporary git worktree off the default branch, removed if unchanged. The call blocks until the agent finishes (it is backgrounded automatically after a while); set run_in_background to return at once and collect the result with wait.
send_messageSend a follow-up message to a finished opencode subagent by agent_id. It resumes with its full previous history (and its worktree, if one was kept) and returns its new final report. Also works for agent_ids from before a restart of the MCP server or Claude Code session, and for agents that were interrupted by such a restart.
waitWait for a background opencode subagent and return its result. agent_ids from before a restart of the MCP server still work.
stopAbort a running opencode subagent. Returns what it produced so far. agent_ids from before a restart of the MCP server still work.
listRead-onlyList this session's opencode subagents and the available agent types. It shows agents started or used since this MCP server started; agents from before a restart are not listed but their agent_id still works with wait, send_message and stop.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesebstaq/opencode-subagent-mcp is public and reachablegithub.com/sebstaq/opencode-subagent-mcp ↗Pass
- Package names this repository as its sourceopencode-subagent-mcp names sebstaq/opencode-subagent-mcp as sourcenpmjs.com/package/opencode-subagent-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for opencode-subagent-mcpnpmjs.com/package/opencode-subagent-mcp/v/0.1.4#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/sebstaq/opencode-subagent-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from opencode-subagent-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubopencode-subagent-mcp
Run Claude Code subagents on cheaper opencode models — for example
opencode-go/deepseek-v4.1-flash (DeepSeek) from an opencode Go subscription — while Claude
Code itself keeps talking to Anthropic directly. Delegate searches, refactors, bug fixes, tests
and research to a model that costs a fraction of Opus or Sonnet, and keep the tools you already
use: background agents, resume via send_message, worktree isolation, .claude/agents
definitions, permission prompts and structured output.
It is a stdio MCP server. Your main Claude Code session is not proxied or routed
anywhere; the server only runs the subagents you delegate to it, on a private
opencode serve instance it starts itself.
Install
Requires Node 22+, git, and the opencode CLI logged in to the
providers you want (opencode auth login).
As a Claude Code plugin (also adds a skill that tells Claude when to delegate to opencode):
claude plugin marketplace add sebstaq/opencode-subagent-mcp
claude plugin install opencode-subagent-mcp@sebstaq-opencode
Or as a plain MCP server:
claude mcp add -s user opencode -- npx -y opencode-subagent-mcp@0.1.4
What it runs and sends
- It starts a private
opencode serveprocess on a random localhost port with a random password, and stops it when Claude Code exits. The password is generated for each run and only used between this server and that local process. The process inherits your environment so opencode can use the provider logins and API keys you already configured for it; this server never reads, stores or sends those credentials itself. - The prompts you delegate, and the files and command output the subagent reads, go to the model provider you choose through opencode (by default opencode Go), under that provider's data retention terms. opencode keeps session history in its local database on your machine. Nothing else is sent anywhere; the server has no telemetry and makes no other network calls.
- It reads
~/.claude/settings.json, the project's.claude/settings.jsonand.claude/settings.local.json, and.claude/agents/*.md(user and project) to mirror your permission rules and agent definitions, and~/.config/opencode-subagent-mcp/config.jsonif present. - With
isolation: "worktree"it creates git worktrees under the project's.claude/worktrees/and removes them when they have no changes.
This is an independent project, not affiliated with Anthropic or the opencode team.
Tools
| Tool | Native equivalent | What it does |
|---|---|---|
agent |
Agent tool | Run a subagent; returns its final report, usage and worktree outcome |
send_message |
SendMessage | Continue a finished agent with its full history; also after a restart |
wait |
background completion notification | Collect a run_in_background agent (optionally with a timeout) |
stop |
TaskStop | Abort a running agent and return what it produced |
list |
/agents | This session's agents, Claude agent definitions and opencode agents |
An agent_id keeps working after the MCP server or Claude Code restarts: wait and stop
return what happened to it, and send_message continues it. Agents from before a restart do not
appear in list until their id is used again, but they still exist in opencode's local session
store.
agent parameters: description, prompt, subagent_type, model, isolation: "worktree",
permission_mode, tools, disallowed_tools, max_turns, effort, output_schema,
run_in_background, cwd.
Parity with native subagents
| Native behaviour | Here |
|---|---|
| Fresh context, only the final message comes back | Same. Long output is truncated (maxResultChars) with the full text written to a file |
| Runs in the project directory | Same (cwd from MCP roots, then CLAUDE_PROJECT_DIR, then the server's cwd) |
isolation: worktree |
Same layout (.claude/worktrees/<name>, branch worktree-<name>, based on the default branch). Removed when unchanged, kept with commit/file summary otherwise. Outside paths are denied |
| Permission prompts surface in the main session | opencode ask rules are shown as MCP elicitation dialogs (allow once / always / deny, with optional feedback) |
| Permission modes | default, acceptEdits, auto, bypassPermissions, plan mapped to opencode rules; your Claude permissions.allow/ask/deny from user, project and local settings apply |
| Background agents with completion notification | Claude Code moves long MCP calls to the background automatically and notifies when they finish; run_in_background + wait for explicit control |
| Resume with full history | send_message (also works for agents from earlier sessions or after a restart, since opencode persists them) |
.claude/agents/*.md definitions |
Used via subagent_type: prompt, tools, disallowedTools, permissionMode, maxTurns, effort, isolation. model applies only when it is an opencode provider/model |
maxTurns returns partial output |
Same; status max_turns, resumable |
| Progress in the UI | Tool calls are sent as MCP progress notifications |
| Subagents cannot spawn subagents or ask the user questions | opencode's task and question tools are disabled |
| Structured output | output_schema (JSON Schema) → opencode structured output, returned as structuredContent |
Known gaps: agents do not appear in Claude Code's /tasks agent view; there is no
fork-with-parent-context; the Workflow tool's agent() cannot target them; auto mode has no
safety classifier (it allows everything, including paths outside the project, except rules
you configured and a fixed list of destructive commands that ask: rm -r/-rf, git push --force, git reset --hard, git clean -f, git restore/git checkout --, curl | sh,
sudo, chmod -R/chown -R, dd, mkfs, npm/pnpm publish; opencode matches each
command in a chain separately); the parent's permission mode is not visible to MCP servers, so
the default comes from config; hooks, skills preloading, memory and per-agent MCP servers are not mapped.
Steering Claude
Claude Code picks between its native Agent tool and this one on its own, so routing is
unpredictable. To make opencode the default for delegated work that is cheap to verify, paste the snippet from docs/claude-md-snippet.md into
your global ~/.claude/CLAUDE.md.
Configuration
Optional ~/.config/opencode-subagent-mcp/config.json (or $OPENCODE_SUBAGENT_CONFIG):
{
"defaultModel": "opencode-go/deepseek-v4.1-flash",
"defaultPermissionMode": "auto",
"pure": true,
"opencodeBin": "opencode",
"maxConcurrent": 8,
"maxResultChars": 80000
}
OPENCODE_SUBAGENT_MODEL and OPENCODE_SUBAGENT_MODE override the first two. pure starts
opencode without external plugins.
How it works
On first use the server starts opencode serve on a random loopback port with a random
password, subscribes to its event stream, and drives one opencode session per agent
(agent id = session id). Permission requests from opencode are answered through MCP
elicitation. The opencode process is stopped with the MCP server; leftovers from crashed
servers are reaped on the next start.
Development
pnpm check # typecheck, lint, format check, unit tests
pnpm smoke [provider/model] # end-to-end run against a real model in a temp repo
License
MIT
opencode subagents MCP questions
How do I add opencode subagents MCP to Claude Code?
Run claude mcp add opencode-subagent-mcp -- npx -y opencode-subagent-mcp in your terminal. Add --scope user to make it available in every project.
How do I add opencode subagents MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does opencode subagents MCP provide?
It exposes 5 tools, including agent, send_message, wait, stop, list.
Does this proxy my main Claude Code session?
No, your main Claude Code session is not proxied or routed anywhere; the server only runs the subagents you delegate to it.
How are my credentials handled?
The server does not read, store, or send your credentials; it uses the environment and provider logins you have already configured for the opencode CLI.
Can I resume a finished agent?
Yes, you can continue a finished agent with its full history using the send_message tool.
Does it support git worktrees for isolation?
Yes, when isolation is set to worktree, it creates git worktrees under the project's .claude/worktrees/ directory.