Pane options and JSON contracts

tma keeps all shared state in tmux pane options (user options, pane-scoped). There is no socket and none is needed: any tmux show-options -p or #{@agent_state} format string reads the current verdict straight from tmux’s own option store, and tma ls --json gives the same data as a stable structured document. This page is the contract for both: the pane-option schema and the JSON schemas.

The stamp grammar

Option values are machine tokens, never glyphs. State is one of the closed vocabulary idle, working, blocked, unknown. Glyph and color rendering happens only in the surfaces, and is configurable.

@agent_detail is a lowercase machine token ([a-z0-9_-]) qualifying why the pane is in that state. Unlike state, this vocabulary is open and unstable until 1.0: an agent manifest may emit a token this engine has never heard of, and it round-trips intact rather than erroring. Read it defensively — match the tokens you know and degrade gracefully on the rest. What the bundled manifests emit today:

tma-core additionally declares error, background and compacting as constants; no bundled manifest emits those three yet.

Every @agent_*_at value is epoch milliseconds (13 digits today), not seconds. Millisecond resolution is what keeps two episodes opening in the same wall-clock second distinguishable.

@agent_attention is a presence flag: the literal value 1 when set, and the option is absent otherwise. It is compared against @agent_since by the ordered-input clear, which is why the raise instant has to stay write-once. Writers order a chained stamp so @agent_stamped_at is written last; a reader that sees stamped_at older than since or evidence_at caught a chained write mid-flight and should treat the tuple as in-progress.

One exception keeps that rule from latching. A chained stamp commits in milliseconds, so a since more than 2 seconds ahead of stamped_at is not a write in flight: it is a backward wall-clock step (a suspend, an NTP correction) that stranded the write-once since in the future. Such a tuple reads as settled, and the next publish rewrites since rather than holding it, so a stepped clock costs one stale transition time instead of a pane that re-captures every cycle for the rest of the session.

Pane-option schema

The store carries provenance (@agent_source, @agent_evidence_at) so a stateless producer can rank a stamped hook claim above its own fresh capture. Pane-scoped options describe one agent pane; window-scoped and server-scoped options carry rollups and hints.

Values that depend on a previous value (the write-once @agent_since, the notification dedup, the hook-versus-capture arbitration) are governed by server-side conditional writes (set-option -pF), which expand formats in the target pane’s context atomically at write time. Everything else is last-writer-wins over deterministic values, which converges.

Reading these from your own bar, prompt, or script is a supported first-class use; Read agent state from a status bar or script covers the read forms and the freshness rule that goes with them.

tma ls --json

A versioned, additive-only document. The top level is { "schema": 1, "agents": [ ... ] }; each element of agents is one agent row with this exact key set:

The “done” surface is state == "idle" and attention == true; done carries that conjunction precomputed from the one definition the whole tool shares (it is also what wait --until done and --state done mean), so consumers stop re-deriving it. The state token itself is never mangled — it stays idle. All of attention, done, session, transcript, permission_request, stamped_at_ms, context, context_at_ms, muted, tokens, quota, cost_usd, repo, branch, worktree, pending_tool, pending_call, pending_summary, server, and host are additive, so the schema stays 1 (a new key never bumps it, including the keys nested inside quota); render an absent context, tokens, quota or cost_usd as absence (no gauge, no count, no quota, no cost), never as 0. The repo/branch/worktree keys are best-effort: the resolver memoizes one bounded git call per unique cwd and degrades every field to null on any failure, so a consumer treats them as hints, never guarantees.

The row writer has a second, title-free protocol surface for consumers that are not on this machine, and title is the only key that differs between the two: a pane title is agent-supplied text, kept off a remote surface for the reason pending_summary is kept out of the notification payload. Both surfaces are written by one function, so every other key, its order, and its null handling are the same on both, and a key added to either is added to both. Nothing tma ships today emits the protocol form; tma ls --json, tma wait --json and tma subscribe are the local surface and carry title exactly as documented above.

server and host: merging rows from more than one place

A pane id is unique within one tmux server and nothing more. Collect tma ls --json from your laptop and from a build box and both sets will contain a %5, with no way to tell them apart — the same is true of two servers on one machine (tmux -L work and tmux -L scratch number panes independently). The server/host pair is what makes a merged set addressable: (host, server, pane) is the key you want, and either alone is not enough.

server is the server’s own #{socket_path}, which is what the daemon already keys its per-server socket and lock on, so it is stable for the life of the server and identifies it however you addressed it: --socket-name work, --socket-path /tmp/tmux-501/work, and an invocation from inside that server all report the same value. The path rather than a hash of it, because an operator reading a merged log can tell /private/tmp/tmux-501/default from a tmate socket at a glance.

Both are resolved once per invocation — one tmux call and one uname — and repeated onto every row, since a line-oriented consumer that filters agents down to one element must not lose the provenance with it. A long-lived tma subscribe resolves them once for the life of the stream.

tma wait --json

The single matched agent row as one schema-1 object: the top-level schema key plus the same row fields as an ls --json element (pane, agent, state, detail, since, since_ms, episode_ms, locator, title, attention, done, session, transcript, permission_request, stamped_at_ms, context, context_at_ms, muted, tokens, quota, cost_usd, repo, branch, worktree, pending_tool, pending_call, pending_summary, server, host). It shares the serialization with ls --json, so the two can never disagree on keys, order, or null handling.

The fleet targets satisfy a SET of panes, so wait --all --json and wait --count <n> --json emit the ls --json document instead — { "schema": 1, "agents": [ ... ] }, one element per satisfied row, with those same row keys. A consumer parses one shape whether it listed or waited; the single-object form stays the single-pane targets’ emission (--pane, --agent, --any).

Notification hook payload

When a [notify] command fires, it receives one JSON object on stdin. It carries metadata only, never captured screen content. The exact top-level key set:

The pane title is not sent

The pane title is the one field whose content the pane’s own program controls, and it routinely holds a branch name, a repo path or a prompt fragment. notify.command pipes this payload to whatever you configured — ntfy, Pushover, an Apple Shortcut — so the title would reach that service’s operator on every fire. Since schema 2 it is omitted by default.

[notify] include_title = true puts it back, and it governs all three carriers together: the payload’s title key, the TMA_TITLE environment variable, and the notify.log audit line. The host-local display-message baseline is not a carrier and always shows the title.

The standing rule for this payload: no field enters it that is not safe world-readable. Its writer is also the audit log’s writer, and that log is the file most likely to end up pasted into an issue.

The same values are also exported as environment variables (TMA_AGENT, TMA_PANE, TMA_STATE, TMA_LOCATOR, TMA_SINCE_MS, TMA_EPISODE_MS, plus TMA_TITLE when include_title is on, TMA_DETAIL, TMA_SESSION, TMA_REPO, TMA_BRANCH and TMA_CONTEXT_PCT when they have a value), so a hook reads whichever is more convenient. Unlike the JSON, a value with nothing to report is an unset variable rather than an empty string.

The daemon and the daemonless tma event path build this payload through one shared builder, so the same transition yields the same object either way.

The [notify] log file (see Configuration) holds the same object per line, with one extra key: at, the fire time in epoch milliseconds, written directly after schema. A detached action’s completion is logged the same way, as its own payload (below) plus at; a completion line carries action and outcome where a state line carries state, which is how a reader tells the two apart.

tma act JSON result

The result of firing one action, a schema-1 object with this exact key set. See tma act for the verb and its exit codes.

tma act --all --json wraps those same objects: { "schema": 1, "results": [ ... ] }, one element per resolved target in the order they were fired, each with the exact key set above. The envelope appears whenever --all is passed, even for a single matched pane, so a consumer’s parse never depends on the match count. The process exit code is the worst element’s (see Fan-out); the per-element exit_code stays each target’s own.

outcome is authoritative and closed: sent (keys delivered), replied (an API-channel answer delivered over HTTP, a 2xx), exited (a synchronous exec child finished; exit_code is its code), spawned (a detached supervisor launched), timeout (a synchronous child killed at timeout_ms), refused (reason carries which gate), vanished (tmux reports the pane gone, or an API target answered/withdrawn between gate and act — a 404; reason carries which), error (broker runtime failure: an unreachable API server, or a tmux command the server refused, whose stderr rides in the message). reason is one of gated, requires-unmet, wrong-agent, no-coverage, episode-changed, request-gone (all exit 4) and locked (exit 5). On a vanished outcome (both exit 3) it is instead pane-gone (tmux says the pane is gone) or request-gone (the API server answered 404: the permission request was already answered or withdrawn, on a pane that is still there).

A --slot dispatch carries one additive key, cached, and the replay’s object is the fire’s object with cached flipped: same outcome, same reason, same exit_code, which is the point of a receipt. An error replayed from the ledger reads reason fired-unknown, a token that appears on no live fire: the broker could not prove the keystroke did not land, so the ledger records the doubt rather than inviting a second one. The ledger and its own document are in tma receipts.

episode-changed and request-gone are the binder refusals: the fire carried --expect-episode-ms or --expect-permission-request and the pane, read under the action lock, no longer matches what the caller saw (see Binding a dispatch to the pane you saw). Note that request-gone is deliberately one token across two outcomes: refused means the pane stopped carrying the id the caller quoted, vanished means the server answered 404 for it. Read outcome to tell them apart.

tma act list document

A schema-1 document enumerating the loaded actions from tma act --list --json: { "schema": 1, "actions": [ ... ] }. Each action carries this exact key set, and with --pane two more.

The when object carries state (array of state tokens), detail (array of detail tokens), context_pct_min, and context_pct_max (number or null each).

Detached-action completion payload

A detached (detach = true) action fires one completion notification through the [notify] command when its child exits. It is its own contract, distinct from the notification hook payload (a completion has no state, and its pane may already be gone). The exact top-level key set:

The same values reach the command as environment variables: TMA_ACTION, TMA_PANE, TMA_AGENT, TMA_OUTCOME, plus TMA_EXIT_CODE and TMA_LOCATOR when they have a value. As on the state path, a value with nothing to report is an unset variable rather than an empty string, so ${TMA_EXIT_CODE:-} is how a hook tells a deadline kill from a child that exited. There is no env mirror of lock_release_failed; read it from the JSON.

A completion rides the same sinks a state notification does: the display-message baseline, the opted-in bell/osc tty sinks, and the [notify] log audit line. A hook that cannot start, or that exits non-zero, updates the same failure marker tma doctor reports.

tma doctor --json

The whole diagnosis as one schema-1 object. It is grouped rather than flat: each check is its own sub-object, so a consumer reads .daemon.alive rather than guessing which prefix belongs to what. Top level:

Each agents element carries this exact key set:

remote_panes and ignored_panes are additive, so the schema stays 1.

tma debug explain --json

One pane’s identity, rule evaluation, and verdict as a schema-1 object. Absent optional fields are an explicit null, never dropped.

The verdict object carries state, detail (string or null), action (publish or hold), may_override, set_attention, episode_reset, and winning_evidence, itself { source, at, label }.

ignored is additive, so the schema stays 1.

Additive-schema discipline

All the JSON contracts on this page share one rule: additive changes (a new key) keep the schema at 1; a breaking change (renaming or removing a key) bumps schema and the exact-key-set drift tests with it. A consumer can branch on schema rather than guess. Each serialization site has a test pinning its exact key set, so a silent drift cannot ship.