Repository navigation
CLI Reference
Agent hooks find the plugin's binary on their own, and so do agents with the
tmag-peers skill. To use tmag from a shell or a script, put the plugin's
bin directory on your PATH.
$ tmag list
TARGET PANE AGENT STATE FOR ID CWD
work:1.0 %3 claude blocked (permission) 12s 1787a44e ~/src/api
work:2.0 %7 codex idle 4m 01a19fda ~/src/web
work:3.0 %9 codex unknown - - ~/src/web
- - claude working (background) 2m 5c2e90b1 ~/src/api
$ tmag send 01a19fda --wait "Review the diff in HEAD and list risky changes"
01a19fda idle
$ tmag read 01a19fda --last # the reply that ended its turn
$ tmag read 01a19fda --turns 3 # its last turns: prompts and replies
$ tmag send 01a19fda "The parser moved to internal/parse.go."
sent to 01a19fda (%7) seq 43
$ tmag interrupt 01a1 # stop the running turn
$ tmag request 1787 3f9c2a01b6d4 # what an open request asks
$ tmag answer 1787 3f9c2a01b6d4 allow # or: deny --message "not now"
$ tmag read %3 --lines 40 # recent pane output
$ tmag wait 1787 --for idle # block until the session is idle
$ tmag watch # JSON lines: a snapshot, then every changeEach row is a pane running an agent, followed by sessions no pane shows,
such as a Claude Code background session. A target is a session id or a
unique prefix of at least 4 characters, or a pane as tmux names it: any
target-pane tmux takes on the current server (%N, the work:1.0 that list
prints, a window name, {last}), which tmux itself resolves, or SERVER:%N
with a socket name (as for tmux -L) or path, as list prints a pane of
another server. wait on a pane that shows no session yet lasts until its
agent shows one, as an agent started there a moment ago does from its first
hook; until then the other verbs refuse the pane unbound.
A session's state comes from its agent's hooks alone, wherever the session runs:
| State | Meaning |
|---|---|
working |
A turn is running. Kind background means the main agent's turn ended while subagents or background tasks still run. |
blocked |
The session waits for you. Kind permission (tool or network approval) or question (also any dialog a Pi extension opens during a turn, and oh-my-pi's ask tool). It stays blocked until every open prompt, from the agent or any of its subagents, is answered. A prompt closes once no call of the tool it asked about is still running in the agent that asked, once that agent's calls settle or the agent stops, or when the main agent's turn ends; a prompt of a subagent still running outlives that turn. A prompt known only from Claude's delayed permission notification, such as a sandboxed command's network request, names neither, and the next finished tool closes it. |
idle |
Waiting for the next prompt. Kind error after a failed turn. |
unknown |
Reported by nothing yet. A pane shows unknown while its agent has not reported (startup, trust dialogs, plugin not installed) or tmag has no proof of the session it shows. |
A session ends with its agent's SessionEnd (in Pi and oh-my-pi, when it
quits or switches to another session), or when the process it runs in exits
without one. Optional last_hook_at is the session's last hook contact
in JSON and inspect, independently of the state's since: its record keeps
it, updated at most every ten seconds when nothing else changes, and an event
carries it as of the change, but contact alone logs no event. Contact time
never establishes state freshness, control authority or eligibility for
cleanup.
A session and the panes that show it are separate. A Claude Code, Pi or
oh-my-pi session runs in its terminal's own process, and so does Codex
started with --no-daemon; by default Codex runs every thread in a shared daemon, and
Claude Code runs background sessions under its supervisor. Their hooks then
come from a process no terminal owns, with an environment that names no pane,
so tmag never trusts $TMUX_PANE. A pane shows a session only on evidence:
| Evidence | Proof |
|---|---|
process |
The session's hooks descend from the pane's own agent process. Claude Code, Pi, oh-my-pi, and Codex run with --no-daemon. |
title-id |
Codex: the pane's terminal title shows the thread id. |
The attachment holds while the same agent process (pid and start time) runs
in the pane and, for Codex, while its title shows the session. A Codex pane
that shows one of the session's subagents stays attached with view
subagent. Bells, prefix + A and the pane border act only on attached
panes; a send typed into a pane needs one, while a person's working prompt
or an agent's takes the session's own channel. tmux's displays cannot show
doubt, so a guess is never shown as a fact. Thread names prove nothing: they
come from prompts and repeat.
For Codex in its shared daemon, turn on the thread-id title item once: run
/title in Codex and select thread-id. Codex saves the choice in its own
configuration. Until then, Codex sessions are listed with their state, and
Codex panes show unknown. The equivalent setting, for people who edit by
hand:
[tui]
terminal_title = ["activity", "thread-name", "project-name", "thread-id"]A pane that runs claude attach shows a background session tmag cannot
prove, and so shows unknown; the session is listed on its own row.
tmag carries a few verbs to a session, the same for every agent: send a
prompt, interrupt a turn, answer a request. Each has one gate, and which
channel carries it is tmag's business, chosen for the session's agent and
runtime, who sends, and what the send asks for:
| Session | send |
interrupt |
answer |
|---|---|---|---|
| Claude Code, terminal | pane while idle, inbox while working | pane | hook |
| Claude Code, background | inbox (a person's --wait is unsupported) |
— | hook |
Codex, daemon (runtime: service) |
service | service | service |
Codex, --no-daemon
|
pane while idle | pane | — |
| Pi, oh-my-pi, terminal | pane while idle, inbox while working | pane | — |
| Pi, oh-my-pi, serving a program | — | — | — |
For send, a person's prompt is typed into the pane only while the session
is idle and takes the session's own channel while it works. An agent's
prompt always takes the session's own channel, whatever the state, with the
pane as a fallback only while the session is idle and its inbox cannot be
proven; that channel is Claude Code's inbox, tmag's extension in Pi and
oh-my-pi, or the Codex daemon's control socket.
A session's capabilities list the verbs some channel carries to it; a verb
nothing carries is refused with unsupported. They follow from the agent
and runtime alone, so send is listed before an agent's inbox is proven; the
send itself still needs a proven channel, or a pane while the session is
idle. Every delivery reports its channel as via, in its output and its
event.
tmag read ID --last prints the reply that ended a session's last turn,
read from the agent's transcript at the moment of the call: the text of
Claude Code's last assistant message, Codex's last_agent_message of the
turn's end, or the last assistant message of a Pi or oh-my-pi session file. tmag keeps nothing of it. It reads only an idle session (busy
otherwise), and only the turn the session's hooks reported, waiting a few
seconds for the agent to write that turn's end; a turn that ended without a
reply, or a transcript that does not catch up, is the error no_reply. It
needs no pane, so it reads sessions in the Codex daemon and Claude Code's
background sessions too. --json adds the session and the turn. Without
--last or --turns, read prints the pane's recent text.
tmag read ID --turns N prints a session's last turns, 1 to 20, oldest
first, in any state: each turn's prompts, the one that started it and those
that arrived while it ran, each quoted, then its reply. A turn's reply is the
one --last reads once the turn ends; while it runs, what the transcript
holds so far, and Codex writes it only at the end. A prompt the transcript
says someone other than the person sent is marked with its sender, such as
(peer) for another session's message or (task) for a background task's
notice. Each text is cut at 16 KiB, and of a turn's prompts the first and
the last nine are kept. tmag keeps nothing of it. --json gives the session and turns, each with
its id, its prompts (text, and from when marked) and its reply.
tmag send <target> [--wait | --reply] [--timeout D] [--json] [text | -]
delivers a prompt now by default: an idle session starts a turn with it, and
a working one reads it at its next step. --reply delivers the same way and
asks the receiver to answer with tmag reply when it is done; it needs a
caller whose session tmag proves. --wait asks for a turn of its own: the
session must be idle, the prompt starts a turn, and the command waits until
that turn ends or blocks on a request; --timeout (30 minutes by default)
bounds that wait. --wait and --reply cannot be combined.
Who sends decides which channel carries the prompt. A person's prompt keeps
the person's authority: while the session is idle it is typed through the
pane that shows it, by process or title-id, when that pane's agent holds
its terminal and shows the main agent; a suspended or backgrounded agent, or
a pane showing a subagent, is refused. While the session works, a person's
prompt takes the session's own channel instead, so nothing is typed into a
busy pane. An agent's prompt always takes the session's own channel,
whatever the state, with the pane only as a fallback while the session is
idle and its inbox cannot be proven. That channel is Claude Code's inbox,
tmag's extension in Pi and oh-my-pi, or the Codex daemon's control socket.
A Codex session run with --no-daemon has no channel but its pane, so it
takes a prompt only while idle; a person's --wait cannot reach a Claude
Code background session, which has no pane.
The session must have nothing of tmag's unconfirmed. A --wait prompt is
held until the agent starts its turn; an asynchronous prompt until the main
agent reports again. While either mark stands another send is refused
busy; both release after 15 seconds. A working session with no channel is
refused busy rather than typed into. An agent's send to its own session
is refused self, and a session that ends before the prompt is written is
the error ended.
A pane send is a bracketed paste followed by Enter. Control characters are
removed first, so relayed text cannot end the paste early or press keys. A
draft left in the agent's composer is joined to the prompt: neither agent has
a key that clears a draft without side effects, so tmag does not try. Hooks
update a session under the same session lock, so the turn a prompt starts is
always logged after its Send event.
send --wait reports the state the session reached: ID idle when the turn
is over, or ID blocked (KIND) when it stopped on a request. Input that
starts no turn, such as a slash command, releases the session after 15
seconds, and send --wait then reports "started": false. wait and send --wait end with error code ended when the session ends; a --wait that
times out after delivery says the prompt was delivered and what became of it
unknown, so run tmag wait again rather than sending it twice.
The Send event is logged before the prompt is written. An explicit refusal
after the write proves nothing was delivered; any other error leaves whether
the agent took the prompt unknown, and the error says so. A gate refusal
exits 3; a channel that took nothing, or an unknown outcome, exits 1 and
says which.
tmag reply <target> [--timeout D] [--json] [text | -] answers a prompt that
asked for a reply, under the first line [tmag] Reply from … Do not reply to it. It delivers now through the asker's own channel — an inbox, or the Codex
daemon's control socket — whatever the asker's state. A pane-only asker gets
it typed into its pane while idle; while that asker is busy, reply retries
until --timeout (one minute by default) on busy refusals alone. Only an
agent whose session tmag proves can send a reply. A timeout exits 4 and
says whether anything was delivered: a refusal or a channel that took nothing
proves nothing was, so it may run again; any other error leaves the outcome
unknown, and it must not be sent again. Output is replied to ID (CHANNEL) seq N, with the pane id when typed into a pane.
A thread in Codex's daemon takes prompts and interrupts through the daemon's
control socket ($CODEX_HOME/app-server-control/app-server-control.sock),
whether or not a pane shows it; its terminals show the turn as if typed.
tmag connects for one command and leaves. It acts only when the socket's
process is the one the thread's hooks run in, or an ancestor of it, and asks
the daemon first: send without --wait takes a thread that is idle or
active, --wait requires idle, and interrupt requires a running turn. The
daemon joins a running turn instead of refusing a prompt, so a send without
--wait takes the turn as it is; --wait keeps tmag's idle gate, so its
prompt starts a turn of its own. The Send or Halt event is logged before
the daemon is asked, since the daemon runs the turn's hooks before it
answers. The first client to connect to a fresh daemon may be recorded as the
originator of its later threads; tmag connects only to a daemon that already
runs the thread.
While a session is blocked, each prompt it waits on is a request in its
requests, with an id, a kind (permission, question or plan), the
tool asked about and, for a subagent's prompt, its agent. tmag request
shows what a request asks, the tool and its input, relayed from where the
agent holds them and never stored. tmag answer TARGET REQUEST allow|deny
decides it; --message goes to the agent with a deny, and a question is
answered with --answers '{"question text":"chosen label"}'.
For Claude Code the plugin's PermissionRequest hook is tmag answer-hook:
it reports the prompt like every hook, then waits for tmag answer while
Claude's own dialog is on screen. Whoever answers first decides, in the
terminal or through tmag; when the dialog is answered in the terminal, the
hook leaves. It waits in background sessions too, so their prompts can be
answered with no terminal at all. On any failure, or after 590 seconds, it
leaves without a word and the dialog alone decides. With @tmag-answer
off it does not wait; answer is then refused with unsupported, for
every agent.
For a thread in Codex's daemon, answer joins the thread through the
daemon's control socket, under the same proof as a send to the daemon. The daemon replays
the approvals still waiting, each naming the tool call it is about, and tmag
answers the one for the request's call (a command approval for Bash and
write_stdin, a file change for apply_patch), then leaves once the daemon
reports it resolved. Codex's PermissionRequest hook does not name the call,
so a request is about the one call of its tool the agent was running when it
asked; when the agent ran several, any of them may be asking, and the request
is answered only in the agent (ambiguous). Approvals of other tools, such
as MCP tools, are answered only in the agent (unsupported). Codex shows its dialog only
after its hooks have run, so no hook waits there. A Codex decision carries no
message, and a Codex session run with --no-daemon can be answered only in
the agent.
Pi and oh-my-pi are answered only in the agent: a Pi dialog belongs to the
extension that opened it, and oh-my-pi's approvals and ask tool to its own
UI, which no channel reaches. tmag still reports them as requests, so tmag inspect and alerts show what the session waits on.
answer checks under the session's lock that the request is still open.
Through the hook it logs Answer once the hook has taken the decision, and
the request closes with it: the event reports the session, working on if
the prompt was its last. Through the daemon it logs Answer before the
daemon is told, still blocked, and the request closes when Codex reports
what followed (the call, or the agent moving on); Codex 0.166 takes
decline although its approvals do not list it. Of two answers to one
request at once, one is delivered and the other refused with changed. A
request answered in the
terminal a moment before may still take one that the agent then ignores;
what the agent did shows in the events that follow. A sandboxed command's
network request reaches no hook, and can be answered only in the agent.
tmag interrupt stops a session's running turn, or declines the prompt it is
blocked on, which ends the turn too. Through a pane it presses Escape once,
only while the main agent is working or blocked, when its pane's agent holds
the terminal: an idle session is refused with idle. Escape twice
on an empty composer opens a menu in these agents, so after an interrupt
another is refused until the agent reports again, or for 90 seconds. Codex
then reports Interrupt, and Pi and oh-my-pi the end of the aborted turn,
and the session is idle. A blocked Pi or oh-my-pi declines its dialog on
Escape and decides itself whether the turn goes on, which it reports. Claude Code reports
nothing, not even its idle notification, so tmag records what it delivered:
the Halt event reports the session idle, its prompts declined.