Log inSubmit server
Opencode subagents logo

Opencode subagents

Delegate coding tasks to opencode models through MCP, with worktrees, background execution, resumption, and Claude agent definitions.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Opencode subagents

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "opencode-subagents": {
      "command": "npx",
      "args": [
        "-y",
        "opencode-subagent-mcp@0.1.4"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

opencode subagents MCP server runs delegated Claude Code-style subagents through a private local opencode process. It supports opencode models such as DeepSeek and opencode Go, while the main Claude Code session continues using its own provider. Use it for searches, refactors, tests, research, or other tasks that can run with a fresh context, especially when worktree isolation or background execution is useful. The server is a stdio MCP server and can resume agents after an MCP or Claude Code restart.

Use cases

  • Delegate repository searches to a lower-cost opencode model
  • Run refactors or bug fixes in an isolated Git worktree
  • Launch tests and collect results in the background
  • Resume an interrupted coding task after a restart
  • Use Claude agent definitions with opencode models

Key features

  • Private local opencode serve process
  • Background agents with wait and stop controls
  • Persistent sessions with follow-up messages
  • Temporary Git worktree isolation
  • Claude and opencode agent definitions
  • Structured JSON Schema output

Tools5

What Opencode subagents lets your agent do. Expand a tool for its parameters.

Verified live~931 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

10/10 checks healthy over the last 44d

What it can do

From the 5 tools this server returned when we ran it; 1 declare their own safety hints.

Read-only tools · 5
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceSigned build
Package age37 days
Maintainers1

Observed 2026-11-02 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · opencode-subagent-mcp@0.1.4 (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads6.6kPackage downloads in the last 30 days.
Last commit8d agoMost recent push to the default branch.
Tools exposed5Callable tools this server registers over MCP.

How Opencode subagents works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Opencode subagents

opencode subagents is an MCP server that connects Claude Code-style delegation to models exposed by the opencode CLI. Its main tools launch agents, send follow-up messages, wait for background results, stop running agents, and list sessions. It is designed for coding work using providers such as opencode Go and DeepSeek.

Install it as a Claude Code plugin or add it as a stdio MCP server with `npx -y opencode-subagent-mcp@latest`. You need Node.js 22 or newer, Git, and the opencode CLI authenticated with `opencode auth login`.

Yes, set `isolation` to `worktree` when calling `agent`. The server creates a Git worktree under `.claude/worktrees/` from the default branch, removes it if unchanged, and keeps it when the agent produces changes.

Yes, use the saved `agent_id` with `send_message`, `wait`, or `stop`. Agent sessions persist in opencode's local store, although agents from before the restart are not shown by `list` until their IDs are used again.

Yes. It is a standard stdio MCP server, so it can be registered with MCP clients that support stdio servers, including Cursor. The documented plugin installation path is for Claude Code, while other clients use their normal MCP server configuration.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewOpencode subagents AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/opencode-subagents?style=directory)](https://allmcps.com/mcp/opencode-subagents)
HTML Embed
<a href="https://allmcps.com/mcp/opencode-subagents"><img src="https://allmcps.com/api/badge/opencode-subagents?style=directory" alt="Opencode subagents on AllMCPs" /></a>