v0.1.3

n on another machine's row in taw app now makes the session on that machine. It opens that machine's own picker, titled new session on studio, at once; it says asking studio for its folders while taw there lists them, then fills with that machine's zoxide folders and [sessions] project_dirs, a folder that already has a session tagged running. Pick a folder, or type a path or a zoxide term and press Enter: the folder, the session's name and its create hooks are that machine's own, no client over there moves, and the app goes in when the session's row shows up, as long as the cursor is still on the row you pressed n on. The popup does not do this: on another machine's row it says the row is read only, as r, x and w do. Where taw on that machine is older than 0.1.3, n says update taw on studio to make sessions there from here at once.

Two commands came with it, and work on their own too. taw session candidates --json prints what the n picker would list on the machine it runs on, with no tmux server needed. taw open --no-switch makes or finds the session and moves no client; taw open --json now names the folder it opened as dir.

After taw app, prefix + L goes back to where you were. Before, going into a session from the app, or going back to tmux when the app ended, gave tmux a new client with no last session, so prefix + L said Can't find last session. The app now attaches through the session you came from, in the same command line. A session you came from that is gone, or is the one you are going into, is left out, and you go in as before. This is for this machine's sessions; going into another machine's session over ssh is unchanged.

taw now marks an agent as seen only when someone is looking at its pane. That attach passes through the session you came from, and tmux ran taw's seen hooks for it, which could mark an agent seen that nobody had looked at (so a done agent became idle unread). The hooks now run taw seen --if-looked-at, which checks that a client shows the pane when the hook runs.

With two machines or more, the status line while the popup is open, and the top line of taw app, lead with the machine count, for example taw · 3 machines · 6 sessions · 7 agents. With this machine alone nothing is added. On a narrow top line the clock is dropped before the machine count.

Rows drawn from your own row template ([ui.sidebar.agents], [ui.sidebar.sessions]) now line up in columns down the list: a column is as wide as the widest value in it, up to 24 columns, over every row the list holds, so scrolling moves nothing. A token hidden by a rule leaves its column blank in the middle of a row, so the tokens after it stay in line. Template rows are also lit as the popup's rows are: an agent row that needs you is in its state's colour, bold while it is blocked, and the row of the window its session has open is lit too. A token with its own fg, or one a rule restyled, keeps its own colour. taw's default rows are unchanged.

The try page's previews now look like each agent. The Claude, Codex and OpenCode screens use those agents' own words and say each thing once, the top line names a machine that is not answering, and picking a width sizes the window again.

If you have several machines, update taw on every one of them: the far n and its picker need 0.1.3 on the machine you make the session on, and the machine you run taw app on needs it for everything else. After you update, restart taw app if it is running, since a running app keeps the old code. Reload the plugin (prefix + I with TPM, or source-file on your tmux.conf) so the seen hooks use --if-looked-at; sourcing it again replaces the old hook lines rather than stacking them.

Full Changelog: v0.1.2...v0.1.3

v0.1.2

The screen says each thing once. While the popup is open, taw's status line holds the session and agent counts and the clock; what needs you is on the list's border, so the status line no longer repeats it. taw app's top line is the same: the counts and the clock. A machine header shows its counts only when two or more machines in the list have agents, since with one they would only repeat the rows.

An away machine is still named once. Its header says it is away; where no header is drawn for it (the flat layout, or a filter or view that hides it), the top line says so instead, for example studio, pi not connected. On a narrow line the clock goes first.

The list keeps still while a machine is away. Before, its width followed the machine's words, so it jumped on every reconnect try (connecting… against not answering, last seen 2m ago, trying again in 30s). Now the rows alone set it, and a header short of room drops the countdown first, then when it was last seen. A machine that waits for you (a key to add, a host key to accept, a taw to install or update) always shows what to do, in a short form such as ssh could not log in: run ssh-add when its whole sentence does not fit.

Rows drawn from your own row template ([ui.sidebar.agents], [ui.sidebar.sessions]) keep the session numbers, the row letters and the tree lines while [ui] labels is on, which it is by default. Before, those rows lost them, though the keys still worked.

The README and the site now compare taw with herdr, workmux and tmux's own plugins in one table, and the demo, the screenshots and the try page show calmer rows. They use a row template; taw's default rows are unchanged.

If your own status line shows @agent_wizard_status, nothing changes: the option is still set.

After you update, restart taw app if it is running: until then the popup reads the machines' words from the old app, and a machine that waits for you may lose what to do in a narrow list.

Full Changelog: v0.1.1...v0.1.2

v0.1.1

taw app picks up edits of [machines] while it runs: a machine you add shows its sessions within about two seconds of saving the config, and a machine you remove goes, along with its connection. Machines you did not touch keep their connections. A bad edit keeps the machines the app already has and says what is wrong once; fixing the file applies it.

Going back to the app's list from a session no longer flashes tmux's exit line ([detached (from session ...)]) at the top left, and it no longer piles up behind the list.

Known limit: a program started by a detach-client -E binding of your own, pressed in a client the app started, now sees a pipe where it asks for a terminal, and what it writes last as it ends is not shown when it looks exactly like tmux's own exit line, such as [exited].

Full Changelog: v0.1.0...v0.1.1

v0.1.0

taw 0.1.0, the first public release.

tmux-agent-wizard (taw): herdr's detection engine for 22 coding agents, as a plugin for the
tmux you already run. It knows which coding agent runs in each tmux pane, whether it is
working, blocked, done or idle, and takes you to the one that needs you. Your herdr
config.toml means what it meant once you copy it to ~/.config/tmux-agent-wizard/, and there
is no central daemon (one small watcher per pane, about 9 MB each).

The popup

prefix + A opens one tree: every tmux session, the panes under it and the worktrees whose
session you closed. Each agent shows its state, its task and how long it has been that way.
The border counts what needs you. 1-9 jump to a session, / filters the tree, matching
only what its rows show, and ? lists every key.

Next up

Tab moves the cursor to the next agent that needs you (blocked, or finished and not looked at
yet), and Enter goes there. prefix + O goes there from anywhere in tmux, without opening
the popup.

Agents

22 agents, detected with herdr's own engine and its bundled manifests: Claude Code, Codex,
Gemini CLI, OpenCode, Copilot CLI, Cursor, Amp and 15 more, plus rules of taw's own so a
Claude Code that is still working does not read as done. An agent started through npm or a
wrapper script, or running inside Docker, Podman, nerdctl, Apple's container or sbx, is
recognised too, with nothing set, and one suspended with Ctrl+Z keeps its name, its session and
its hook while its process stays alive behind the shell. An agent outside the 22 shows as a
plain pane.

Restore

Save and restore every session. 18 agents (Claude Code, Codex and OpenCode among them) reopen
in their own conversations once the agent's hook is installed (taw integration install <agent>). Without the hook, an agent's pane comes back as a pane. A Claude pane comes back
with the flags it was started with, --model among them, at the effort its last turn ran at.

Hooks

Run a command of your own on any event, such as an agent finishing or a session opening, from
the [hooks] table of the config.

Notifications, and the phone

When an agent blocks or finishes: in the tmux status line, in your terminal (over ssh too), or
as a macOS or Linux notification. taw sends nothing to a phone itself: a command of yours does,
and the Notifications page shows one for ntfy (https://27medkamal.com/tmux-agent-wizard/notifications/).

Agents in a sandbox

taw sandbox, typed in a pane, runs an agent there in a container, through a profile: a plain
script you can read. The popup marks it, and restore brings it back inside its sandbox. A
sandbox limits accidents, such as an rm -rf ~; it is not a wall against an agent that is
trying to get out. It needs Docker (or Podman, by a line in the profile). The sandbox is in
beta: no real coding agent has been run inside it yet.

Remote machines

taw lists every machine's agents in one list, over your ssh. taw app, in a terminal, shows
this machine's agents and each machine's. Enter goes into a machine's pane: that machine's
own tmux gets the terminal, and the popup key brings the app back. Each machine needs taw
installed. A machine that drops shows greyed rows with "last seen". Each machine's
notifications arrive on this machine, said once by the app that holds the lease. Actions on a
machine's rows (close, rename, worktrees) run on that machine, and that machine's own hooks
decide. taw --machine NAME verb does the same for scripts.

Each machine's rows sit under its own header, a coloured line whose dot says whether it is
connected; with only this machine listed there are no headers. In the popup, Enter on another
machine's row hands the terminal to the app, which goes there, and Q in that app brings you
back to your tmux. Every attach shows for four seconds which keys bring the list back. A machine
with no tmux running shows a row that starts one. When the other machine does not know your
terminal's type, its tmux runs as xterm-256color, and an attach that fails keeps its words on
screen until you press Enter.

taw machine add NAME DESTINATION writes a machine into the config for you, taw machine remove NAME takes it out, and taw machine check tries each machine once and says what it
found. ctrl-v on an agent's row pastes the image on your clipboard into that agent, on any
machine.

Themes

12 themes. With [theme] auto_switch = true the popup follows your terminal's light or dark
mode, on tmux 3.6 and later. The preview shows a pane in the pane's own colours: what the pane
leaves at your terminal's default colours stays at them, so a see-through terminal shows through
the preview as it does through the pane.

herdr-compatible

Copy your herdr config.toml to ~/.config/tmux-agent-wizard/config.toml: it means what it
meant, and taw config check points at anything that does not apply inside tmux. herdr's key
action names are accepted, agent integrations install into the same directories, and
CLI-driven herdr plugins install with the same trust preview; taw plugin update keeps them
current. Plugin support is in beta: ten real plugins were run before this release, and the
compatibility matrix in docs/COMPAT.md says which work.

The CLI for scripts, and SKILL.md

taw is also a JSON CLI (taw agent start, taw agent prompt --wait, taw agent wait --state blocked, taw pane run), so scripts and agents can drive it. taw skill prints the skill that
teaches an agent how.

Install

Add this to tmux.conf:

set -g @plugin '27medkamal/tmux-agent-wizard'

Press prefix + I: it loads into the tmux you are running, no restart. The first load
downloads the taw binary for your machine (macOS or Linux, Intel or ARM). Then press
prefix + A. From then on taw is on the PATH of every pane you open from tmux. Needs tmux
3.2 or newer. To build it yourself
instead, run ./scripts/install.sh (a Rust toolchain; mise.toml pins the version).

Known limits

• tmux has no live event socket, always-on sidebar or floating toasts, so taw is a popup, a
  status-line token and a JSON CLI. docs/PARITY.md lists each gap with its workaround.
• A machine's agents arrive over your ssh, and the machine's own tmux gets the terminal, so
  herdr's remote attach with your own keybindings is not there (ctrl-v on a row does paste
  the clipboard's image into that agent, over ssh too).
• The sandbox limits accidents, not an agent that is trying to get out: the internet stays
  open, and its recipes for 12 agents are marked untested on the Sandbox page (https://27medkamal.com/tmux-agent-wizard/sandbox/).
• Restore with the conversation needs the agent's hook installed.
• tmux 3.2 or newer, macOS and Linux; no Windows.

taw is independent of herdr and uses its Apache-2.0 detection engine and rules, with credit.
Bug reports are very welcome: the output of taw agent explain <pane> helps most.