Skip to content

Agent Collaboration

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

Agent Collaboration

Agents use the same verbs, run from their tools, and tmag tells who runs one the way it tells which pane shows a session: from the process table. A command whose ancestors include an agent's process is that agent's; its session is one of those the agent's process runs, named by the variable the agent sets for its tools (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, PI_SESSION_ID in Pi and oh-my-pi), or the only one. The variable alone proves nothing, and when nothing tells which session it is, the agent is known and its session is not. tmag list marks the caller's own session, and --json reports the caller as caller.

Every Send, Halt and Answer records where it came from: the pane, as from, and the agent, as by. An agent's verb on its own session is refused with self: the turn it would prompt, stop or answer is the one running the command. An answer stands in for the person's decision, so an agent may give one only when @tmag-answer is agents; otherwise it is refused with agent. This keeps an agent from approving its own or another agent's prompts by accident, and the log shows every decision an agent made. It is no security boundary: an agent can type into any pane with tmux itself.

Agents do not use these verbs unless told about them: asked to message another agent, they type into its pane with tmux send-keys and judge its state from its screen. The tmag-peers plugin is what tells them. Its skill, peers, covers when to look at and act on another agent, the verbs, and to talk to agents only through tmag: tmux opens windows, tmag talks to agents. An agent looks when the person asks it to involve one, or on a signal that a peer shares its work: changes it did not make, or a branch switch, history rewrite or process stop it is about to make. It never checks peers routinely. It acts when the person asks, when a peer's prompt asks within the person's work, or, on its own, to settle a collision with a peer in the same repository: it leaves the peer's changes alone, tells the person, and sends it one short message (tmag send) only if that settles the collision. What to do after a refusal or an error comes from tmag itself, on the line after it, starting with next:. In Claude Code the plugin puts tmag on the agent's PATH; in Codex, Pi and oh-my-pi the skill runs it from its own directory. Either way it is a launcher that runs the binary the agent's hooks run.

An agent the person asks for a peer that does not run yet starts it in a tmux window of its own, where the person can watch it and take it over, and works with it like any other peer:

pane=$(command tmux new-window -d -P -F '#{pane_id}' -c "$PWD" claude)
tmag wait "$pane" --for idle --timeout 2m
tmag send "$pane" --reply - <<'EOF'
Review the parser in internal/parse.go and list the bugs you find.
EOF

tmag wait on the pane lasts until the new agent shows its session, which Claude Code, Pi and oh-my-pi do as they start. Codex shows its session only from its first prompt, so it starts with the task as its argument, and the sender reads the answer with tmag read --last once it is idle.

A prompt carries no sender of its own, so when an agent sends one, tmag writes its first line from the caller it proved: which agent and session sent it, and how to answer. An agent without the skill can follow it too:

[tmag] From claude 1787a44e-…, another agent. Answer in your final message.
[tmag] From claude 1787a44e-…, another agent. When done, send your answer on stdin to: tmag reply 1787a44e-… -
[tmag] From claude 1787a44e-…, another agent. No answer needed.
[tmag] Reply from codex 01a19fda-…, another agent, to your prompt. Do not reply to it.

The first is what send --wait writes, for a sender that waits for the turn and reads the answer with read --last; the second is what send --reply writes, for a sender that ends its turn and takes the reply as its next prompt; the third is what send writes without a flag, for something a peer should know now, and asks for no answer; the fourth is what tmag reply writes. A prompt given to send or reply may not itself start with [tmag] (a usage error), so a first line that does was written by tmag about an agent it proved. A person's prompt gets no such line. An agent with the skill treats such a prompt as a colleague's request rather than the person's; a line ending No answer needed. is taken into account and not replied to; and it does not answer a reply. Like the rest of the gate, this holds for prompts tmag delivers; it is no security boundary against text typed into a pane by other means.

A send without a flag delivers now through the peer's own channel — an inbox, or the Codex daemon's control socket — whatever its state: an idle agent starts a turn, and a working one reads the prompt at its next step. The pane is only the fallback while the session is idle and its inbox cannot be proven. Choose the response you need: tmag send ID - for what a peer should know now, which gets the line No answer needed.; send --reply for long work, whose answer arrives later as a prompt; send --wait for a short question, which needs the peer idle and starts a turn of its own. Claude Code labels every inbox message as from another session and applies its own inbound controls: a session that bypasses permission prompts holds a sent prompt for its person unless its crossSessionInbound is accept, and tmag reports only that it wrote the message.

tmag reply writes the reply line and delivers now through the asker's own channel — an inbox, or the Codex daemon's control socket — whatever its state. A pane-only asker gets it typed into its pane while idle; while it is busy, tmag reply retries until --timeout (one minute by default) on busy refusals alone. It exits 4 on a timeout 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. Only an agent whose session tmag proves can send a reply or ask for one.

Clone this wiki locally