opencode-lens

opencode-lens is a local automation bridge for live opencode TUI sessions. It combines an opencode TUI plugin, a Unix-socket HTTP API, an MCP server, a Hermes skill, and optional watchdog scripts so local agents can inspect and safely control running opencode instances without screen scraping.

Recommended GitHub description:

opencode TUI bridge and MCP toolkit for inspecting, controlling, and safely automating live opencode sessions

What It Does

• Discover active opencode TUI instances.

• Read the visible TUI session and status.

• Send prompts to a specific session in the background or switch the visible TUI session.

• Run a single prompt on a specific model with per-message providerID + modelID.

• Read recent messages, diffs, and todo state.

• Bridge opencode interactive questions to Hermes users.

• Approve or deny opencode permission prompts with explicit user intent.

• Close accidentally opened TUI overlays such as the model selector.

• Monitor instances for pending permissions, questions, and completion events.

Related MCP server: textual-mcp-server

Repository Layout

opencode-lens/
├── packages/
│   ├── plugin/          # opencode TUI plugin; exposes the lens Unix socket API
│   ├── mcp/             # stdio MCP server for Hermes and other MCP clients
│   └── shared/          # shared registry/types/discovery helpers
├── scripts/             # optional watchdog scripts
├── skill/               # Hermes/OpenClaw skill instructions
├── docs/                # HTTP API notes
├── package.json         # Bun workspace
├── tsconfig.json
├── bun.lock
└── LICENSE

Architecture

Hermes / MCP client
  └─ opencode-lens-mcp (stdio MCP server)
       ├─ discovers active lens registry files
       ├─ talks HTTP over per-user Unix sockets
       └─ exposes tools such as instances_list, tui_status, prompt_send

opencode TUI process
  └─ opencode-lens plugin
       ├─ writes an instance registry file
       ├─ serves HTTP over a Unix Domain Socket
       ├─ reads live TUI/session state through the opencode plugin API
       ├─ forwards selected operations through the opencode SDK
       └─ publishes status events for automation clients

The plugin does not open a TCP port. Registry files are written under:

~/.local/share/opencode-lens/instances/

Sockets prefer:

$XDG_RUNTIME_DIR/opencode-lens/

and fall back to:

~/.local/share/opencode-lens/sockets/

Requirements

• Bun 1.3+

• opencode with TUI plugin support

• Hermes or another MCP client if you want MCP automation

Development

bun install
bun run typecheck
bun test
bun run build

Build standalone MCP binaries when needed:

bun run build:mcp:binaries

Install The TUI Plugin

Build the plugin:

bun run --cwd packages/plugin build

Install the built plugin into opencode's TUI plugin directory:

mkdir -p ~/.config/opencode/plugins
cp packages/plugin/dist/index.js ~/.config/opencode/plugins/opencode-lens.js

Register it in ~/.config/opencode/tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["./plugins/opencode-lens.js"]
}

Restart opencode after changing the plugin bundle. Already-running opencode TUI processes keep the old plugin code loaded.

Configure Hermes MCP

Build the MCP server:

bun run --cwd packages/mcp build

Example Hermes MCP configuration:

mcp_servers:
  opencode-lens:
    command: /path/to/bun
    args:
      - /path/to/opencode-lens/packages/mcp/dist/opencode-lens-mcp.js
    enabled: true
    timeout: 30
    connect_timeout: 10

Restart Hermes after changing MCP tools. MCP tools are registered when Hermes starts.

Install The Hermes Skill

Copy the skill into Hermes:

mkdir -p ~/.hermes/skills/opencode-lens
cp skill/SKILL.md ~/.hermes/skills/opencode-lens/SKILL.md
rm -f ~/.hermes/.skills_prompt_snapshot.json

The skill tells Hermes agents how to use the MCP tools safely. In particular, it requires concise status tables, explicit permission choices, per-message model selection, and safe handling of interactive questions.

Optional Watchdog Scripts

Copy the watchdog scripts if you want polling-based notifications:

mkdir -p ~/.hermes/scripts
cp scripts/opencode-watch.py ~/.hermes/scripts/opencode-watch.py
cp scripts/opencode-watch-loop.sh ~/.hermes/scripts/opencode-watch-loop.sh
chmod +x ~/.hermes/scripts/opencode-watch.py ~/.hermes/scripts/opencode-watch-loop.sh

Run one poll:

~/.hermes/scripts/opencode-watch.py

Run a simple polling loop:

~/.hermes/scripts/opencode-watch-loop.sh

Useful environment variables:

OPENCODE_LENS_SOCKET_DIR       defaults to $XDG_RUNTIME_DIR/opencode-lens or /run/user/$UID/opencode-lens
OPENCODE_WATCH_STATE_FILE      defaults to ~/.hermes/opencode-watch-state.json
OPENCODE_WATCH_LIST_FILE       defaults to ~/.hermes/opencode-watch-list.json
OPENCODE_WATCH_LOCK_FILE       defaults to ~/.hermes/opencode-watch.lock
OPENCODE_WATCH_SCRIPT          used by opencode-watch-loop.sh

MCP Tool Highlights

• instances_list: list active opencode lens instances.

• tui_status: read the visible TUI session/status for an instance.

• prompt_send: send a prompt to a target session; supports per-message model parameters.

• messages_read: read recent messages for a session.

• tui_session_switch: switch the visible TUI session.

• question_respond / question_reject: answer or dismiss opencode interactive questions.

• permission_respond: reply to permission prompts with allow, always, or deny.

• model_selector_close: close the currently open TUI overlay/dialog when the runtime exposes api.ui.dialog.clear().

Model Selection

opencode 1.17.x chooses the model per message. The reliable workflow is:

1. Call models_list.

2. Match the desired provider/model IDs.

3. Send the prompt with prompt_send and providerID + modelID.

Do not rely on moving the TUI's visible model indicator. The plugin API does not provide a stable way to set that indicator to an arbitrary model by ID.

Permission And Question Safety

Permission replies are high-risk. Always show the user the requested operation and ask for one of three choices:

• allow once

• allow always

• deny

Interactive questions are separate from permissions. They must be answered with question_respond; sending normal prompt text does not select an option.

Troubleshooting

• No instances: confirm ~/.config/opencode/tui.json loads ./plugins/opencode-lens.js, then restart opencode.

• MCP tool missing: rebuild packages/mcp, then restart Hermes.

• Plugin behavior did not change: restart the target opencode TUI process.

• Prompt returns 409 session_busy: inspect tui_status; the session may be running, waiting for a question, or waiting for permission.

• Permission prompt does not appear: the target opencode permission rules may be configured as auto-allow instead of ask.

• Status reads time out: the plugin caps slow opencode SDK calls and returns structured timeout errors instead of Bun's default 10-second server timeout.

License

MIT