# opencode subagents [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/sebstaq/opencode-subagent-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 6558  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/opencode-subagents

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

## Tools
Capabilities this server exposes over MCP:

- **agent** — 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.
- **send_message** — 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.
- **wait** — Wait for a background opencode subagent and return its result. agent_ids from before a restart of the MCP server still work.
- **stop** — Abort a running opencode subagent. Returns what it produced so far. agent_ids from before a restart of the MCP server still work.
- **list** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "opencode-subagents": {
    "command": "npx",
    "args": ["-y","opencode-subagent-mcp@0.1.4"]
  }
}
```

## Documentation

## What opencode subagents MCP server does

opencode subagents connects Claude Code-style delegation to models available through the opencode CLI. Each `agent` call starts a subagent in the selected project, gives it a self-contained prompt, and returns its final report rather than the full working conversation. The default model is configured as `opencode-go/deepseek-v4.1-flash`, although a different `provider/model` can be selected.

The server is intended for coding tasks such as repository searches, refactors, bug fixes, tests, and research. It can use Claude agent definitions stored in `.claude/agents/`, including their prompts, tools, permission modes, turn limits, and related settings. It also recognizes opencode agent types such as `general`, `explore`, `plan`, and `build`.

## How it works

At startup, the server launches a private `opencode serve` process on a random localhost port with a per-run password. The opencode process inherits the environment in which the server runs, allowing it to use provider authentication already configured for the opencode CLI. The server itself does not read, store, or transmit those credentials.

An agent can run in the current project or in a temporary Git worktree. Worktree execution is based on the default branch and uses `.claude/worktrees/`; unchanged worktrees are removed, while worktrees with changes are retained with their outcome reported. Background execution is available through `run_in_background` and can be collected with `wait`. Long-running calls may also be moved to the background automatically by Claude Code.

Agent sessions persist in opencode's local session store. `send_message` continues a completed or previously interrupted agent with its history, and `wait` or `stop` can still address agent IDs from before a server restart. Progress is delivered as MCP progress notifications.

## Setup and configuration

The runtime requires Node.js 22 or newer, Git, and an authenticated opencode CLI. Providers can be configured with `opencode auth login`. Install it as a Claude Code plugin or register the package as a stdio MCP server with Claude Code using `npx -y opencode-subagent-mcp@latest`.

Optional configuration is read from `~/.config/opencode-subagent-mcp/config.json`, or from the path in `OPENCODE_SUBAGENT_CONFIG`. Available settings include the default model, default permission mode, opencode executable path, maximum concurrent agents, and maximum returned result length. `OPENCODE_SUBAGENT_MODEL` and `OPENCODE_SUBAGENT_MODE` override the configured model and permission mode.

The server reads relevant Claude settings from the user and project configuration files, including permission rules and `.claude/agents/*.md` definitions. Project roots come from MCP roots, then `CLAUDE_PROJECT_DIR`, and finally the server's working directory.

## Tools and capabilities

- `agent` launches a subagent with a prompt, agent type, model, working directory, permissions, tool restrictions, turn limit, effort level, optional JSON Schema output, and optional worktree isolation.
- `send_message` resumes a finished or interrupted subagent and returns a new final report.
- `wait` collects a background agent, optionally with a timeout.
- `stop` aborts a running agent and returns its partial output.
- `list` shows agents used in the current server session and available Claude or opencode agent types.

Permission prompts can appear as MCP elicitation dialogs. Configured Claude allow, ask, and deny rules are applied, and structured output is returned through MCP `structuredContent`.

## Limitations and notes

Subagents begin without the parent conversation and cannot spawn further subagents or ask the user questions. Agents are not shown in Claude Code's `/tasks` view, cannot be targeted by the Workflow tool's `agent()` function, and do not support fork-with-parent-context. Hooks, skills preloading, memory, and per-agent MCP servers are not mapped.

The `auto` permission mode has no safety classifier. It permits operations outside the project except for configured rules and a fixed set of destructive command patterns that trigger confirmation. Prompts, files, and command output read by a subagent are sent to the selected model provider under that provider's retention policies. The server makes no telemetry or other network calls, but opencode stores session history locally.

_Full upstream README: https://allmcps.com/mcp/opencode-subagents/readme_