Debugging opencode itself

Workflow for interactively exercising the V2 CLI/TUI and server while developing in this repo. All commands below run from packages/cli unless noted otherwise.

Server/client model

opencode V2 is a client/server system, not a single monolithic process:

• Server process runs the Effect HTTP API (packages/server) and owns all domain state: sessions, database, plugins, permissions, Location services. It's started by the serve command (packages/cli/src/commands/handlers/serve.ts).
• TUI process is a separate process that runs no application logic itself — it's an HTTP/SSE client of the server via the generated SDK (createOpencodeClient / sdk.client.v2).
• Discovery: CLI processes find the shared server through a JSON registration file at ~/.local/state/opencode/service.json (or service-local.json for the local/dev channel) containing {id, version, url, pid}. A separate password file under ~/.config/opencode/service.json provides HTTP Basic auth. Before reusing a registration, the client calls GET /health to confirm the server is alive, authenticated, and version-compatible.
• Sharing: because of this registration/health-check dance, many concurrent opencode/TUI invocations converge on one shared background daemon rather than each spawning their own. If no compatible healthy daemon is found, a new one is spawned detached (serve --service) and registers itself.
• bun dev service start|status|stop|restart manages this shared background daemon's lifecycle directly — useful when you need to force a fresh server, confirm one is running, or kill a stuck one.
• Standalone mode (--standalone) opts a single invocation out of the shared daemon: it spawns a private one-off serve --stdio --port 0 child tied to that invocation's lifetime, with its own random password. Use this to isolate a debugging session from your other running opencode sessions.
• Every log line is tagged role=server or role=cli and a per-process run=<id>, so you can distinguish server-side and client-side activity in one shared log file (see "Logs" below) even when both roles are interleaved from concurrent processes.

Starting the dev TUI