Agent targeting
The structured CLI surface an AI agent drives without a TTY: create with new, place configured agents or explicit argv with launch / spawn, reshape exact...
Full source summary
The structured CLI surface an AI agent drives without a TTY: create with new, place configured agents or explicit argv with launch / spawn, reshape exact existing panes with insert-pane / move-pane / swap-pane, act through run, send-keys, or paste, observe through bounded wait / watch, and raise advisory human attention with ask. Plugin, workspace, and satellite verbs provide the surrounding configuration and inventory surfaces. This file is the agent contract. Per ADR-0030, the structured agent state — cells, command results, semantic events — is a local projection over the shared engine, and the CLI plus its versioned JSON schemas are what an agent depends on, not a structured wire tier. It documents each verb, its JSON shape, the read-act-wait loop, and the exit codes each verb mirrors.
3. Targeting: the selector grammar
One grammar, every targeted command — kill, snapshot, wait, watch,
send-keys, paste, run, ask, resize, agent wait,
agent send-keys, agent prompt, agent answer, launch/spawn placement, and the
three spatial verbs all share TARGET.
It is resolved client-side against a server snapshot (ADR-0021); the server
never parses a selector.
The full grammar table and CLI examples live in tui.md §3. In one
line, the forms are: . (current), name (session), name:N / name:tag
(window), name:N.M (pane), and @N (opaque id). = is explicitly
unsupported for headless commands because they have no attached-client MRU.
%name is reserved for the proposed agent-name addressing contract in
ADR-0075, but no shipped CLI verb
resolves it yet. It fails closed as a selector miss rather than choosing a
pane. Use the direct @N returned by inventory and creation verbs until that
ADR is accepted and implemented.
A selector that names several panes (a whole session or window) narrows to a
single pane: the focused pane when it is among the matches, else the first in
snapshot order (the pick_target_pane tiebreak the MCP tools share).
Optionality differs per verb: snapshot, wait, watch, and agent wait
may omit a target (agent wait matching agent show/explain);
send-keys, paste, run, ask, resize, agent send-keys, agent prompt,
agent answer, and every
spatial verb require it. launch/spawn
use an optional target only for explicit local placement. Spatial and placement
targets are stricter than the selected-pane tiebreak: each must resolve to one
exact local pane.
Agent CLI
The structured CLI surface an AI agent drives without a TTY: create with new, place configured agents or explicit argv with launch / spawn, reshape exact...
Agent JSON contracts
The structured CLI surface an AI agent drives without a TTY: create with new, place configured agents or explicit argv with launch / spawn, reshape exact...