tmux-agent-wizard

Every agent. One key. Your tmux.

See which coding agent needs you and get there in one key, inside the tmux you already run.

Try it in your browser Install

From the maker of tmux-session-wizard. Compare with herdr · Questions · GitHub tmux 3.2 or newer · macOS and Linux · MIT licence

Who needs you, in one key

prefix + A shows every session and agent in one tree. Tab finds the one that needs you, Enter goes there.

Told wherever you are

A toast in tmux, a desktop notification, or a message on your phone. prefix + O jumps to the agent from anywhere.

Back after a reboot

Sessions, windows, layouts and folders, and 18 agents back in the same conversation.

Your tmux, kept

One plugin line, no restart. Your tmux.conf, keys and plugins stay, and agents already running show up at once.

Install

Needs tmux 3.2 or newer, on macOS or Linux, and TPM.

1. Add the plugin to ~/.tmux.conf:

   ~/.tmux.conf

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

2. Press prefix + I. TPM installs the plugin, and its first load downloads the taw binary for your machine from the project's GitHub releases, checked against the release's SHA-256 checksum. tmux says tmux-agent-wizard: taw is ready, press prefix + A when it is done.

3. Press prefix + A. The agents you already have running are in the list.

4. Optional, for restore: once for each agent you use, let it tell taw its session, so a restore brings it back into the same conversation:

   taw integration install claude    # and codex, opencode, cursor, ...
   

5. Optional, for a shell outside tmux (inside tmux, taw is on your PATH already):

   mkdir -p ~/.local/bin && ln -s ~/.local/state/tmux-agent-wizard/bin/taw ~/.local/bin/taw
   

Without TPM, from source, or with the download or the per-pane watchers off: see Install.

Three keys

1prefix + A

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.

2Tab

Moves the cursor to who to deal with next: the next agent that needs you (blocked, or finished and not looked at yet), else the next agent of any kind.

3Enter

Goes there.

1-9 jump to a session, a-e to its rows, / filters the whole tree with fzf syntax, matching only what its rows show, and the preview shows the pane under the cursor. The bottom line names the keys you need most; ? lists every key on one screen. If you know tmux, you already know taw. All the keys

tmux · prefix + A

Told when an agent needs you, wherever you are

When an agent in a pane you are not looking at blocks or finishes:

Where	What you see	To turn it on
In tmux	a toast on the status line	nothing, it is the default
On your desktop	a macOS or Linux notification	[ui.toast] delivery = "system"
In your terminal, over ssh too	your terminal's own notification	[ui.toast] delivery = "terminal"
On your status line, all the time	⏸1 ⏵3 ✓2: blocked, working, done	set -ag status-right ' #{@agent_wizard_status}'
On your phone	a message through ntfy, Pushover or any command	a one-line [hooks] notification

prefix + O takes you there

From anywhere in tmux, prefix + O goes to the agent that needs you, and the next press to the next one. With nothing waiting it goes to the next agent of any kind.

Notifications

On your phone, with nothing new to install

It is all tmux, so your agents are wherever your tmux is: ssh in from any terminal app on your phone, tmux attach, and prefix + A lists every agent; Tab and Enter take you to the one that needs you. With the one-line hook above, your phone also tells you when one does.

Back after a reboot, in the same conversation

taw saves on its own, a few seconds after each change, and keeps a copy of the layout at most every 15 minutes. After a reboot or a tmux crash, taw session restore brings back your sessions, windows, layouts and folders, and 18 agents (Claude Code, Codex and OpenCode among them) reopen in their own conversations once each agent's hook is installed (one command per agent, such as taw integration install claude). A Claude pane even comes back with the flags it was started with, --model among them.

Next to tmux-resurrect and tmux-continuum: taw restores when you run the command, not by itself when tmux starts, and it does not start other programs such as vim again, which resurrect can. So you do not need resurrect unless you want that, and if you keep it, one line runs taw's restore after resurrect's own. Save and restore has the side by side.

One plugin for agents, sessions and restore

herdr's agent features, in your tmux

Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI, Cursor, Amp, Cline, Droid, Kilo, Kimi, Kiro, Qwen, Pi, Hermes, Grok, Devin, Antigravity, Maki, Muse, Qoder and Letta, read with herdr's own detection engine and the same 22 manifests, ported with herdr's tests and updated from herdr.dev. "Done" means finished and you have not looked yet, so a row you already read never nags. On top sit seven rules of taw's own, six for Claude Code and one for Codex, so a Claude 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. herdr is its own terminal workspace, and a good one outside tmux; taw is for the people who stay in tmux. Agents

working blocked done idle unknown

Sessions, worktrees and machines, in one popup

• A project picker. n, then type or pick a directory (zoxide and your project folders): switch or create. tmux-session-wizard's session picking, folded in, and taw open <path> from a shell.
• Worktrees as sessions. w makes a git worktree with its own tmux session; a closed one stays in the tree and Enter reopens it.
• Your other machines. taw machine add build build.local, then taw app lists this machine's agents and each machine's in one list, over your ssh. Enter goes into that machine's own tmux; ctrl-v pastes the image on your clipboard into the agent under the cursor, on any machine.
• A sandbox on request. 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. It limits accidents such as an rm -rf ~. It is in beta.
• Hooks. Run a command of yours on any event: an agent going blocked, a session opening, a worktree closing.

Sessions and worktrees · Remote machines · Sandbox · Hooks

The project picker

A closed worktree, reopened

Agents can drive agents

Every verb is a JSON CLI, and taw skill prints a skill any agent can read. CLI

taw agent start                  # start an agent in a new pane
taw agent prompt --wait          # send it a prompt and wait for its answer
taw agent wait --state blocked   # block until it needs a human
taw pane run                     # run a command in a pane
taw pane wait-output             # wait for the output it produces

herdr-compatible

Copy your herdr config.toml to ~/.config/tmux-agent-wizard/config.toml; it means what it meant, taw config check points at anything that does not apply inside tmux, and herdr's key action names are accepted. Agent integrations install into the same directories. CLI-driven herdr plugins install with the same trust preview, and taw plugin update keeps them current; plugin support is in beta. Coming from herdr

taw config check   # points at anything that does not apply inside tmux

How it compares

✅ has it, ⚠️ in part, ❌ does not. Where taw is ahead first, then what both do.

	taw	herdr	tmux and its plugins
Runs in the tmux you already run	✅ a TPM plugin, no restart; running agents show up at once	❌ its own terminal workspace and config	✅
Project picker (your project folders, open or not)	✅ n in the popup, or taw open	❌ a new workspace starts in the folder new_cwd names	✅ with tmux-session-wizard (zoxide)
An agent in a container	✅ taw sandbox, through a profile you can read	❌ no sandbox of its own	❌ by hand
An agent you start in Docker or Podman	✅ recognised, with nothing set	⚠️ only with HERDR_AGENT set	❌
A command of yours on any event	✅ one line under [hooks]	⚠️ through a plugin or its socket	⚠️ tmux's own hooks, for tmux's events
Notifications on your phone	✅ a one-line hook	⚠️ through a plugin	❌
Knows each agent's state	✅ 22 agents, herdr's rules plus seven of taw's own	✅ 22 agents	❌
Tells "done" from "you already looked"	✅	✅	❌
Takes you to what needs you	✅ Tab in the popup, prefix + O anywhere	✅ its sidebar and notification key	❌
Notifications	✅ in tmux, your terminal (over ssh too), macOS or Linux	✅ in the app, your terminal, the OS's own	⚠️ the bell, activity and silence alerts
Agents back in their conversations after a reboot	✅ 18 agents, once each one's hook is installed	✅ the same 18	❌ tmux-resurrect: layouts, folders, some programs
Worktrees	✅ each with its own session	✅	❌ by hand
Agents on other machines	✅ one list, over your ssh; Enter goes into that machine's tmux	✅ connects to herdr on other machines	⚠️ ssh, then tmux
Scripting	✅ JSON CLI and an agent skill	✅ socket API, CLI and an agent skill	⚠️ send-keys, capture-pane
Agents always accessible	✅ in a popup on a key, plus a count on the status line	✅ in a sidebar	❌
Updates live as agents change	✅ the popup, the status line and the toasts, as it happens	✅ the sidebar, and events on its socket	❌
Supports herdr's plugins	✅ in beta: herdr's CLI-driven plugins, beside your TPM ones	✅ plugins and a marketplace	❌

herdr as of v0.9.4, October 2026.

taw is independent of herdr and uses herdr's Apache-2.0 detection engine and rules, with credit. The parity ledger goes through herdr feature by feature, and Beyond herdr lists what taw does differently.

Footprint

22agents read with herdr's own rules

18agents restored in their own conversations

9 MBabout, for one pane's watcher

2.7%of one core of an M1 Pro for eleven panes with ten agents among them

An end-to-end suite drives real tmux servers. State lives in tmux's own options, kept current by one small watcher per pane (about 9 MB each; eleven panes with ten agents among them used 2.7% of one core of an M1 Pro, and scripts/demo/measure.sh measures your own). taw writes nothing into your tmux.conf or your status line: it adds its two keys and its tmux hooks when it loads, beside yours. The only thing it asks the network for on its own is newer detection rules from herdr.dev, at most once every 6 hours, and one setting turns that off.

One line in ~/.tmux.conf. The tmux you are sitting in has it.

Install Try it in your browser Read the guide

taw is an independent project, by the maker of tmux-session-wizard. MIT licence. The detection manifests, the manifest engine port, the integration hook scripts and the plugin manifest format are derived from herdr (Apache License 2.0).