claudeers.
// Automation & Workflows

tmux-agent-plane

See and steer every coding agent (Claude Code, Codex) running in your tmux

// Automation & Workflows[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-agents#claude-code#codex#rust#tmux#tmux-plugin#automation◷ GPL-3.0$open-sourceupdated about 2 hours ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up tmux-agent-plane (git-clone project) into my current project.
Found on https://claudeers.com/tmux-agent-plane
Repo: https://github.com/zazencodes/tmux-agent-plane
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/zazencodes/tmux-agent-plane
Category: automation. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/zazencodes/tmux-agent-plane

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseGPL-3.0
Pricingopen-source
LanguageRust

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

tmux-agent-plane

See and steer every coding agent running in your tmux.

Quick start

Open your coding agent (Claude Code, Codex or any other) and ask it:

Install and configure tmux-agent-plane with me: https://github.com/zazencodes/tmux-agent-plane

https://github.com/user-attachments/assets/aa11b86c-dab4-4c0a-b485-0f2c2e8fea59

Start Claude Code, Codex or Antigravity in any tmux pane, the way you already do. tmux-agent-plane finds your agents, tracks whether each is working, waiting on you or done, and shows them in your status bar and agent list. The CLI and agent skill give your agents the same view, so they can check on, message, wait for or start each other.

Claude Code, Codex and Antigravity use native signals. Add Pi, OpenCode or Grok Build with the opt-in integrations under More agents: Pi and OpenCode use publishers built on their official extension APIs; Grok Build uses its official leader mode.

Features

  • Every agent, every session. One daemon tracks agent names, states, tasks and locations across your tmux server.
  • Know what needs you. The status bar counts agents by state. Off-screen completions and blocked prompts send desktop notifications and a five-second sidebar notice. Off-screen completions stay done until you look at them.
  • A sidebar of agents. One live list down the left of every window, grouped by session. Browse to preview an agent, then Enter to focus it. Open or close the sidebar everywhere with your sidebar key.
  • Flip through your agents. Alt + k / j (Option + k / j on macOS) focuses the previous or next agent across sessions, without a prefix. See Direct agent navigation.
  • Search and peek before you jump. prefix + a opens the agent picker with a live preview; prefix + f starts filtering. Search names, projects and tasks with /, or fuzzy-filter names, projects and descriptions with f.
  • How much is left. Press u in the sidebar to expand plan quota while agents stay visible above it. The CLI and your agents can read it too. See Quota.
  • Agents that know about each other. The CLI and skill let agents list, read, message, answer, wait for, focus, close and spawn other agents. One agent can coordinate helpers and review their results.
  • Names you can read. Rename agents with r, name helpers when you spawn them, or enable optional AI naming through o → Configure.
  • See who spawned whom. Press p for the selected agent's parent and children, with their current states.
  • Sessions are projects. Agents started by hand join a session named after their folder. Create project sessions, launch helpers into them, and move running agents between projects. See Project sessions.
  • Workspaces above tmux. Group sessions into workspaces and set one aside the way you detach from tmux: the sidebar, the picker, the agent keys and the status bar show only the workspace you are in, while tmux still shows every session. Press w to switch, or ask an agent to start a workspace or break work off into one. See Workspaces.
  • Stay in tmux when a session closes. Closing its last pane switches you to the most recently active remaining session of its workspace. Closing the final session exits tmux.
  • Background tasks every agent can see. Keep dev servers, watchers and tunnels in a shared list with their ports, output and exit status. Tasks outlive their agents and can be restarted after they stop. See Background tasks.
  • Recently closed conversations. Press h in the sidebar or picker to revive a closed agent with its conversation, folder and project. Works with every integrated kind; Codex needs its conversation ID in the title.
  • Restore after tmux restarts. Review saved agents and layouts, then choose whether to bring back their conversations and background tasks. See Restore.
  • Your agents, unchanged. Spawned agents use your interactive login shell, so aliases and flags apply. A shell stays open when the agent exits.

States

StateMeaning
● workingrunning a turn
◆ blockedwaiting on you: a question, a permission prompt, a dialog
✓ donefinished a turn you have not looked at yet
○ idleready for input, already seen

Requirements

  • tmux 3.3 or newer
  • At least one supported agent CLI: Claude Code, Codex, Antigravity, Pi, OpenCode or Grok Build
  • lsof for Antigravity process/session association and background task ports (included with macOS; install it on Linux when using agy or tasks)
  • Rust and a C compiler, to build it (SQLite is bundled)
  • macOS or Linux. Desktop notifications use osascript on macOS and notify-send on Linux.

Install

Agents installing this for a user: onboard them. Do each step below in order. Before changing any of their files (~/.tmux.conf, ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, skill folders), show the change and ask. Ask which agent CLIs they use, and set up the matching More agents integrations for Pi, OpenCode or Grok Build. Ask which keys they want for moving between agents (step 2), where the status bar should go, and whether they have standing preferences for their agents, such as the model for each kind (step 5). Then reload tmux, run tmux-agent-plane list and show them the sidebar key (default prefix + S) and optional AI naming.

1. The binary.

cargo install --locked tmux-agent-plane

2. The tmux plugin. With TPM, add to ~/.tmux.conf and press prefix + I:

set -g @plugin 'zazencodes/tmux-agent-plane'

Without TPM, clone the repo and add run-shell /path/to/tmux-agent-plane/tmux-agent-plane.tmux to ~/.tmux.conf.

The plugin starts the daemon and binds the sidebar (default prefix + S), the agent picker (prefix + a) and the picker ready to filter (prefix + f, replacing tmux's window finder). To choose a sidebar key, set it before the plugin loads:

set -g @agent-plane-sidebar-key Space   # replaces tmux's next-layout binding

Keys. Without the prefix, Alt + k / j move to the previous / next agent and Alt + h / l go into and out of the sidebar. prefix + o turns Agent Plane keys off and on, closing sidebars and restoring tmux bindings while off. Choose your bindings through the plugin options so the toggle covers them all; see Direct agent navigation.

3. The status bar. Add #{@agent_plane_status} to status-right (or status-left):

set -g status-right "#{@agent_plane_status}%H:%M"

4. The skill. Link it into each agent's skills folder. With TPM the repo is in ~/.tmux/plugins/tmux-agent-plane:

ln -s ~/.tmux/plugins/tmux-agent-plane/skill/tmux-agent-plane ~/.claude/skills/tmux-agent-plane   # Claude Code
ln -s ~/.tmux/plugins/tmux-agent-plane/skill/tmux-agent-plane ~/.agents/skills/tmux-agent-plane   # Codex

5. Your agent preferences (optional). Standing instructions for agents using the skill go in ${XDG_CONFIG_HOME:-$HOME/.config}/tmux-agent-plane/config.toml. The skill tells every agent that loads it to read this file, if it exists, and follow it over the skill's defaults. Only agents read it; the binary's own settings stay in config.json beside it. Without the file, agents use the skill as written.

Use instructions for rules that apply to every agent or [spawn.<kind>].instructions for one kind. Set model and effort in Configure. Optional [spawn.<kind>].args supply other CLI flags. The skill ignores model and effort overrides in those arrays.

instructions = ["Start helpers with --in window in the current project."]

[spawn.codex]
instructions = ["Never use GPT-6-Astra (gpt-6-astra)."]

6. Tell your agents. Agents reach for raw tmux commands out of habit, even with the skill installed. One line in your global ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md fixes that:

- Coding agents in my tmux are indexed by `tmux-agent-plane`. Whenever a task touches another agent (checking on, reading, messaging, waiting for, showing, closing or spawning one), load the `tmux-agent-plane` skill first and use its CLI; never drive agent panes with raw tmux commands.

More agents

Tested with Pi 1.0.2, OpenCode 1.19.3 and Grok Build 1.0.70. Pi/OpenCode must inherit the daemon's XDG_STATE_HOME.

These integrations are independent. Install only the ones you use; absent publisher files or a Grok leader socket leave that kind untracked. The paths below assume a TPM checkout at ~/.tmux/plugins/tmux-agent-plane.

  • Pi: symlink its publisher into Pi's extension directory, then restart Pi:

    mkdir -p "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/extensions"
    ln -s "$HOME/.tmux/plugins/tmux-agent-plane/extensions/pi" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/extensions/tmux-agent-plane"
    
  • OpenCode: symlink the TUI publisher plugin and add "./tmux-agent-plane.js" to the plugin array in ~/.config/opencode/tui.json (or your $XDG_CONFIG_HOME/opencode/tui.json), preserving existing entries. Restart OpenCode. Example configuration.

    mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
    ln -s "$HOME/.tmux/plugins/tmux-agent-plane/extensions/opencode/tmux-agent-plane.js" "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/tmux-agent-plane.js"
    
  • Grok Build (macOS): add use_leader = true to the existing [cli] table in ~/.grok/config.toml (or $GROK_HOME/config.toml), then restart Grok sessions. Example configuration. The daemon uses the same GROK_HOME and GROK_LEADER_SOCKET overrides as Grok; its default socket is ~/.grok/leader.sock.

Usage

Run your agents as usual. Then ask any of them things like:

  • "What agents are running?"
  • "How is codex-164 doing?"
  • "Answer reviewer's question: yes, apply it."
  • "Spawn a Codex agent in a new window to migrate the billing tests, and tell me when it's done."
  • "You're the super agent: split this refactor across three agents, one per package, and review their work."

Direct agent navigation

Press Alt + k / j (Option + k / j on macOS) to focus the previous or next agent directly, without entering the sidebar or pressing the tmux prefix. The keys work with the sidebar open or closed, follow its global order across sessions, and wrap at either end. While typing in an agent, sidebar filters do not limit this navigation. Inside the sidebar, these keys move its selection just like Up/Down and keep the preview attached to it. From a shell, Alt + j starts at the first agent and Alt + k at the last.

The binding targets the exact tmux client that received the key. It refuses a destination session or linked window another client is using. To choose other direct bindings, set these before the plugin loads, then reload the plugin:

set -g @agent-plane-previous-key C-M-k
set -g @agent-plane-next-key C-M-j

These are tmux key names (C is Ctrl, M is Alt). The defaults leave tmux's prefix-then-Alt-arrow bindings available for resizing. Your window manager and terminal must pass the chosen keys through to tmux.

Press Alt + h to move into the sidebar, opening it if it is closed; from inside, it stays put. Press Alt + l to leave it for the selected agent, as Enter does, even halfway through typing a search. Everywhere else Alt + l goes to the pane as usual. To choose other keys:

set -g @agent-plane-sidebar-in-key C-M-h
set -g @agent-plane-sidebar-out-key C-M-l

Inside the sidebar, l and → also leave it for the selected agent. Each binding option accepts one key or several, separated by spaces.

Turning Agent Plane keys off

Press prefix + o to suspend Agent Plane's global shortcuts. Every navigation, sidebar and picker binding returns to what it did before the plugin loaded, so Shift/Alt shortcuts can reach Codex and other programs. For example, if you use prefix + Space for the sidebar, it returns to tmux's next-layout command while keys are off.

Sidebars keep their current open or closed state. While shortcuts are off, you cannot open or close them (including with q), or open the picker. An open sidebar still follows new windows and works normally: use your tmux pane navigation, such as prefix + h/j/k/l when configured, to move in and out, then j/k or arrows to browse inside it. enter-sidebar can focus an open sidebar.

The status bar permanently shows Agent Plane keys off · prefix o to enable until you turn them back on. prefix + o remains available as the enable key. Reenabling restores Agent Plane's bindings and keeps the sidebar's open or closed state.

To start with them off, add set -g @agent-plane-keys off to tmux.conf. To toggle with another key, set @agent-plane-keys-toggle-key before the plugin loads:

set -g @agent-plane-keys-toggle-key e
KeyAction
Sidebar key (default prefix + S)Open the sidebar in every window and move into it; close it everywhere when open
prefix + a / prefix + fOpen the agent picker / open it ready to filter
Alt + k / Alt + jPrevious / next agent across sessions
Alt + h / Alt + lEnter the sidebar / leave for the selected agent
prefix + oTurn Agent Plane keys off or on
j / k, ↓ / ↑, Ctrl-J / Ctrl-KSelect and preview; Ctrl-J/K and arrows also work while editing a filter
gg / HomeFirst agent
GLast agent
{ / }First agent in the previous / next project
wWorkspaces: Enter switches to one, c starts one, r renames one, m moves the selected agent's project into one
/Search names, projects and tasks without hiding rows; Enter keeps the search
n / NNext / previous match in a kept search
fFuzzy-filter names, projects, tasks and blocked details; / freezes matches so keys become commands, f resumes editing
dCycle the state filter: All → Blocked → Done → Working → Idle
mShow only orchestrators; combines with the state and text filters
Enter, l, →Focus the selection; the picker closes and the sidebar stays open. When the daemon is stopped, Enter restarts it
Esc / Ctrl-CCancel an edit, clear a kept search, clear filters, then close the picker
rRename the selected agent; Enter saves, Esc cancels
eRename the selected agent's project (its tmux session); Enter saves, Esc cancels
vMove the selected agent into another project of its workspace without restarting it; j/k choose, Enter moves, Esc cancels
xConfirm killing an agent or stopping a task; Enter or lowercase y accepts, other keys cancel
cStart a new agent in the selected agent's project and folder
pShow or hide the selected agent's graph
tSidebar: show or hide background tasks
RRestart the selected task
zClean up the workspace: close finished agents, exited tasks and unused sessions; Enter or lowercase y accepts
hBrowse recently closed conversations in this workspace; Enter revives the selected one
bReview agents waiting to be restored after tmux restarted
oOpen Configuration
TabPicker: type to the selected agent in the preview; Tab again returns to the menu
uSidebar: expand quota; u or Esc collapses it to a summary
?Show shortcuts, including your configured tmux bindings; reopen for the next page on a short terminal
qClose the sidebar everywhere, or close the picker

While editing a search, filter or name, letters are text. Ctrl-W deletes a word and Ctrl-U clears it. The footer shows the controls for the current action.

c offers Claude Code, Codex, Pi, OpenCode and Grok Build. Antigravity needs a first task to start, so use spawn agy "<task>" for it. Pi, OpenCode and Grok Build always appear in the picker, but are tracked only once their optional integrations are set up. Like Enter, c refuses a session another client is using.

An agent in a linked window has one index row, displayed under the first session by name. It counts as visible when its pane is visible through any link.

While the sidebar is open, every window has one, including windows and sessions you create later; each keeps its own selection. A window's sidebar closes with the window: when its other panes are gone, the layout hook closes it immediately. The sidebar starts on the first blocked agent, or else the first done one; the picker opens on the agent you are viewing, or the top row. The agent you are looking at is shown in bold in the sidebar.

Moving with arrows or j/k previews the selected agent's window/session and keeps keyboard input in its sidebar. The sidebar pane itself moves into the previewed window, so selection, filter, search and order stay exactly as they were, and the sidebar it swapped with takes its place in the window you left, which gets back the pane it had active before the sidebar: come back with plain tmux and you land on that agent, with no key or focus event sent to it while you were away. Preview keeps the sidebar active, so a done agent remains unseen; Enter focuses it and makes it seen, and the sidebar moves with you the same way. Navigation requires a unique client in the input sidebar and refuses a destination session/window used by another client.

Clicking an agent's name or description previews it the same way. With tmux's mouse option on, tmux also moves the keyboard into the sidebar when you click it, and clicking the agent's pane then focuses it; with mouse off, clicks reach the sidebar while it has the keyboard. Clicks do nothing while you type a search, filter or name, or answer a prompt.

Session headings stay in place, each in the same colour its session has in the picker. Rows never move: badges and ages update in place, new agents append in their group, and removed agents disappear. The daemon keeps one order for every sidebar. Sessions are listed by name. The highlight follows the agent you are in; from a sidebar or a plain shell it stays on the last agent you used, until you move it.

An idle sidebar runs no tmux commands: it reads the daemon's index twice a second and writes to its pane only when something on screen changed. A window with an agent active is right the moment you arrive, however quickly you move, because its active pane cannot change while it is hidden. Everything else comes from the index and can be a second or so old: arriving in a window whose keyboard was left in its sidebar or a plain shell, moving between the sidebar and an agent within a window, and which agent counts as last used.

The state filter, text filter and search stay visible above the list. They combine, and a search only visits rows the filters keep. A state filter stays selected if its last match changes state or exits, until you press d again. Typing a search moves the selection but pauses previews, so nothing changes under you until Enter; from there n and N preview each match while the keyboard stays in the sidebar, and Enter goes to the agent. The text filter works as it does in the picker: the best match comes first, under its session heading, so a heading can repeat when matches from different sessions interleave. It updates as you type and pauses previews, including arrow navigation, so editing stays in the current sidebar. Enter jumps to the selected match and ends the filter; / freezes the filter and previews its selection. Esc while editing restores the previous text and selection. While editing either one, letters such as f, r and q are text.

x closes the agent's pane using the same operation as tmux-agent-plane kill. It does not issue kill-session. The confirmation takes priority over notices and event footers, with separate name/state lines in narrow sidebars. It is pinned to the target's native identity and state; an exited, changed or renamed agent requires a new confirmation. The selection moves to the next visible agent (or the previous one at the end); a sidebar goes there first, then kills, so your keys stay in it when the agent's window closes. Killing a final pane may naturally remove its window; if that would also end a session, the prompt names it. Ending the session you would still be in is refused: the picker's client, or a sidebar with no other row to move to.

tmux fuzzy picker

Press prefix + a from any pane. It opens over a dimmed copy of your screen, on the list, grouped by session: each row names its session in a colour of its own. The agent you are looking at is selected, including from a sidebar beside it, so you browse from where you are; with no agent in view, the top row is. j/k, Up/Down or Ctrl-J/Ctrl-K browse, and the screen preview updates inside the popup. Periodic state updates preserve the selected pane. Enter focuses that exact pane in the client that opened the picker, across sessions; q, Esc or Ctrl-C closes and leaves your original pane and session selected. Browsing never switches sessions.

Press / to search as in the sidebar: the selection and preview move to the next row whose name or task contains your text, or the first visible agent in a project whose name matches, and after Enter, n and N go through the matches. Press f to filter, or open the picker with prefix + f to start there. The filter box appears and letters become text: a case-insensitive fuzzy query across agent names, projects, task titles and blocked details, where each word can match any of them. Stronger matches appear first; Ctrl-J/Ctrl-K or Up/Down browse them. Backspace edits, Ctrl-W deletes a word and Ctrl-U clears. Press / to freeze the filter: its matches and selection stay, and your keys are commands again, so c or x act on the selected match. f resumes editing. Enter opens the selected match right away; Esc cancels the edit. A / cannot be part of a filter. On the list, Esc or Ctrl-C clears a kept search, then the text and state filters, then closes.

The sidebar's actions work on the selected agent, with the same prompts and checks: c new agent, x kill, r rename, v move, d state filter, p graph, o configure and ? shortcuts. c closes the picker and takes you to the new agent.

Press Tab to type to the selected agent without leaving the picker. The preview gets a coloured border and follows the agent live, with its cursor, and every key goes to that agent: Enter, Esc, Ctrl-C and letters included, so you can give it a task or answer a prompt. Tab again returns to the menu or search you came from. The agent stays pinned: if it exits or leaves the list, the picker returns to the menu and sends nothing elsewhere. Tab itself never reaches the agent, and Shift-Tab does. The preview shows the agent's screen at its own size, so a pane wider than the popup is cut off on the right. Ctrl-J sends a newline. Each newline in a multi-line paste arrives as Enter, so it submits; to paste several lines, press Enter from the menu to jump to the agent's pane.

The popup inherits the terminal background and uses its palette for the selected row, even when a tmux theme configures other popup colors. The plugin supplies the originating client to tmux-agent-plane ui --client <client-name>.

Neovim Telescope picker

In Telescope normal mode, p toggles the selected project filter and x asks to remove the selected conversation. Open a specific project directly with :Telescope tmux_agent_plane history project=PROJECT. Press h to switch between live agents and recently closed conversations in your workspace. Open history directly with :Telescope tmux_agent_plane history. Search by conversation title, agent name, project or agent kind. Enter revives the selected conversation and focuses its new pane.

With Neovim 0.10+ and Telescope, add this local plugin to your lazy.nvim spec (adjust the checkout path):

{
  dir = vim.fn.expand("~/.tmux/plugins/tmux-agent-plane/extensions/nvim"),
  name = "tmux-agent-plane.nvim",
  dependencies = { "nvim-telescope/telescope.nvim" },
}

After your Telescope setup, load the extension and bind Space f a:

require("telescope").load_extension("tmux_agent_plane")
vim.keymap.set("n", "<leader>fa", function()
  require("telescope").extensions.tmux_agent_plane.agents()
end, { desc = "Find agent sessions" })

Run Neovim inside tmux with tmux-agent-plane on PATH and its daemon running. :Telescope tmux_agent_plane agents opens the same picker. Like the sidebar, it lists the agents of the workspace Neovim's tmux session is in and names it in its title: it asks tmux-agent-plane workspace list --json which workspace is here, then reads that workspace's agents from tmux-agent-plane list --json, with their existing names and task descriptions (blocked detail when present). Type a case-insensitive fuzzy search across name, project, title and blocked detail, including queries spanning those fields; use Up/Down in insert or normal mode to browse, then Enter to run tmux-agent-plane focus <pane-id> for that exact selection. Browsing does not change agent focus. An empty index opens an empty picker; command failures, including a stale index, appear as error notifications.

Notifications

When an agent finishes or blocks off screen, every open sidebar shows the latest transition on its bottom line for five seconds: ✓ grok-support done in green or ◆ grok-support blocked in red. Sidebars in other windows and sessions receive the same event. Rename errors and active rename controls take priority; normal key hints return when the notice expires. A notice never opens a closed sidebar, changes focus or intercepts pane input. Expired notices are discarded, and restarting the daemon clears the previous notice.

Pi and OpenCode completion counters also report a new finished turn when it completes between polls while the agent still shows done. Each new completion follows the same footer and desktop policy.

Desktop notifications keep the task or blocked detail and work with the sidebar closed. Daemon faults and recoveries open in their own window a little below the top of the terminal, once you pause typing so it does not swallow keystrokes. A notice stays until you press a key or for 10 seconds, and it takes keyboard input while it is open.

Quota

Press u to expand quota upward from the bottom while agents remain visible above it. Press u again or Esc to collapse to the summary. The summary nests each plan’s pacing windows beneath its name, including Antigravity’s separate budgets, using the same heading and rule as tasks. Configure whether sidebars start with it shown through o → Quota panel.

── quota ───────────────────────────
● claude
  5h      ━━━━━━━━━━━━━┃  97% 4h38m
  week    ━━━━━━━━━━┃───  72% 4d21h
◐ codex
  5h      ━━━━━━━━──────  60% 2h0m
  week    ━━━━━━━━━━━╸──  83% 3d0h
● agy
  gemini
  5h      ━━━━━━━━━┃────  75% 2h0m
  claude/gpt
  5h      ━╸┃───────────  10% 1h0m

To hide particular budgets in your own sidebar, set sidebar.hidden_quota_groups in ~/.config/tmux-agent-plane/config.json and reopen the sidebar. For example, "hidden_quota_groups": ["agy:claude/gpt"] hides Antigravity's Claude/GPT budget from both compact and expanded quota. The default is an empty list, showing every budget. CLI quota output retains all groups.

Antigravity's budget groups come from its /quota response. Models that share a budget, such as Neon and Hydrogen when reported under Gemini Models, share one tracker. Separately reported groups, including Neon, Carbon and Argon, keep their own windows; model names do not create additional budgets.

Expanded details show each plan's windows, pace and reset times. Use r to refresh, j/k or arrows to scroll, and Enter to allow Keychain access when Claude asks. Expired logins are omitted.

Each window has one bar, with identical label, bar, percentage and reset columns across every provider and budget. Compact and expanded quota use the same rows; expanded quota adds plan names, model limits and pacing verdicts. When Gemini is Antigravity’s only visible budget, its windows sit directly beneath agy. A fresh unused window starts with its marker at 100% even when the provider has not started a reset clock; its countdown stays blank. Percentages are what is left: green from 50%, yellow from 20%, red below. ┃ marks where the bar would be if you used the window evenly up to its reset: fill short of the marker means you are using it faster than the clock. The verdict on the right is on pace ✓ when every window lasts to its reset, empty in 7h21m when, at the rate so far this window, one runs out first, ✗ exhausted now, or runway unknown when a window's cycle is not known. Antigravity shows its Gemini and Claude/GPT groups separately, because each is its own budget.

Quota refreshes while shown once the reading is five minutes old, sharing a recent reading from other sidebars. In details, r reads again; the last reading stays visible with refreshing… meanwhile. The daemon does every read, so the sidebar stays idle and codex or agy never appear as agents. When a read fails for a moment (timeout, network, rate limit, server error), the card keeps the windows that have not reset yet, marked ◐ stale with the reason; a sign-out drops them. A number is never shown past its reset. A failed card says what to do, such as run grok to renew it. Provider failures are logged to daemon.log once each and never count as daemon faults.

Each provider is read one way, with the login its own CLI already keeps. Tokens go only to that provider's own endpoint, and are never written, cached or logged; refresh tokens are never read, and nothing is ever written to a credential store. No read spends any usage.

ProviderHow
ClaudeGET https://api.anthropic.com/api/oauth/usage with Claude Code's OAuth token. macOS: the Claude Code-credentials Keychain item (suffixed with a hash of CLAUDE_CONFIG_DIR when that is set); Linux: ${CLAUDE_CONFIG_DIR:-~/.claude}/.credentials.json. A rejected token means its login expired: open Claude Code, which renews it.
CodexIts own codex app-server, found on the daemon's PATH, asked only for the account and its rate limits. Codex renews its own login.
Antigravityagy -p /quota --output-format json, with open and xdg-open stubbed out so it can never open a browser.
Grok Buildgrok.com's credits for Grok Build, with the session login in ${GROK_HOME:-~/.grok}/auth.json. API keys are never used.

Claude on macOS asks once. Reading the Keychain item can make macOS ask for permission, so nothing reads it until you allow it: the Claude card says needs Keychain access · enter allows. Press u from the quota summary, then Enter in the details; macOS may show its dialog, where Always Allow keeps later reads silent. Once a read succeeds, the daemon remembers your consent in a marker file, quota-keychain-granted in its state directory, which holds no secret. Delete it to withdraw consent. If a later read is denied, the marker is removed and the card asks again. Until then only the item's presence is checked, which never shows a dialog. The quota command reports the same remedy.

The snapshot lives in ${XDG_STATE_HOME:-~/.local/state}/tmux-agent-plane/quota.json, written only by the daemon. HTTPS honours HTTPS_PROXY and NO_PROXY, follows no redirects and gives up after 15 seconds.

Project sessions

Each project has zero or one orchestrator. Its agent appears first under the project heading with an orch badge, alongside its normal state. m in the sidebar or picker shows only orchestrators in the current workspace; combine it with d for blocked or completed orchestrators, and with text filtering. Escape or Ctrl+C clears filters. Background tasks are hidden while this filter is active.

The background naming agent can infer leadership when it names an agent, using the task, parent links and the project's other agents. Unclear cases stay ordinary workers. Naming is still optional; disabling it leaves role reporting available through the CLI and skill. A naming command must return a JSON object such as {"name":"coordinate-api","orchestrator":true} in its configured output format.

The shipped skill tells agents to report promotions and demotions from conversation context: “you're in charge”, “you're the orchestrator”, or an assignment to delegate and coordinate project work. tmux-agent-plane orchestrator set <agent> transfers the project's role; orchestrator clear <agent> reports that agent stepping down. A late naming result cannot undo an intervening report, and clearing a previous holder cannot demote its successor. Roles survive agent/project renaming and daemon restarts, and end with their agent process. No replacement is elected on exit. The text CLI marks [orch]; list --json exposes orchestrator.

Moving an orchestrator into a vacant project carries its role and leaves its old project without one. A destination already holding an orchestrator requires an explicit leadership decision before the move.

A tmux session is a project: its orchestrator and helpers live in the same session, and the sidebar groups them under that session's name. The CLI and shipped skill let an orchestrator organize existing work and place new work directly in a named project:

tmux-agent-plane sessions list --json
tmux-agent-plane list --json
tmux-agent-plane sessions create --cwd /path/to/api   # named after its folder: api
tmux-agent-plane sessions rename api api-v2
tmux-agent-plane move api-review --session api
tmux-agent-plane spawn codex "Review the API changes" --in window --session api --cwd /path/to/api --name api-tests
tmux-agent-plane spawn claude "Plan the website" --in session --session website --cwd /path/to/website --name website-lead

sessions list includes every session, even one with only shells: exact name and ID, workspace, attached-client count, window IDs, session group and agent names. Linked agents appear in each containing session. Existing destinations use exact names or IDs; new session names reject dots, colons, control characters and surrounding whitespace so tmux cannot silently rewrite them. sessions create opens a detached interactive shell. Without a name, a project is named after its folder, or with -2, -3… when another session (perhaps in another workspace) already has that name, since tmux session names are unique. Rename a project with sessions rename, or e in the sidebar or picker; its agents, windows, clients and workspace stay as they are. spawn --in session --session NAME creates the project with its first agent; --name names that agent separately. spawn --in window --session NAME uses an existing project's configured shell. An unknown destination fails before launching anything.

move uses a native detached pane move: the process keeps running, with the same pane ID, native identity, name, parent and completion history. No input is sent to the agent. Only the chosen pane moves, leaving other agents and shells in a mixed source window. The destination's current window and clients stay in place. The command prints the new location; the daemon publishes it on its next scan.

A source window or detached session may disappear when it has no remaining content; the normal sidebar hook closes a lone sidebar. Moves that would end an attached source session are refused. Linked source windows and grouped source/destination sessions are also refused because those share windows across projects. The CLI checks the live agent identity and rechecks topology in tmux's command queue before moving. Existing shell-only windows remain for the user. The skill's project organization workflow covers inspecting work, creating sessions, moving each team member and verifying the result.

An agent you start by hand joins a project by itself. Within a second of appearing it moves to its folder's project in its own workspace, which is created if needed, and any client viewing it moves too, so you keep working in it without interruption. Its folder's project is the session named after the folder, or the first of <folder>-2, <folder>-3… in its workspace when the folder's name belongs to another workspace. The folder is the one the agent runs in, so a subfolder or worktree gets its own project; . and : in a folder name become -. This happens once per pane, so a later move sticks. Agents already running when the daemon starts, agents from spawn or the sidebar's c, and agents sharing a window with other panes stay put, as do moves into a session another client is using and any move involving grouped sessions or linked windows.

Workspaces

A workspace is a group of tmux sessions, one level above tmux. Every session belongs to exactly one. While you only have one, called main, nothing changes but the sidebar and picker headings, which name it. Once you start a second, everything Agent Plane shows is scoped to the workspace you are in: the sidebar lists its agents and tasks, the picker, the Telescope picker and Alt + k / j go through its agents only, sidebar notices come from it, and each session's status bar counts its own workspace's agents after the workspace's name. tmux itself is untouched: prefix + s, tmux ls, switching and detaching see every session, as always. Agents in other workspaces keep running; desktop notifications still reach you from all of them.

Press w in the sidebar or the picker to see your workspaces, marked ◆ or ✓ when an agent there is blocked or done. Enter takes you to the session you used last in the highlighted workspace. c starts a new workspace: type its name, and you land in its first project, a fresh session in the folder the list runs in, named after that folder. r renames the highlighted workspace. m moves the project (the whole session) of the agent selected in the list into the highlighted workspace. x closes the highlighted workspace and asks first: Enter moves its sessions intact into main, agents still running; n asks again, and Enter there ends all of its sessions and their agents. Esc or Ctrl+C cancels either question. Its background tasks keep running and move to main either way. main cannot be renamed or closed, and no other workspace can take its name. Esc, Ctrl+C or w closes the menu.

Your agents can manage workspaces too, when you ask them to:

tmux-agent-plane workspace list [--json]                 # each workspace's sessions and agents; * is the one you are in
tmux-agent-plane workspace switch research               # show its most recently used session in your client
tmux-agent-plane workspace move api web --to client-x    # move whole sessions; a new name starts a workspace
tmux-agent-plane workspace rename client-x acme
tmux-agent-plane workspace close acme                    # move its sessions to main
tmux-agent-plane workspace close acme --terminate-sessions # end its sessions and agents
tmux-agent-plane sessions create notes --workspace research --cwd ~/notes
tmux-agent-plane spawn claude "Plan the launch" --in session --session launch --workspace research --name launch-lead

New work joins the workspace it starts in. spawn into a pane or window stays in the caller's session, and a session created by sessions create or spawn --in session joins the caller's workspace unless --workspace names another. A session you make by hand (tmux new, a script) joins the workspace you are in, that of the tmux client you used last. An agent moves to another workspace only by moving its session (workspace move) or by moving it into a session there (move <agent> --session <session>); automatic folder projects never cross workspaces, so an agent whose folder's session lives in another workspace gets a numbered project of its own. When a session closes, its clients stay in its workspace while it has sessions left. list shows every agent with its workspace, and restore brings sessions back into theirs. The workspace is a tmux option on each session, @agent-plane-workspace, so it lasts as long as the session.

Background tasks

A task is a long-running command an agent starts through the plane: a dev server, a file watcher, a tunnel, a queue worker. Every agent sees the same list, so an agent that needs the dev server reuses the running one instead of starting another on a different port.

tmux-agent-plane task start web --cwd ~/pro/site -- npm run dev
tmux-agent-plane task list
tmux-agent-plane task read web --lines 100
tmux-agent-plane task restart web
tmux-agent-plane task stop web

In the sidebar, t lists the tasks started from its workspace below the agents, where Enter opens one, x asks to stop it and R restarts it; see Sidebar and agent list. Each task runs in its own window, named after it, in a detached session called agent-plane-tasks that is created on first use. Its command runs the way spawn runs an agent, through an interactive login shell in tmux's default-shell, so your PATH and aliases apply. The first word after -- is the program, one plain word such as npm; every later word reaches it verbatim. For pipes or other shell syntax, run sh -c '...'.

Names are one word of letters, digits, -, _ and ., unique across tmux. task start with a name that is already running the same command in the same folder reuses it and prints (already running); if that task has exited, it runs it again. The same name with a different command or folder fails and shows what the existing task runs, where and who started it. task start returns at once and prints <name> <pane> <state>.

A task keeps running when the agent that started it exits; only task stop (or x in the sidebar) ends it, and it then leaves the list. When a task's command ends, its window stays with its output and the list shows exited <code>; a command ended by a signal shows 128 plus the signal number, as a shell reports it. task restart runs the command again in the same window, clearing the earlier output.

task list shows every task's state, the TCP ports its processes listen on, folder, the agent that started it, how long ago it started, and its command, with its workspace once there are several; --json gives every field. A task belongs to the workspace it was started from. The daemon looks up ports with lsof at most every five seconds, only while tasks run. A task is never an agent, even when its command is an agent CLI, and projects and automatic placement leave the tasks session alone. The definition lives on the task's tmux pane, so tasks and their state survive a daemon restart.

Recently closed conversations

Press h in the sidebar or picker for your workspace's recently closed agent conversations, newest first. Browse with j/k or arrows, then Enter revives the selected conversation and takes you there; Esc or Ctrl+C clears the search, then the project filter, then returns to the agent list. Each row shows the agent, kind, project, task title and time since closing. An unavailable conversation shows why it cannot be revived.

History colors match the sidebar for active projects. Closed projects get a shade based on their recorded project name. In sidebar and popup history, / searches titles, agent names, projects and agent kinds. Press p to filter to the selected project and again to show all projects. Press x then y to remove the selected entry from Agent Plane history. Its native transcript stays on disk. From the CLI, use tmux-agent-plane recent --project PROJECT --search WORDS (either flag works alone) and tmux-agent-plane forget ID.

The daemon remembers conversations it has tracked, including agents closed outside the plane, and keeps the latest 100 closed conversations across daemon and tmux restarts. History starts when this version is installed. Reviving opens a new window in the original project and folder, recreating the project in its original workspace if needed. An existing project in another workspace is refused. The agent keeps its name if available; leadership and old family links stay with the original processes. A conversation already running stays out of the list.

tmux-agent-plane recent             # all workspaces
tmux-agent-plane recent --json
tmux-agent-plane revive <id>        # id from recent

All six kinds use their native resume command. Pi/OpenCode need their publishers and Grok Build needs leader mode as usual. For Codex, include its conversation ID in the native terminal title, ahead of the task and project so it survives title length limits. Add this to your Codex config ($CODEX_HOME/config.toml, normally ~/.codex/config.toml):

[tui]
terminal_title = ["activity", "session-id", "thread-name", "project-name"]

New Codex processes load this setting. For one already open, use Codex's /terminal-title setup to choose these items, with Session ID ahead of Thread Name and Project Name. Until its title publishes an ID, that conversation cannot be revived. Codex shortens the title's UUID; the plane resolves that prefix uniquely against Codex's local thread database, and refuses an ambiguous match. Task titles in the plane leave the ID out. This identifies the conversation being viewed; Codex tool-shell caller identity remains unavailable with a shared server.

Revive resumes saved history; it cannot recover deleted conversations, missing folders, unsent drafts or an interrupted in-memory turn. History stores metadata, without copying conversation transcripts.

Restore

…view the full README on GitHub.

// faq

What is tmux-agent-plane?

See and steer every coding agent (Claude Code, Codex) running in your tmux. It is open-source on GitHub.

Is tmux-agent-plane free to use?

tmux-agent-plane is open-source under the GPL-3.0 license, so it is free to use.

What category does tmux-agent-plane belong to?

tmux-agent-plane is listed under automation in the Claudeers registry of Claude-compatible tools.

0 views
★ 10 stars
unclaimed
updated about 2 hours ago

// embed badge

tmux-agent-plane on Claudeers
[![Claudeers](https://claudeers.com/api/badge/tmux-agent-plane.svg)](https://claudeers.com/tmux-agent-plane)

// retro hit counter

tmux-agent-plane hit counter
[![Hits](https://claudeers.com/api/counter/tmux-agent-plane.svg)](https://claudeers.com/tmux-agent-plane)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 119,754◷ MIT[ claude ]
→ see how tmux-agent-plane connects across the ecosystem