An MCP server that lets Claude Code delegate software-engineering tasks to OpenCode agents — DeepSeek by default — while keeping every agent inside the same workspace/worktree.
Claude Code (orchestrator)
│ MCP
▼
claude-opencode-mcp (this bridge)
│ workspace + task + agent
▼
OpenCode (agent runtime: tools, sessions, permissions)
│
▼
DeepSeek (or any provider configured in OpenCode)
│
▼
your repository — the same working tree Claude Code is using
Claude Code stays in charge: it decomposes the work, picks agents, reviews the results and integrates changes. OpenCode does the repository exploration, editing and test execution. The bridge is deliberately thin.
- Features
- Requirements
- Install
- Claude Code setup
- OpenCode + DeepSeek setup
- Quick start
- Tools
- Agents
- Workspace model
- Security
- Configuration
- Sessions
- Troubleshooting
- Development
- Documentation
- License
- Seven focused MCP tools —
delegate_task,create_session,send_message,get_session,get_diff,abort_session,list_agents. - Same worktree — the delegated OpenCode server runs with your project as its working directory; the agent reads and edits the real files.
- Persistent sessions — follow-up messages keep the agent's context across separate MCP calls.
- Four agent profiles — researcher, reviewer, coder, tester, each with permissions enforced by OpenCode (not by prompt wording).
- Workspace boundaries — canonical paths, allowed roots, path-traversal rejection, and a per-run probe that proves the server is serving the right directory.
- Safety defaults —
.env/credential protection,git commit/git pushdenied, external directories denied, noaskrules that could hang a headless run. - Structured results — every tool returns JSON with stable error codes, and
get_diffgives Claude Code the exact changes a coding session made. - Reliability — timeouts, cancellation, health checks, crash detection, graceful shutdown, request IDs and a rotating log file.
| Component | Version |
|---|---|
| Node.js | 20 or newer |
| Claude Code | recent 2.x |
| OpenCode | 1.18+ (tested against 1.18.32) |
| Model provider | DeepSeek by default; any provider OpenCode supports |
npm install -g claude-opencode-mcpor run it on demand with npx -y claude-opencode-mcp (recommended for
.mcp.json).
The bridge can also use an OpenCode installation from PATH, from
node_modules/.bin, from ~/.opencode/bin, or from an explicit
OPENCODE_BIN.
git clone https://github.com/ArkFlame/claude-opencode-mcp.git
cd claude-opencode-mcp
npm install
npm run build
npm install -g .Create .mcp.json in your project root:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "claude-opencode-mcp"],
"type": "stdio",
"timeout": 600000
}
}
}timeout is milliseconds and is a per-tool-call wall-clock limit. Delegated
runs are long; without it Claude Code falls back to MCP_TOOL_TIMEOUT.
Claude Code also moves main-conversation tool calls to a background task after
two minutes, which is fine — the result arrives when the run finishes.
claude mcp add opencode --scope project -- npx -y claude-opencode-mcpOr for one machine only:
claude mcp add opencode --scope user -- npx -y claude-opencode-mcpVerify:
claude mcp list # opencode ... ✔ ConnectedInside Claude Code, /mcp shows the server and its seven tools.
The bridge reads
CLAUDE_PROJECT_DIR, which Claude Code sets for stdio MCP servers, so delegation defaults to the project you launched Claude Code in.
The bridge starts and stops its own headless OpenCode server, so you do not need
to run opencode serve yourself. You only need OpenCode installed and a
provider authenticated.
-
Install OpenCode
npm install -g opencode-ai # or: brew install sst/tap/opencode opencode --version -
Authenticate DeepSeek (once)
opencode auth login # choose DeepSeek, paste your API keyAlternatively export
DEEPSEEK_API_KEYbefore starting Claude Code; OpenCode reads it for thedeepseekprovider. -
Check the models
opencode models | grep deepseek # deepseek/deepseek-flash # deepseek/deepseek-v4-pro
-
(Optional) validate the project
cd my-project claude-opencode initinitonly creates.claude-opencode/and validates the environment; it never modifies source code and is not required for delegation.
If you prefer to control OpenCode yourself, start opencode serve and point
the bridge at it with opencode.url; see
docs/configuration.md.
Restart Claude Code, then ask:
Use the
opencodeMCP server to havedeepseek-researchermap this repository: entry points, main modules, and where authentication lives.
Then something that edits:
Have
deepseek-coderadd input validation tosrc/api/users.ts, run the tests, and report what changed. Then show me the diff withget_diff.
And a full workflow:
Ask DeepSeek to inspect the authentication system, identify potential issues, implement a fix, and review the changes.
Claude Code typically orchestrates: deepseek-researcher → deepseek-coder
→ deepseek-reviewer → deepseek-tester, calling get_diff between steps.
All tools return JSON in content[0].text (mirrored in structuredContent).
Errors return isError: true with { "error": { "code", "message", ... } }.
Run one task in a fresh session and wait for the agent's answer.
{
"task": "Review the authentication implementation for bugs and security issues.",
"agent": "deepseek-reviewer",
"cwd": "/Users/andy/projects/my-app",
"paths": ["src/auth", "src/middleware", "tests/auth"],
"model": "deepseek/deepseek-v4-pro",
"timeout": 600000,
"allow_edits": false
}Returns { status, session_id, agent, cwd, model, summary, findings, files_changed, duration_ms, truncated, error? }.
pathsare exploration hints, not a boundary — the agent may inspect the whole workspace.allow_edits/allow_bashgrant or revoke edits and shell commands for the run (safe permission profiles; sensitive files and git history stay protected).findingsare parsed from a## Findingssection:- [severity: high] Title (path/to/file:42) — detail.
{ "cwd": "/abs/path", "agent": "deepseek-researcher", "model": null, "title": "auth investigation", "allow_edits": true }Returns { session_id, cwd, agent, model, title, status, can_edit, can_run_bash, created_at }.
Permission overrides set here persist for the session.
Continue a session; the agent keeps its context and permission level.
{ "session_id": "ses_...", "message": "Now implement the fix.", "allow_edits": true }allow_edits / allow_bash may change the level from this message onward.
Returns the stored session state plus live OpenCode status
(opencode.status is idle, busy or retry when a server is running).
Returns the changes associated with a session:
- OpenCode's own session diff when the server reports one, otherwise
- a git diff against a baseline captured when the session was created, so pre-existing uncommitted work is not attributed to the agent.
Returns { source, files, diff, truncated, note? }.
Stops a running delegation. Safe to call when the session is idle.
Lists the built-in agents plus project-local agents from
.claude-opencode/agents/, with read_only, can_edit, can_run_bash flags.
| Agent | Purpose | Edit default | Shell default |
|---|---|---|---|
deepseek-researcher |
architecture, exploration, dependency analysis, recommendations | deny | deny |
deepseek-reviewer |
code review, bugs, regressions, security, architecture | deny | deny |
deepseek-coder |
implementation, refactoring, running tests and fixing failures | allow | allow (no git commit/git push) |
deepseek-tester |
run tests, inspect failures, root causes, suggested fixes | deny | allow (no git commit/git push) |
The orchestrator is not limited to those defaults: every tool that starts or
continues a run accepts allow_edits and allow_bash (true grants, false
revokes, omitted keeps the default). Grants map to safe permission profiles, so
allow_edits: true still protects .env/credential files and allow_bash: true
still denies git history changes. A researcher with write access is one call:
{
"agent": "deepseek-researcher",
"task": "Investigate the caching layer, then implement and test the fix.",
"allow_edits": true,
"allow_bash": true
}Agent prompts live in agents/ and are loaded into the OpenCode
server configuration at startup. Project-local copies in
.claude-opencode/agents/*.md override the prompt, description, model and
temperature; permissions always come from the bridge policy (configurable
through security.* and the per-call overrides).
See docs/agent-configuration.md for frontmatter details and custom agents.
Resolution order for every call:
- explicit
cwdargument CLAUDE_PROJECT_DIR(set by Claude Code)- the MCP server process working directory
workspace.defaultCwdfrom configuration
The first two are required: if they are present but invalid, the call fails instead of silently using a different directory.
Validation happens before any session is created:
- the path must exist, be a directory, and be readable;
- it is canonicalized with
realpath; - when
workspace.allowedRootsis set, the canonical path must live inside one of those roots (traversal is rejected); - the git root is detected for diff isolation.
During the first request for a workspace the bridge reads back directory from
the OpenCode server and compares it with the requested path, so a misrouted
request can never reach the wrong repository.
One OpenCode server is started per workspace directory and reused for all sessions in that workspace; the server process itself runs with the workspace as its working directory.
| Control | Default | Where |
|---|---|---|
| Workspace must exist, be readable, be a directory | always | bridge |
workspace.allowedRoots containment |
disabled (empty) | config |
| Path hints cannot escape the workspace | always | bridge |
.env/.env.*, keys, credentials, .ssh/* protection |
on, even when edits are granted | OpenCode permissions |
git commit / git push for shell-enabled agents |
denied, even when shell is granted | OpenCode permissions |
| Paths outside the workspace | denied | OpenCode external_directory |
Subagent spawning (task) |
denied | OpenCode permissions |
Interactive questions (question) |
denied (headless) | OpenCode permissions |
ask permission rules |
never emitted by the bridge | OpenCode permissions |
The bridge also listens to OpenCode's event stream and auto-rejects any permission request that would otherwise wait for a human, so a delegated run can never hang on approval.
Caveats, stated plainly:
- A shell-enabled agent (
coder,tester) can technically write files through shell commands. The bridge denies theedittools for the tester and forbids git history changes for both, but shell access is inherently powerful. .envprotection applies to the file tools. A shell-enabled agent could stillcata file throughbash; the OpenCode project permission model has the same property.- When connecting to an external OpenCode server (
opencode.url), the bridge cannot inject agent permissions. It verifies the agents exist and refuses to run otherwise.
Details and hardening options: docs/security.md.
Global file: ~/.config/claude-opencode-mcp/config.json (honours
XDG_CONFIG_HOME).
Project file: <project>/.claude-opencode/config.json (overrides global).
Extra file: CLAUDE_OPENCODE_CONFIG=/path/to/config.json (highest precedence).
{
"opencode": {
"url": null,
"autoStart": true,
"hostname": "127.0.0.1",
"port": 0,
"startupTimeout": 30000,
"binary": null,
"username": null,
"password": null,
"maxServers": 4
},
"workspace": {
"allowedRoots": [],
"defaultCwd": null
},
"defaults": {
"agent": "deepseek-researcher",
"provider": "deepseek",
"model": null
},
"timeouts": {
"execution": 600000
},
"security": {
"protectEnvFiles": true,
"denyGitPush": true,
"denyGitCommit": true,
"externalDirectory": "deny",
"extraProtectedPatterns": []
},
"limits": {
"summaryChars": 6000,
"sessionChars": 20000,
"diffChars": 60000
},
"agents": {
"deepseek-researcher": { "model": "deepseek/deepseek-v4-pro" }
}
}defaults.modelacceptsprovider/modelor a bare model id (combined withdefaults.provider). Whennull, the provider's default model from OpenCode is used.- Provider credentials stay in OpenCode (
opencode auth login) or environment variables; they are never duplicated in this config. - For auto-started servers the bridge passes
OPENCODE_SERVER_USERNAME/OPENCODE_SERVER_PASSWORDthrough and authenticates its own requests. For external URLs it only uses credentials you configure.
Full reference: docs/configuration.md.
- Sessions are OpenCode sessions; the bridge keeps a small registry at
~/.local/state/claude-opencode-mcp/sessions.json(override withCLAUDE_OPENCODE_STATE_DIR) soget_session,get_diffandsend_messagesurvive a bridge restart. - Records older than 14 days are pruned at startup.
- If an OpenCode server restarts, persisted sessions are still addressable;
get_sessionreports live status when a server is running. - Logs:
~/.local/state/claude-opencode-mcp/bridge.log(rotated at 5 MB). SetCLAUDE_OPENCODE_LOG=debug|info|warn|error|silent.
| Symptom | Fix |
|---|---|
OPENCODE_NOT_AVAILABLE |
npm install -g opencode-ai or set OPENCODE_BIN / opencode.binary. |
OPENCODE_START_TIMEOUT |
run opencode serve manually to see the error; raise opencode.startupTimeout; check OPENCODE_SERVER_PASSWORD handling. |
MODEL_NOT_AVAILABLE |
authenticate a provider (opencode auth login) or set defaults.model, e.g. "deepseek/deepseek-v4-pro". |
ProviderAuthError in a result |
DeepSeek credentials are missing/expired; re-run opencode auth login. |
AGENT_NOT_FOUND with an external server |
add the four agents to that server's config or stop using opencode.url. |
AGENT_TIMEOUT |
raise timeouts.execution or the timeout argument; consider a narrower task. |
WORKSPACE_NOT_ALLOWED |
add the project to workspace.allowedRoots or clear the list. |
| Tool call seems to hang in Claude Code | Claude Code backgrounds long calls after 2 minutes; progress notifications are sent, and the bridge always resolves or aborts — check bridge.log. |
| Claude Code kills the call at 60s | set "timeout": 600000 in the .mcp.json entry (or MCP_TOOL_TIMEOUT). |
More: docs/troubleshooting.md.
npm install
npm run lint # Biome
npm run typecheck
npm test # unit + integration (no OpenCode needed)
npm run buildReal end-to-end tests need an OpenCode install with DeepSeek authenticated:
npm run test:e2e # checkpoints: workspace, agents, sessions, diff, abort, stdio
CLAUDE_OPENCODE_E2E_WORKFLOW=1 npm run test:e2e # full researcher → coder → reviewer → tester workflowLayout:
src/
index.ts CLI entry (MCP server + `init`)
cli/ `claude-opencode init`
config/ configuration loading and merging
workspace/ resolver, validator, task context
security/ path policy + OpenCode permission profiles
opencode/ binary resolution, manager, client, agents, sessions, runner
mcp/ MCP server and the seven tools
agents/ built-in agent prompts
tests/ unit, integration, e2e
docs/ documentation
See docs/development.md and docs/architecture.md.
- Installation
- Configuration
- Claude Code setup
- OpenCode setup
- DeepSeek setup
- Agent configuration
- Workspace model
- Security
- Security audit
- Troubleshooting
- Architecture
- Development
- Contributing
- Changelog
- Security policy
- Code of Conduct
Bug reports, feature requests, and pull requests are welcome. Start with CONTRIBUTING.md; for vulnerabilities use SECURITY.md instead of a public issue.
MIT — see LICENSE.
delegate_task now starts a background opencode run and returns a run_id at once. Use
wait_any to block on the first finished run and get_run for its result. Runs have a hard
timeout and an idle watchdog. Each run is killed with its whole process group. Records persist
across MCP restarts, and orphaned runs are reaped at startup.
| Tool | Purpose |
|---|---|
delegate_task |
Start a run: task, brief, cwd, model, agent, read_paths, allow_edits, allow_bash, allow_shared_cwd, wait_seconds (<= 110) |
list_runs |
Status, age, idle seconds, cwd, branch, last log line, one-line summary |
get_run |
Final reply (16 KB cap), parsed Status:/commit/tests, log tail, git diff stat |
wait_any |
Block up to N seconds (<= 110) until any listed run finishes |
abort_run / abort_all |
Stop one run or all runs, then reap stale records |
list_models |
Models from opencode models, cached five minutes |
create_worktree / remove_worktree |
<repo>-wt/<name> on branch kab/<name>; removal refuses unlanded commits unless force |
Environment variables (env overrides config.json values in the runs section):
| Variable | Default | Meaning |
|---|---|---|
CLAUDE_OPENCODE_MODEL |
opencode-go/hy4-flash-free |
Default run model (provider/model) |
CLAUDE_OPENCODE_TIMEOUT |
1500 |
Hard timeout per run, seconds |
CLAUDE_OPENCODE_IDLE_TIMEOUT |
300 |
Kill after this many seconds without output |
CLAUDE_OPENCODE_MAX_PARALLEL |
10 |
Concurrent runs; extra runs queue FIFO |
CLAUDE_OPENCODE_ALLOWED_ROOTS |
parent of the repo | Path-delimiter-separated roots runs may use |
CLAUDE_OPENCODE_BRIEF_HEADER |
built-in header | File whose text prepends every brief |
CLAUDE_OPENCODE_RUNS_DIR |
~/.cache/claude-opencode-mcp/runs |
Run records, logs and prompts |
CLAUDE_OPENCODE_BIN |
opencode |
OpenCode executable |
Install as a Claude Code server with scripts/install.sh. See docs/installation.md.