Quickstart · ~5 minutes

First dispatch.

Prerequisites: Python 3.12, the opencode CLI on your PATH, and Claude Desktop or any MCP client.

Clone and install

terminal

git clone https://github.com/Parithosh-Varma/claude-opencode-bridge.git
cd claude-opencode-bridge
python3.12 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Wire into Claude Desktop

Merge this into ~/Library/Application Support/Claude/claude_desktop_config.json under mcpServers, replacing <REPO_PATH>. Restart Claude Desktop.

claude_desktop_config.json

{
  "mcpServers": {
    "opencode-bridge": {
      "command": "<REPO_PATH>/.venv/bin/python",
      "args": ["<REPO_PATH>/opencode_bridge_mcp.py"],
      "env": { "TASK_DB_PATH": "<REPO_PATH>/tasks.db" }
    }
  }
}

Run one worker pass

terminal

./.venv/bin/python worker.py
./.venv/bin/python tasks_cli.py pending   # what Claude is waiting on

For hands-free mode, schedule worker.py every 60s with launchd (macOS) — see the repo README for the plist.

Dispatch from Claude

claude

submit_task(title="Add retry tests", working_dir="/path/to/repo",
  instructions="Steps, paths, acceptance criteria. Be explicit.")
wait_for(task_ids=["t-…"], timeout_sec=120)
get_task_result(task_id="t-…")

Go public (optional)

Need Claude on the web to reach your machine? One command pairs a tunnel with the MCP allowlist.

terminal

./start_public.sh   # ngrok fixed domain if .ngrok-domain exists, else cloudflared

How it works → Stuck? Read the FAQ