Repository navigation
Architecture and Contracts
- tmux stays the only terminal runtime: no daemon, no wrapper, no new entry point. The optional HTTP endpoint runs in a tmux window you open.
- Agents report through their own plugin hooks (in Pi and oh-my-pi, an
extension that runs the hook without waiting on it), which fail open: a
broken or missing
tmagnever blocks a turn. An ordinary CLI hook shares one entry budget across input, discovery, state changes and housekeeping. Cooperative cancellation begins after 2.75 seconds, with a fail-open process cutoff at three seconds under normal OS scheduling. Answer-hook setup has that short budget separately from its intentional permission wait; cancellation closes its owned streams and suppresses late decision output. Process suspension or an uninterruptible kernel operation cannot provide a hard real-time bound. - The binary lives in the plugin's TPM directory; session metadata and owner
authorization have the separate locations listed in Footprint.
Agent integrations use each host's plugin manager. Prompts and agent
output are never stored: a prompt sent through an inbox is written to the
agent's channel and kept nowhere, and
tmag read --lastand--turnsread an agent's reply and turns from its own transcript when asked.
Every JSON document carries "schema": "tmag/v2".
tmag list --json gives every session and every pane running an agent:
{
"schema": "tmag/v2",
"seq": 42,
"caller": { "pane": { "server": "/tmp/tmux-1000/default", "id": "%5" } },
"sessions": [
{
"id": "1787a44e-244c-4c3c-aeea-40a74ff7ef8c",
"agent": "claude",
"state": "blocked",
"kind": "permission",
"turn": "00161c25-78f9-4c24-8799-5ed63c406153",
"since": "2026-11-03T05:20:28Z",
"cwd": "/home/me/src/api",
"runtime": "terminal",
"capabilities": ["send", "interrupt", "answer"],
"requests": [
{ "id": "3f9c2a01b6d4", "kind": "permission", "tool": "Bash", "since": "2026-11-03T05:20:28Z" }
],
"transcript": {
"path": "/home/me/.claude/projects/-home-me-src-api/1787a44e-244c-4c3c-aeea-40a74ff7ef8c.jsonl",
"format": "claude-jsonl"
},
"panes": [
{ "server": "/tmp/tmux-1000/default", "id": "%3", "evidence": "process", "view": "main" }
]
}
],
"panes": [
{
"server": "/tmp/tmux-1000/default",
"id": "%3",
"target": "work:1.0",
"cwd": "/home/me/src/api",
"command": "claude",
"agent": "claude",
"session": "1787a44e-244c-4c3c-aeea-40a74ff7ef8c",
"evidence": "process",
"view": "main"
}
]
}runtime is terminal for a session in its terminal's own agent process and
service for one in a background service (the Codex daemon, Claude Code's
supervisor, Pi or oh-my-pi running for a program: their rpc, json and print
modes, which they report).
transcript is where the agent writes the session's transcript, in the
agent's own format (claude-jsonl, codex-rollout, or pi-jsonl for Pi and
oh-my-pi's session files); tmag only says
where it is, and the file may not exist before the first turn. subagents
lists the session's running subagents. capabilities lists the verbs tmag
can carry to the session (see Control); each still
checks its gate when used, and an inbox it uses must be the session's
recorded socket. requests are the prompts it waits on (see
Answering). A pane without session runs an agent tmag has no proof for.
caller is who ran the command: its pane, and by the agent whose tool ran
it, as in events.
tmag watch prints one JSON document per line: first
{"type":"snapshot","seq":N,"sessions":[…],"panes":[…]}, then
{"type":"event","event":{…}} for every event after seq, and
{"type":"panes","panes":[…]} whenever the pane list changes (an agent starts
or exits in a pane, a pane moves or closes, a pane switches between a
session's main agent and a subagent). Events carry seq, time, agent,
session and event. An event with state reports the session in full:
state, kind, turn, cwd, runtime, transcript, subagents,
capabilities and requests are
then what the session is, and a field left out is empty. Every change to any
of them is such an event. event is the hook's name (for Pi and oh-my-pi,
the agent's own name for the event tmag's extension reports), SessionEnd
for a session that ended, whatever the agent calls that, or one of:
| Event | Meaning |
|---|---|
Attach |
A pane (pane) started showing the session, by evidence. |
Detach |
A pane (pane) stopped showing the session. |
Send |
tmag send delivered a prompt via pane (then through pane), service or inbox, bytes long. |
Halt |
tmag interrupt delivered an interrupt via pane (then through pane) or service. For Claude Code it reports the session, now idle. |
Answer |
tmag answer delivered a decision (allow or deny) on request, via hook or service. It reports the session: through the hook with the request closed, through the service before Codex reports what followed. |
Exit |
The session's process exited without SessionEnd; the session is gone. |
Send, Halt and Answer carry from, the pane the command ran in, and
by, the agent whose tool ran it (agent, and session and subagent when
known), when there is one (see Agents acting on agents).
A change is made where it lives, the session's record or the pane's options,
and then logged, best effort: if the tmag process that made it dies before
logging it, the session's next event, or the next snapshot, reports it. A
client that applies events to the snapshot and replaces its pane list with
each panes document stays current, and tolerates an event it has already
applied. Changes that come without a hook (a pane closes, an agent is killed,
a title shows another thread) are found by whichever tmag process looks next,
watch itself every two seconds.
Sequence numbers run without gaps through the retained log, from the current
time in microseconds when the log was created; treat them as ordered,
otherwise opaque integers. Whenever a watch cannot vouch that it sent every
event since the last, because events rotated away unread or the log was
recreated, it sends a new snapshot and goes on from it: replace both the
session collection and the pane collection whenever a snapshot arrives,
including when either is empty. After a disconnect, tmag watch --since <last seq> replays what was missed and sends the pane list, or starts with a
new snapshot when it cannot.
A snapshot is not an atomic image at seq: it is read after seq, so it may
already show changes whose events follow, and applying such an event again
changes nothing. A state event's since is when that state and kind began.
Over SSH, a remote client needs nothing else: ssh host tmag watch. A watch
ends as soon as nobody reads it, even with nothing to send: when its reader
closes the pipe, or when the connection of a command ssh runs without a
terminal drops.
Inside tmux, the same state is in pane options, read-only, for formats and
scripts that do not run tmag: @tmag_agent, @tmag_session, @tmag_state,
@tmag_kind and @tmag_since (Unix seconds) on every attached pane, and
@tmag_cmd, the pane's command when they were written. For example
tmux list-panes -a -F '#{pane_id} #{@tmag_agent} #{@tmag_state}'.
Exit codes: 0 ok, 1 error, 2 usage, 3 refused by the safety gate, 4
timeout. With --json, errors are also printed as
{"schema":"tmag/v2","error":{"code":…,"message":…}}; codes are usage,
not_found, ambiguous, refused:unbound, refused:busy,
refused:background, refused:subagent, refused:changed,
refused:idle, refused:unsupported, refused:self, refused:agent,
ended, no_reply, records_unavailable, timeout and error. On stderr,
a line starting with next: follows an error when tmag knows what to do
next.
What a hook accepts is bounded where it is read: a path longer than any path is dropped, names and ids are cut to 256 bytes, and a session keeps at most 32 pending prompts, 64 requests, running calls and background tasks, and 32 subagents. A session's record and its events stay small whatever an agent sends. Failures after a delivery are of another kind: tmag reports the prompt, interrupt or answer delivered but not logged, and does not claim it undone.
A session record tmag cannot read is left out of views and reconciliation,
and tmag doctor reports it; the session's next hook writes it anew.
tmag send hands a prompt to the session's own agent, never through a busy
pane. Its channel is an inbox or, for a Codex daemon thread, the daemon's
control socket; a person's prompt takes it while the session works, and an
agent's takes it in any state, with the pane as an idle fallback. An inbox
is a Unix socket the agent serves for messages: Claude Code's cross-session
socket, or the one tmag's extension serves in Pi and oh-my-pi. The session's
hooks record the socket and the process that serves it; send dials it and
proves the peer is that process, still running with the same start time
(SO_PEERCRED on Linux, LOCAL_PEERPID on macOS), and is refused unbound
otherwise. Under the session's lock, an inbox the record no longer names is
refused changed; the extension's request names the session it is for, and
a process that now serves another refuses it changed, delivering nothing.
A send racing a session switch in one Claude Code process may still reach the
session that replaced the one it named: the socket belongs to the process,
and tmag cannot close that race. The agent queues the prompt in any state,
so an idle session starts a turn and a working one reads it at its next step.
A Send event reports via pane, service or inbox and is logged before
the write; only an explicit refusal proves nothing was delivered — any other
error leaves that unknown. tmag keeps the prompt nowhere.
| Piece | Where | Removed by |
|---|---|---|
tmux plugin and tmag
|
$TMUX_PLUGIN_MANAGER_PATH/tmux-agent-experience/ |
removing the @plugin line, then prefix + alt + u
|
Agent plugins tmag and tmag-peers
|
each agent's plugin directory; for Pi and oh-my-pi, the tmux plugin's plugins/pi and plugins/omp, which they install by path |
the agent's plugin manager, for Pi and oh-my-pi before the tmux plugin |
| Pane state |
@tmag_* pane options, gone with the pane |
tmag uninstall --purge |
tmag serve |
a tmux window, while you keep it open, and @tmag_api_addr while it runs |
closing the window |
| Owner credentials |
$XDG_STATE_HOME/tmag/auth/, or TMAG_AUTH_DIR: metadata and verification digests |
tmag auth revoke, or tmag uninstall --purge
|
| Sessions and event log |
$XDG_STATE_HOME/tmag/v2/<realm>/ (default ~/.local/state/tmag/v2/<realm>/): one small file per live session, the current event file, with an 8 MiB rotation threshold, and one rotated file. v2 names the layout of the state, and the realm the process table tmag sees, one per container or machine and boot, so containers that share a home directory keep their sessions apart |
tmag uninstall --purge; ordinary reconciliation leaves other realms and other layouts' state alone |
| Locks |
<state dir>/locks/: at most 256 pane and 256 session lock files, beside the event log's |
removing the state directory with tmag uninstall --purge
|
| Session write temporaries |
<state dir>/sessions/<agent>/.tmp-XX: at most 256 per agent, one per session lock |
the next write under that lock |
| Answer sockets |
/tmp/tmag-<uid>/: one socket per answer hook waiting |
the hook, as it leaves; one killed before is removed by a later hook after a minute |
A state directory holds one layout of tmag's state. A tmag of another layout
keeps its state elsewhere: the default directory is named after the layout,
so an upgrade starts afresh beside the old state, which it neither reads nor
changes, and sessions reappear as their agents' hooks report them. Delete an
old layout's directory once no tmag of that layout runs. A directory named by
TMAG_STATE_DIR serves one layout: point it at a fresh directory when
upgrading across layouts.
A session record is written to the temporary of its lock and renamed over the record, so a reader sees one whole record or the other. The state directory is tmag's own; tmag does not defend it against other programs.
An answer hook listens on a socket of its own under /tmp/tmag-<uid>, a
directory tmag uses only if it belongs to the user alone, as tmux does for
its own sockets. The socket's name derives from the state directory and the
request, and the hook answers only messages naming its request. A refused
connection proves a hook gone. A hook that cannot listen leaves the agent's
own on-screen dialog in control.
Ordinary reconciliation leaves other realms and other layouts' state alone. Idle agents elsewhere may leave their metadata untouched for weeks.
tmag uninstall prints the exact removal steps.