Repository navigation
Releases
v0.7.0
tmag 0.7 reads a session's last turns, each prompt beside its reply, for a client that shows a session as a conversation.
Read a session's turns
tmag read ID --turns Nprints 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, then its reply. Once a turn ends, its reply is the oneread --lastgives; while it runs, what the transcript holds so far. A prompt the transcript says someone other than the person sent is marked(peer)for another session's message or(task)for a background task's notice. Each text is cut at 16 KiB, and tmag keeps nothing of them.--jsongives the session andturns, each with itsid,promptsandreply.tmag servegives the same throughGET /v2/read?turns=1..20.
Smaller changes
read --lastreads a transcript as--turnsdoes. A Claude Code local command such as/modelno longer stands in for the last turn, so--lastgives the reply of the turn before it, and an interrupted Codex turn'sno_replysays that the turn ended without a reply.
Contract
/v2/readtakesturnsbesidelastandlines, one of the three. The schema staystmag/v2, and the state directory keeps its layout: 0.6 state carries over as it is.
What's Changed
Full Changelog: v0.6.0...v0.7.0
v0.6.0
tmag 0.6 delivers a prompt now, through each agent's own channel, and takes the panes tmux names.
Send through the agent's own channel
tmag sendis the one delivery verb. By default and with--replyit delivers now: through Claude Code's cross-session inbox, tmag's extension in Pi and oh-my-pi, or the Codex daemon's control socket. An idle session starts a turn; a working one reads the prompt at its next step, and the Codex daemon joins the active turn. A prompt is never typed into a busy pane.--waittakes a turn of its own once the session is idle, andtmag read ID --lastreturns that turn's reply.- An agent's prompt goes through the session's channel in any state, with the pane only as an idle fallback, and its first line names the proven sender. A person's prompt carries no sender line: it is typed into an idle pane, and goes through the channel while the session works and always to a Codex daemon thread.
replyis delivered now through the asker's channel. - An inbox is proven when its listener is the agent process that named it, checked again under the session's lock. A Claude Code background session is reached through its inbox.
- Claude Code applies its own inbound controls: a session that bypasses permission prompts holds a sent prompt for its person unless its
crossSessionInboundisaccept.
tmux targets and peers started in tmux
- Every verb takes any target-pane tmux takes on the current server (
%N, thework:1.0thatlistprints, a window name,{last}), resolved by tmux itself, orSERVER:%Nfor a pane of another server.list,inspectand every verb's report name such a paneSERVER:%Ntoo. A target tmux cannot find is refused. tmag waiton a pane lasts until its agent shows a session, so an agent can start a peer in a tmux window of its own and work with it through tmag. Thepeersskill teaches this, starting tmux ascommand tmuxpast any shell alias; until the session shows, the other verbs refuse the paneunboundwith anext:line that says to wait.tmag inspectlists a session's open requests with the id thattmag requestandtmag answertake.
Smaller changes
- tmag recognises Claude Code run as
claude.exe, as its npm package runs it, and its background supervisor's processes. tmag doctornamesmonitor-bell offandallow-set-title offwith theset -gline that restores each, and changes nothing.- The installer publishes the binary with one atomic rename. An interrupted install no longer leaves a lock that stops the next one.
- Agent configuration reached through a symlink is read.
- A tmag installed with mise is no longer a supported channel: the plugin keeps its binary in its own
bin/.
Contract
- A
Sendevent reportsviainboxbesidepaneandservice. The schema staystmag/v2, and the state directory keeps its layout: 0.5 state carries over as it is.
Website
- tmag has a landing page, with onboarding and best practices in English and Chinese, published from each release: https://chralpha.github.io/tmux-agent-experience/
Checked against Claude Code 2.1.319, Codex 0.167, Pi 1.5.0 and oh-my-pi 18.18.6.
Upgrading
prefix + U updates the plugin, which fetches the 0.6.0 binary on its next load; then prefix + M-a brings the agent plugins and the peers skill to 0.6.0. Codex asks again to approve tmag's hooks (/hooks). See Installation and Updates.
What's Changed
- fix(proc): recognize Claude Code run as claude.exe by @ChrAlpha in #12
- test(e2e): run panes under /bin/sh and leave no core dumps by @ChrAlpha in #13
- feat: send through each agent's own channel by @ChrAlpha in #14
- feat: take tmux targets, wait for peers started in tmux, and thin tmag by @ChrAlpha in #15
- fix(cli): list open requests in tmag inspect by @ChrAlpha in #16
- fix: name panes of other servers and start peers through command tmux by @ChrAlpha in #17
- docs: add a landing page published from each release by @ChrAlpha in #18
Full Changelog: v0.5.1...v0.6.0
v0.5.1
tmag 0.5.1 names its hooks in Codex.
Codex
- Codex's
/hookslists tmag's hooks as "Reporting state to tmag" instead of "Unnamed hook", so they are easy to tell apart from other hooks when you approve them. - When one of them runs past Codex's reveal delay, Codex shows that text in place of "Running hook".
- Checked against Codex 0.167.0.
Upgrading
prefix + U updates the plugin, which fetches the 0.5.1 binary on its next load; then prefix + M-a brings the agent plugins to 0.5.1. Codex asks again to approve tmag's hooks (/hooks), now listed by name. See Installation and Updates.
What's Changed
Full Changelog: v0.5.0...v0.5.1
v0.5.0
tmag 0.5 knows two more coding agents, Pi and oh-my-pi, next to Claude Code and Codex.
Pi and oh-my-pi
- Neither has hooks, so tmag ships an extension for each that reports what changes, in order and without holding up the agent. Their panes show their sessions on process proof, with states, bells, the picker, the status line and
jump, as for the other agents. sendandinterruptreach them through their pane, andread --lastreads the reply from their session file (pi-jsonl). A dialog of a Pi extension, oh-my-pi'sasktool and its tool approvals block the session; they are answered only in the agent.- They work with the other agents: the
peersskill comes to them too, and tmag proves their tools as callers throughPI_SESSION_ID. - A Pi or oh-my-pi run for another program (rpc, json and print modes) is a service: no pane shows it and nothing types into the program that runs it.
- Checked against Pi 1.5.0 and oh-my-pi 18.18.6.
Setup
prefix + M-ainstalls tmag's packages in Pi and oh-my-pi from the tmux plugin's own directory (pi install,omp plugin install), so they always match the binary and update with the plugin. It needs the tmux plugin, installed through TPM;tmag doctorsays when it is missing.tmag doctorchecks all four agents at once, andtmag uninstalllists the commands that remove Pi's and oh-my-pi's packages, before the plugin they come from.
Contract
- A session's end is reported as
SessionEndfor every agent. Pi's and oh-my-pi's other events keep their own names, such asmessage_endandagent_settled. agenttakes the valuespiandomp, andtranscript.formatthe valuepi-jsonl.
Upgrading
prefix + U updates the plugin, which fetches the 0.5.0 binary on its next load; then prefix + M-a brings the agent plugins to 0.5.0 and connects Pi and oh-my-pi where they are installed. Codex asks again to approve tmag's hooks (/hooks). See Installation and Updates.
What's Changed
Full Changelog: v0.4.0...v0.5.0
v0.4.0
tmag 0.4 makes the state layer thin, leaning on tmux, the kernel and plain files, and lets agents notice and settle work they share.
Breaking changes
- The JSON contract is
tmag/v2and the HTTP contracttmag/http/v2, under/v2/. Clients move with tmag. tmag watchmay send a new snapshot at any time, whenever it cannot vouch that it sent every event since (the log rotated past it, or was recreated); a client rebuilds its view from it.tmag waitdrops--after; it andsend --waitread session records.- Hook contact alone logs no event; a session's
last_hook_atis kept at most every 10 seconds and reported with the session. - State lives in a new default directory,
$XDG_STATE_HOME/tmag/v2/<realm>. 0.4 starts empty there and leaves the 0.3 directory as it is; running sessions reappear with their next hook. Remove the old directory once you no longer need it.
Agents working with each other
- The
peersskill looks at other agents when a signal says one shares your work (changes you did not make, branch switches, force-pushes, stopping shared processes) or when you ask, and never routinely. - After a refusal or failure, the verbs agents use print a
next:line on stderr saying what to do, claiming no more about a prompt's delivery than tmag proved. tmag read --lastright aftersend --waitwaits for the reply Claude Code writes after its Stop hook.
Reliability and performance
- What hooks accept is bounded where it is read, so records and events stay small whatever an agent sends.
- Session records and pane options are the truth; the event log tells what changed, best effort, numbered without gaps.
- A Codex pane proven by its process is no longer replaced by a title inference, so its first turn shows no Detach/Attach flicker.
- Six Codex daemons in a soak: 426 hooks/s, p99 20 ms, 0.29 events per hook, no hook errors (0.3.0: 404 hooks/s, p99 27 ms).
Upgrading
prefix + U updates the plugin, which fetches the 0.4.0 binary on its next load; then prefix + M-a brings the agent plugins to 0.4.0. Codex asks again to approve tmag's hooks (/hooks). See Installation and Updates.
What's Changed
- fix: bound state growth and enforce replay and hook deadlines by @ChrAlpha in #1
- refactor: simplify long-running reliability by @ChrAlpha in #2
- ci: shorten race checks and fix answer hook timeouts by @ChrAlpha in #4
- fix(attach): keep a pane's proof when only its evidence changes by @ChrAlpha in #6
- fix(state): let readers observe atomic replacement of published metadata by @ChrAlpha in #5
- fix(read): wait for a reply Claude Code writes after its Stop hook by @ChrAlpha in #7
- feat(peers): look at peers on signals and say what to do after refusals by @ChrAlpha in #8
- refactor!: thin the state layer onto records, pane options and plain files by @ChrAlpha in #9
Full Changelog: v0.3.0...v0.4.0
v0.3.0
tmag 0.3.0 adds a local, owner-authorized HTTP API and notification command hooks while keeping tmux as the entry point.
Local HTTP API
tmag serveexposes one local instance through the independently versionedtmag/http/v1contract.prefix + M-ropens it in a tmux window; closing the window stops it.- Clients can inspect sessions, subscribe to resumable SSE updates, read replies and requests, and send prompts, interrupt turns or answer approvals through the existing control gates.
- The listener binds loopback. Remote deployments provide encrypted transport and explicitly configure public hosts and browser origins. Web/mobile interfaces and multi-machine gateways are maintained as independent clients.
Owner credentials
tmag auth issue,pair,listandrevokemanage independently revocable bearer credentials. All credentials represent the same owner.- The persistent store keeps verification digests and metadata, independently of boot/PID session realms. Set
TMAG_AUTH_DIRseparately for independent deployments sharing a home directory. - Pairing invitations are short-lived and single-use. Revocation closes existing subscriptions; already admitted control operations finish within their timeout. Proven agent tools retain their agent authority and cannot issue owner credentials.
Notifications and reliability
@tmag-notifyruns a configured notification command when an agent waits for the owner or finishes a turn, including sessions without panes. It exports metadata only and runs separately from the hook with a bounded lifetime.- Shell variables and literal escapes in notification commands are preserved on tmux 3.4, whose option display adds an extra escaping layer.
tmag watchexits when its reader disconnects, including quiet SSH streams.- End-to-end contract tests verify that rebuilding state from the event stream agrees with
tmag list --jsonthroughout control scenarios.
The existing tmag/v1 CLI/state contract is preserved; owner control events add an optional credential id.
Updating
Update the TPM plugin with prefix + U, then connect/update the agent plugins with prefix + M-a. In Codex, approve the updated hooks with /hooks when prompted.
v0.2.1
tmag 0.2.1 keeps containers that share a home directory from ending each other's sessions.
Fix
- Each process table gets its own state directory. tmag proves sessions from the processes it can see. Containers that share a home directory, such as devcontainers sharing a
~/.localvolume, used to share one state directory, so each container's tmag ended the other's sessions: their processes were invisible to it. A session would showunknownseconds after it started. - The state directory is now
$XDG_STATE_HOME/tmag/<realm>/. The realm is the boot and PID namespace on Linux, and the boot on macOS.TMAG_STATE_DIRstill names the directory itself. tmag prune, which the picker key runs, removes state nobody has written for 30 days: other realms' directories, and the state tmag 0.2.0 and earlier kept directly intmag/.tmag uninstall --purgeremoves only this realm's directory.
Updating
prefix + U, then prefix + M-a. Sessions that are already running show unknown until their next hook, because the new directory starts empty.
Full Changelog: v0.2.0...v0.2.1
v0.2.0
tmag 0.2.0 lets people and agents act on the agents in tmux panes, not only see them, and lets agents work with each other.
Control surface
send,interrupt,requestandanswerwork the same for Claude Code and Codex, wherever a session runs. tmag picks the channel itself: the session's proven pane, the Codex daemon's control socket, or Claude Code's permission hook.- Every verb rechecks the session's state under its lock and delivers once. Its event records
fromandby. A channel that can't carry the verb is refused asunsupported. - Permission prompts become requests with ids. In Claude Code,
tmag answer-hookwaits beside the dialog, which stays on screen, and whoever answers first decides.@tmag-answer(on,agents,off) says who may answer. - Callers are proven from process ancestry. An agent never acts on its own session.
Agents working with each other
- New
tmag-peersplugin for each host, holding thepeersskill.prefix + M-ainstalls it;@tmag-peers offremoves it. - When an agent sends a prompt, tmag writes its first line (
[tmag] From …) from the proven caller. People's prompts get no such line, and no prompt may start with[tmag]itself. send --replyandtmag replylet an agent take its answer later as a prompt.tmag read ID --lastreads the reply that ended a session's last turn from the agent's transcript and keeps nothing.
Checked live with Claude Code 2.1.318 and Codex 0.166, in both directions.
Fixes
- The Codex plugin declares the 3 s timeout Codex allows
SessionEndandInterrupthooks, which removes two startup warnings.
Contract
tmag/v1 gains only optional fields: transcript, capabilities, requests and subagents on sessions; every state event now reports the whole session; caller in list --json; Halt and Answer events; and the refusals unsupported, idle, self and agent.
Updating
prefix + U updates the plugin, which fetches this binary on the next load. Then prefix + M-a brings the agent plugins to 0.2.0 and adds tmag-peers. Codex then asks you once to review tmag's changed hooks. Trust them in /hooks: until you do, they don't run.
Design records: ADR 0001, ADR 0002.
Full Changelog: v0.1.0...v0.2.0
v0.1.0
Full Changelog: https://github.com/ChrAlpha/tmux-agent-experience/commits/v0.1.0