pipe-opencode

pipe-opencode is a local MCP server for inspecting and controlling a running OpenCode TUI session. It reads durable OpenCode state through opencode db --format json and uses tmux for live pane capture and prompt injection.

Deployment

Build and deploy the MCP bridge to one or more local agent clients:

./deploy.sh all
./deploy.sh codex claude
./deploy.sh opencode

If no environment is provided, deploy.sh prompts for all, codex, claude, or opencode. The opposite operation removes only the pipe-opencode config and instruction blocks owned by these scripts:

./undeploy.sh all
./undeploy.sh codex

The scripts deploy a stable repo-owned launcher:

/home/artur/Projekty/local-LLM/pipe-opencode/bin/pipe-opencode-mcp

By default, the bridge uses:

• OPENCODE_BIN=/home/artur/.opencode/bin/opencode

• OPENCODE_CONFIG_DIR=$HOME/.config/opencode

Override either environment variable when running deploy.sh if a machine uses different paths.

Related MCP server: herdr-mcp

OpenCode MCP config

{
  "mcp": {
    "pipe-opencode": {
      "type": "local",
      "command": ["/home/artur/Projekty/local-LLM/pipe-opencode/bin/pipe-opencode-mcp"],
      "enabled": true,
      "timeout": 1800000,
      "environment": {
        "OPENCODE_BIN": "/home/artur/.opencode/bin/opencode",
        "OPENCODE_CONFIG_DIR": "/home/artur/.config/opencode"
      }
    }
  }
}

Use the longer timeout when calling blocking tools such as opencode_wait with condition: "awaiting_user". A shorter client timeout cancels the MCP request before the bridge can finish waiting for OpenCode to become idle.

Interrupting OpenCode

Use opencode_interrupt when an overseer needs to stop the running OpenCode turn. The tool sends the double-Escape sequence OpenCode expects in one MCP request, instead of relying on the overseer model to invoke opencode_tui_key twice quickly enough.

{
  "target": "%2",
  "intervalMs": 75
}

target is optional when pane auto-detection is unambiguous or OPENCODE_TMUX_TARGET is set. intervalMs defaults to 75; set it to 0 to send both Escape presses in a single tmux send-keys burst.

Blocking waits

opencode_wait supports three wait conditions:

• changed: return after session.time_updated advances. This keeps the old polling behavior.

• idle: return after the root assistant turn is finished and no tracked session has a running tool call.

• awaiting_user: return after OpenCode appears ready for the next user prompt. This is the preferred mode for overseer agents that should block while OpenCode or its child agents are still processing.

When condition is omitted, calls with sinceTimeUpdated use changed; calls without it use awaiting_user. Blocking waits default to no server-side timeout, a 2s internal poll interval, and a 15s stable window. Set timeoutMs to a positive value to cap the wait, or set stableMs higher if a local model has long gaps between internal steps.

Development

npm install
npm test