opencode subagents

io.github.sebstaqPublished by GitHub account sebstaqv0.1.4Updated Nov 4, 2026

Run Claude Code subagents on cheaper opencode models (DeepSeek, opencode Go) with native parity.

VerifiedSTDIODesktop onlyDeveloper ToolsAI & ML

Overview

AI-generated overview

Runs Claude Code subagents on cheaper opencode models such as DeepSeek, with agent, send_message, wait, stop and list tools that mirror the native Agent tool.

What you can do
  • Launch subagents on an opencode model with a self-contained prompt; only the final report comes back
  • Continue a finished agent with its full history, including after a restart
  • Wait for or abort background agents and collect partial results
  • List this session's agents and the available agent types
  • Mirror native behaviour: worktree isolation, permission modes, .claude/agents definitions, structured output
When to use it
Useful when you want to delegate cheap-to-verify work such as searches, refactors, bug fixes, tests or research to a lower-cost model while the main Claude Code session keeps talking to Anthropic directly.
Requirements
Local stdio process installed via npm (npx) or as a Claude Code plugin. Needs Node 22+, git, and the opencode CLI logged in to the providers you want (opencode auth login). Optional config file or OPENCODE_SUBAGENT_CONFIG, OPENCODE_SUBAGENT_MODEL and OPENCODE_SUBAGENT_MODE variables.
Before you install
Delegated prompts and the files and command output the subagent reads go to the chosen model provider under its data retention terms. The opencode process inherits your environment, so configured provider logins and API keys are available to it. Subagents can edit files and run commands; auto mode allows everything except configured rules and a fixed list of destructive commands, so review permission settings.

Installation

In SourceWeft

  1. Open opencode subagents in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

opencode-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):

sh
claude plugin marketplace add sebstaq/opencode-subagent-mcpclaude plugin install opencode-subagent-mcp@sebstaq-opencode

Or as a plain MCP server:

sh
claude mcp add -s user opencode -- npx -y [email protected]

What it runs and sends

  • It starts a private opencode serve process 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.json and .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.json if 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

ToolNative equivalentWhat it does
agentAgent toolRun a subagent; returns its final report, usage and worktree outcome
send_messageSendMessageContinue a finished agent with its full history; also after a restart
waitbackground completion notificationCollect a run_in_background agent (optionally with a timeout)
stopTaskStopAbort a running agent and return what it produced
list/agentsThis 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 behaviourHere
Fresh context, only the final message comes backSame. Long output is truncated (maxResultChars) with the full text written to a file
Runs in the project directorySame (cwd from MCP roots, then CLAUDE_PROJECT_DIR, then the server's cwd)
isolation: worktreeSame 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 sessionopencode ask rules are shown as MCP elicitation dialogs (allow once / always / deny, with optional feedback)
Permission modesdefault, 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 notificationClaude Code moves long MCP calls to the background automatically and notifies when they finish; run_in_background + wait for explicit control
Resume with full historysend_message (also works for agents from earlier sessions or after a restart, since opencode persists them)
.claude/agents/*.md definitionsUsed via subagent_type: prompt, tools, disallowedTools, permissionMode, maxTurns, effort, isolation. model applies only when it is an opencode provider/model
maxTurns returns partial outputSame; status max_turns, resumable
Progress in the UITool calls are sent as MCP progress notifications
Subagents cannot spawn subagents or ask the user questionsopencode's task and question tools are disabled
Structured outputoutput_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):

json
{  "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

sh
pnpm check   # typecheck, lint, format check, unit testspnpm smoke [provider/model]   # end-to-end run against a real model in a temp repo

License

MIT

Source: README.md at commit e68c627

Tools

5

agent

opencode subagent

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

Parameterscwdmodeltoolseffortpromptrequiredisolationmax_turnsdescriptionrequiredoutput_schemasubagent_typepermission_modedisallowed_tools+1 more

send_message

Continue an opencode subagent

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

Parametersmessagerequiredagent_idrequiredmax_turnsrun_in_background

wait

Wait for an opencode subagent

Wait for a background opencode subagent and return its result. agent_ids from before a restart of the MCP server still work.

Parametersagent_idrequiredtimeout_seconds

stop

Stop an opencode subagent

Abort a running opencode subagent. Returns what it produced so far. agent_ids from before a restart of the MCP server still work.

Parametersagent_idrequired

list

List opencode subagents

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

Parameterscwd

Version history

4
  1. v0.1.4LatestNov 4, 2026
  2. v0.1.3Sep 27, 2026
  3. v0.1.2Sep 27, 2026
  4. v0.1.1Sep 26, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts