# 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:

```sh
./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:

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

The scripts deploy a stable repo-owned launcher:

```sh
/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.

## OpenCode MCP config

```json
{
  "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.

```json
{
  "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

```sh
npm install
npm test
```