Skip to content

CLI Reference

ChrAlpha edited this page Nov 13, 2026 · 8 revisions
🇬🇧English | 🇨🇳中文

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.

Use

$ 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 change

Each 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.

States

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.

Sessions and panes

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.

Control

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.

Reading a reply and turns

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.

Sending

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.

Replying

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.

Through the Codex daemon

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.

Answering

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.

Interrupting

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.

Clone this wiki locally