clide/docs/ADRs/0006-cli-and-event-surface.md

ADR 0006 — CLI and event surface contract

Status: accepted Date: 2026-04-20

Context

ADR 0001 established that Claude drives Clide via a Bash CLI, not MCP. That decided the channel. It did not define the surface — which subsystems exist, how commands relate to events, what the JSON looks like on the wire, how subscribers discover state changes.

CLAUDE.md states the rule colloquially: "every CLI subcommand has a UI affordance in the app, and every UI action has a CLI. If you add one side without the other, the feature is incomplete." This ADR restates that as an implementable contract.

The shape needs to satisfy three things at once:

1. User/Claude parity. Anything the user can do with a mouse, Claude can do with clide <...>. Anything the user can observe in the UI, Claude can observe via events.
2. Daemon as authoritative state. The app and the CLI are both clients. State lives in the clide --daemon process; commands mutate it; events broadcast changes to all subscribers.
3. pql-style ergonomics. One tool-use pattern for Claude across pql and clide — same exit codes, same JSON-on-stdout habit, same stderr-for-diagnostics rule.

Decision

The CLI is organised into subsystems. Each subsystem owns a noun, a set of verbs, and a set of events. The set is closed at any point in time (documented); growth is additive (new verbs, new events — never renaming existing ones without a version bump).

Subsystem list (initial, by tier)

Subsystem	Tier	Nouns	Representative verbs	Representative events
pane	1	terminal pane	spawn, list, focus, close, write, resize, tail	pane.spawned, pane.output, pane.exit, pane.resized
tab	2	workspace tab	new, switch, close, list	tab.opened, tab.switched, tab.closed
open	2	editor shortcut	(verb-only: clide open <path>)	— (emits editor.opened)
editor	2	active editor buffer	goto, highlight, insert, replace-selection, save	editor.opened, editor.selection_changed, editor.saved
panel	2	sidebar/context panels	show, hide, toggle, list	panel.visibility_changed
tree	2	file tree	reveal, refresh	tree.node_expanded, file.changed
git	3	working tree	status, stage, unstage, stage-hunk, commit, stash, pull, push	git.status_changed, git.branch_changed
pql	4	queries	run, tags, backlinks	pql.result
canvas	5	canvas surface	open, node add/move/connect, save	canvas.node_added, canvas.node_moved, canvas.connection_added
graph	5	graph view	open, focus, filter	graph.focused, graph.filter_changed
theme	6	theme/palette	set, list, get	theme.changed
settings	6	settings store	get, set, list	settings.changed
project	—	whole-workspace	status, reload, events	project.ready, project.reloaded

Two umbrella entry points sit outside any subsystem:

• clide tail --events [--filter <subsystem>[:<id>]] — subscribe to the event stream. Bare tail --events gets everything; filtered forms narrow by subsystem or by subsystem+id (e.g. --filter pane:p_7, --filter git).
• clide status — one-shot daemon snapshot: connected clients, live panes, open tabs, workspace root, daemon version, uptime.

Command shape

clide <subsystem> <verb> [<positional>...] [--flag ...] [-- argv...]

• Positionals are nouns/ids; flags are modifiers.
• -- separates Clide's args from an inner argv passed through (e.g. clide pane spawn --cwd X -- tmux new-session -A -s foo).
• Verbs are imperative (spawn, not create-pane).
• Where it reads naturally, single-word shortcuts exist for the hottest paths (clide open <path> → clide editor open <path>). Shortcuts alias; they do not fork.

Exit-code contract (parity with pql)

Code	Meaning
0	Success
1	User error (bad args, unknown id, precondition failed)
2	Tool error (daemon unreachable, IPC failure, internal panic)
3	Not-found (id or path doesn't resolve)
4	Conflict (state busy, already-running, concurrent-modify)
64–78	Reserved, per sysexits.h, for future specific cases

Diagnostic JSON on stderr (not stdout) on any non-zero exit:

{"code":1,"kind":"user_error","subsystem":"pane","message":"pane id p_99 not found","hint":"clide pane list"}

Stdout stays machine-parseable on success. This matches pql.

Event schema

Events are JSON objects, one per line, on the --events stream. Every event:

{
  "v": 1,
  "ts": "2026-04-20T21:00:00.123Z",
  "type": "pane.output",
  "subsystem": "pane",
  "id": "p_7",
  "payload": { "bytes_b64": "…", "seq": 412 }
}

• v: schema version. Bumped only for breaking changes. Old subscribers pin v.
• ts: ISO-8601 UTC with millisecond precision.
• type: <subsystem>.<verb_past|noun_changed>. Past-tense for things that happened; _changed suffix for state transitions.
• subsystem + id: redundant with type, but makes filtering cheap and future-flexible.
• payload: subsystem-defined; documented per subsystem.

Binary payloads (PTY output, file contents) are base64. The ergonomic cost is worth the "entire stream is line-delimited JSON" invariant.

Command ↔ event duality

Every state-changing command emits at least one event. Subscribers see the same mutation whether they triggered it or not, and the issuing client gets the event back (so clide pane spawn followed by a tail --events subscription sees pane.spawned regardless of subscribe order, via a short replay buffer per subsystem).

Read-only commands (list, get, status) emit nothing.

User/Claude parity as a check

Every merge to main that adds a UI affordance must either:

• add the matching CLI verb, or
• include a linked follow-up task naming the verb to add next.

Every merge that adds a CLI verb must either:

• surface it in the UI, or
• document why the verb is Claude-only (rare; mostly diagnostics like clide status).

Events have the symmetric rule: any UI surface that reacts to state must react to the corresponding event; any new event must be consumable both by the UI and by clide tail --events.

Consequences

• Surface is enumerable. Adding a subsystem means adding a row to the table above and specifying its verbs + events in a short doc under docs/cli/. The daemon registers it; the CLI dispatcher picks it up; clide --help and clide <subsystem> --help stay accurate by construction.
• Wire schema is versioned. v: 1 is the starting point. Compatibility breaks bump the major and land alongside a project.yaml schema_version: bump.
• Replay buffer per subsystem. Cheap (most subsystems emit seldom); needed so a subscriber that connects after a command still sees that command's effect. Buffer depth per subsystem is a tuning parameter; defaults to 16 events.
• Events are the only UI→app state channel. The Flutter app does not poll; it subscribes. Panels render from the last event for their subsystem + current snapshot from project status.
• pql events fit naturally. Long-running pql queries stream rows as pql.result events keyed by a query id, letting the Query panel render incrementally.
• Testability. Every subsystem can be integration-tested by: start a daemon → open a tail --events subscriber → issue commands over the CLI → assert events. No UI needed for protocol-level coverage.
• Extension API (Tier 6) inherits this. A Dart extension publishes a subsystem; the same registration pipeline exposes it to Claude via the CLI. Extensions don't get a second-class channel.

Open questions

• Authorisation granularity. The daemon's token auth is coarse (allow all / deny all). Later, per-subsystem grants may matter (e.g. restrict git push). Out of scope here.
• Back-pressure on event streams. A subscriber that falls behind on pane.output (a firehose) needs a policy: drop oldest, block producer, coalesce, or kill subscriber. Defer until Tier 1 is in real use.
• Event persistence. Events are in-memory only in v1. If a future need (audit log, undo) wants persistence, it becomes a subsystem that subscribes and writes — not a property of the bus.