agent-managerSessions run inside tmux (am_* namespace), so they survive the manager quitting. Inside a session, Ctrl+Q detaches back to the manager when your terminal and tmux leave it available; Ctrl+\ is an alternate under the same rule. Ctrl+R opens the session's diff review and F3 opens its directory in your editor. In a full-screen attach, the session footer also shows an inner tmux prefix followed by d when configured. When nested inside another tmux, send the inner prefix shown in the footer, then press d. If both tmux servers use the same prefix, invoke the outer tmux's send-prefix binding; if the outer tmux otherwise captures the inner prefix, configure it to forward that key. agent-manager --version prints the version.
Agent sessions live on a private tmux server named agentmgr, so they never mix with the tmux you run yourself and a kill-server on your own socket leaves them alone. To reach one from a plain shell, name that server: tmux -L agentmgr ls, then tmux -L agentmgr attach -t am_<id>.
The first launch of a fresh install opens a setup over the whole terminal. It opens on a welcome, then four steps set what most people change first: which agent CLIs the session pickers offer (the ones found on your PATH start checked), the sessions layout, the list density, and the theme, with "follow the OS" beside the palettes. When the terminal has room, a window beside each step draws the list the way the choice on screen would, and the theme step repaints the whole screen as you move. A short tour follows, each card acting itself out in that window: starting an agent from the quick prompt, answering a session, focusing it with → and coming back with ← (the enter and detach keys when the ←→ pair is off), commenting in Review and sending the comments to the agent while you read on, one agent leading the rest by opening agents in groups and coordinating them through the manager's MCP tools, and where Settings and Messages live. The cards name the keys as they are bound now, and under the main flow they name the other ways in, such as the n form and g for a new group.
The last step brings in the conversations your CLIs saved before you installed the manager. Check the installed CLIs to import from, pick how far back to reach (7, 14 or 30 days) and the agent CLI that does the work, then ↵ closes the setup and starts that agent as import-past-chats. It reads each CLI's own storage, skips any conversation already in the list, and adds each one with create_session and resume, named after what it was about. The setup ends by starting that import, so ↵ waits until a CLI is checked, and leaving without one takes esc. space checks a CLI and ← → step the two values.
↵ confirms a step and saves it, the same as its Settings row would save it, and ⌫ goes back. esc on any step asks before the setup closes. y or ↵ leaves and keeps what the confirmed steps saved, and n or esc stays. The setup runs once, and the first-run setup row in Settings (s) opens it again on your current choices.
Tell your agent what you want to review in Agent Manager. Your agent will set up the repository or worktree, target and scope for you to view in the review panel. You can also tell your agent to manage sessions and terminals in Agent Manager; it can set them up and control them for you.
| Key | Action |
|---|---|
n |
New session (name, tool, the model, effort and profile the tool offers, environment profile, directory, worktree toggle and the base it starts from, optional saved prompts and starting prompt, group picker) |
T |
New terminal tab: a shell under the selected agent, or in the selected group |
o |
Open the selected row's directory in your editor |
f |
Fork the selected conversation into a named session in the same group and directory |
g |
New group (name, parent, default path, worktree default, worktree base) |
C |
New SSH connection: another machine's sessions in this list (see SSH connections) |
enter |
Focus session in place (keys go to the agent, list stays) / fold group |
| click | Focus the session from its row or its preview (the full-screen layout selects the row) |
| double click | Fold the group / focus the session in the full-screen layout |
drag ⠿ / = |
Reorder the row, drop it into another group, or nest a terminal under an agent |
[…] / right click |
The row's actions |
| click the list / mouse back | Focused: back to the list |
A |
Attach session full screen (Settings can swap it with enter) |
. |
Mark a finished or waiting session idle without entering it |
ctrl+q / ctrl+\ |
Inside a session: back to the manager when the terminal and tmux leave the key available. ctrl+r, F3, ctrl+] and this pair move in the keybindings row of Settings, and so does every key of the list itself (see Key bindings) |
tmux prefix, then d |
Inside a full-screen attach: back to the manager when the prefix reaches the inner tmux |
F3 |
Inside a session: open its directory in your editor |
→ |
Step into the row: focus the session, or open the group. Settings (s) can turn the pair off |
← |
Step out: close the group, or — focused, with the caret at the start of the agent's prompt — back to the manager. This needs the tool's prompt marker (its activity_cutoff) on the caret's row, so a CLI without one keeps ← entirely; anywhere else in the prompt it moves the caret as usual |
K / J (or shift+↑ / shift+↓) |
Reorder session or group among its visible siblings |
m |
Move a session to a group, a terminal into a session, or a group under another group |
r |
Rename session / edit tool; on a group, open the Edit Group card (name, path, worktree, base, env) |
y |
Copy the selected session's newest reply to the system clipboard, without attaching |
x |
Kill the selected session, or every live session under a group: frees the RAM their agents hold, and the rows stay for v |
X |
Kill every live session in view |
v |
Revive a dead session, or every dead session under a group. A group asks first when more than one session under it is dead |
V |
Revive every dead session in view, asking first when more than one is dead |
R |
Restart the selected session on an empty context: same name, group, directory and tool |
a / u |
Archive / restore a session or group. Archive kills the process and keeps the last preview; restore resumes it |
c |
Keep a session that asked to be archived or killed once its turn ends: cancels that request |
d |
Delete session, or a group + its entire subtree |
space |
Quick prompt mode: answer the selected session, or spawn an agent in the selected group |
ctrl+r |
Review the selected session's changes: full-screen whole-file diffs, with c to comment a line and C to send the comments to the agent |
F |
Fold / unfold every group |
s |
Settings (default tool, theme, theme follows OS, background, list density, sessions layout, header and computer stats visibility, review layout, review scope, after quick send, session keys, ←→ step in/out, mouse, spawn in worktree, fetch on spawn, coordination, notifications, notify on finish, editor, keybindings, CLIs, saved prompts, environments, first-run setup, docs, report a bug, suggest a change, and the version row that updates in place) |
ctrl+] |
Resize the split, in the list and with a session focused: ←→ or h/l nudge the divider, enter commits, esc cancels. Focused in the split, any other key ends the gesture where it stands and then takes its usual route: to the agent, or to the manager action it names. The full screen layout has no divider, so ctrl+] does nothing there |
t |
Toggle archived view |
w |
Filter to sessions that need attention (waiting, finished, errored); press again to show all |
M |
Messages (the update notice with a release's highlights and thanks, maintainer messages, and tips, where x dismisses one for good). New notices open automatically. A long message scrolls with the wheel, pgup/pgdn, and home/end. While any message is left, the key legend leads with messages, and a click on it reopens them in either layout. |
e |
Hide / show empty groups |
/ |
Search the list by name. The field takes an accent fill while it is open, and the query lights up inside every matching session and group name |
? |
The key map for the current screen. From the list it shows every group; from review it shows only review bindings. It scrolls (↑↓/jk, pgup/pgdn, g/G) and / searches it down to one line. |
q |
Quit (sessions keep running) |
In a focused session, PgUp/PgDn scroll the pane's tmux history when the pane is on its normal screen, has not claimed mouse input, and has history to show. Otherwise the agent gets them, and alt+PgUp/alt+PgDn always reach the agent. Hermes recalls earlier prompts with Up/Down.
Shift+Enter reaches a focused agent as a new line when the terminal sends it as \x1b[13;2u or \x1b[27;2;13~ and the agent has asked tmux for extended keys, as Claude Code and Codex do. Enter, Tab, Backspace, Esc and Space held with shift, ctrl or alt reach such an agent the same way. An agent that has not asked gets none of them, since tmux would hand it a plain Enter or the key's name as text, except a key held with alt alone, which arrives with an ESC in front. tmux before 3.5 cannot report which agents asked, so there these keys are dropped. Ghostty and kitty send Shift+Enter as a plain Enter unless it is mapped. The mapping keybind = shift+enter=text:\n in Ghostty or map shift+enter send_text all \n in kitty works in every agent. Mapping it to \x1b[13;2u instead gives a new line only in agents that ask for extended keys and does nothing in the others.
Navigation is keyboard-driven, but the mouse works too. The manager claims mouse reporting so the wheel stays inside the app and cannot scroll the TUI out of view: a notch moves the session cursor in the list and scrolls the diff, and in a focused session it walks that pane's scrollback, where click-drag also selects pane text and copies it. In the split, a click on a session row focuses it when the button comes back up, so a press that slides off the row does nothing, and a press on the preview beside the list focuses the session under the cursor at once, unless it lands on a link that shows its own address. That press never reaches the agent, so an agent that tracks the mouse never receives it. In the full-screen layout a click selects and a double click focuses. A double click on a group row folds or unfolds it. With search open a click only selects. With quick prompt mode open, clicks work as they do in the list, and one that leaves the list closes the prompt. While a session is focused beside the list, a click on another row focuses that one, and a click anywhere else in the list column, the focused session's own row and the blank below the rows included, returns to the list. The mouse back button returns in either layout. Every row carries a drag handle beside its name: ⠿ in Advanced mode or = in Compatible mode. Drag it to reorder the row among its siblings, onto a group row to move it into that group, onto a session in another group to land just before it, or, for a terminal, onto an agent to nest under it. The row a drop would land on is tinted and the footer names the move. Letting go stores it, esc puts everything back, and holding the drag on the top or bottom row of a long list scrolls it. A click on the handle without a drag keeps the row lifted for the arrow keys, with enter to drop and esc to put back. The […] at the end of every row opens the row's actions, each with its key beside it: attach, prompt, copy the last reply, review, fork, new terminal, editor, rename, move, restart, archive, kill and delete, trimmed to what the row can do. Hovering or the arrow keys highlight an entry, and a click or enter runs it, as does letting go over an entry after pressing […] and dragging onto it. A right click opens the same menu in terminals that pass right clicks to the app. iTerm2 keeps right clicks for its own menu unless its pointer settings pass them on. With the mouse toggle off, rows paint no handle and no […]. A press on the sessions/sidebar divider drags it without arming resize mode from the keyboard first, and it drags the same while a session is focused: that press never reaches the agent, focus stays where it was, esc before letting go cancels the move, and any other key ends it where it stands and goes on to the agent. While any message is left, a click on messages in the key legend opens Messages, the same as M, in either layout. Settings has a mouse toggle, on by default; turning it off releases mouse reporting everywhere except a focused session, which hands the terminal back native click-drag text selection over the rail and the content column, and the wheel with it: the diff stops scrolling and the host terminal can scroll the manager out of view again. Clicking a link in a focused pane opens it, in either layout. That covers a web address written out in the pane and a hyperlink an agent draws behind other text, such as a markdown link. A hyperlink to a file on this machine is shown in the file manager rather than opened, so a click never runs it. Hovering a link names its target on the status bar, so a label cannot hide where it goes. The mouse claim keeps the terminal's own opener out of reach, so the manager does the opening itself. A link the pane wrapped across rows opens from any of its rows, and a press in the preview beside the list on a link that shows its own address opens it rather than focusing the session. A label that hides its target focuses the session there, so its target is named before it opens. Hovering a link turns the pointer into a hand in terminals that let an app set the pointer shape (OSC 22), such as Ghostty, kitty and iTerm2 3.7. In a focused agent that tracks the mouse, a click off a link passes straight through to its own clickable UI while a drag still selects and copies; hold alt to pass a whole drag through instead, for the agent's own text selection or sliders. See #110. Over SSH a clicked link is printed on the plain terminal instead, with the manager stepped aside, so your own terminal can open or select it. The manager also sends it to your clipboard with OSC 52, which lands where the terminal accepts clipboard writes. Enter brings the manager back. Inside tmux the check follows the client that attached last. Copies over SSH take the same OSC 52 route, except through an X11 display forwarded by ssh, where xclip or xsel reach your clipboard.
Every other screen answers the mouse the same way. A click on a key in a footer, in a card's foot, in Messages' bottom edge, or on a key pill in Review's header runs that key as if typed. Keys, cards and row menu entries act when the button comes back up, so a press that slides off does nothing. The pairs that move a cursor (↑↓, ←→, pgup/pgdn) stay with the keyboard, since the rows and the wheel cover them. In a list inside a card (Settings, CLIs, Keybindings, saved prompts, Move, Review's repo, branch and target pickers, Messages' titles), a click moves the cursor to a row and a second click on that row runs it, the way ↵ runs an action and → steps a value, and the wheel moves the cursor while the pointer is over the card. In CLIs, a checkbox toggles and the request line opens a GitHub issue on the first click. A group's edit (r) takes clicks on its path, worktree, base and env rows the way New Group does. A click on a path suggestion completes it, and the wheel scrolls New Session's model list and group picker and the quick prompt's model sheet. In Review a click opens a file, shows a commit from the commit rail, moves the cursor to a code line, or answers the send question, and a click on a file's or a commit's ○ or ✔ marks it reviewed or clears the mark, a commit's for every file in it. A click beside a card closes it the way esc does, except New Session, New Group, Fork, the Settings editor line while it is typed, and a saved prompt being edited, which keep what was typed. Outside a focused session, the mouse toggle turns all of it off with the rest.
Press space to enter quick prompt mode, which takes over the footer: the target and the prompt on a band across the whole width with an accent edge on the left, and the mode's keys on the row under it. The footer offers it first on every agent and group row, on a fill of its own. A prompt that wraps takes its extra rows from the body, and the sessions' panes keep their size while it does, so the preview crops instead of every agent redrawing. The target follows the cursor while the bar is open: ↑↓ still navigate the list from a one-row prompt, and in a taller one ↑ navigates from the top row and ↓ from the bottom row. Anywhere else they move the caret, so a prompt that wrapped or was pasted with line breaks edits like a multi-line editor.
- On a session row,
entersends the typed text straight into the session's pane, so the agent gets it as a user message without you attaching. The bar clears and stays open, ready for the next answer; Settings (s) can make it close instead. - On a group row,
enterspawns a new agent in that group and submits the prompt at startup, using the group's default path. This is the shortest path to a fresh agent:space, type the task,enter, with no form and no name to invent. The spawn tool starts on the Settings default tool row, which every local session you create from the form or this bar sets to its tool.tab(oralt+m) steps it forward (claude ↔ opencode ↔ any configured tool),shift+tabsteps it back one. The target row shows what the new agent launches with on its right: the tool, its model, effort and profile, and the worktree, and a click on one does what its key does.ctrl+lswaps the bar for a sheet listing the models the tool reports, where typing filters,enterpicks andeschands the prompt back.ctrl+xsteps the reasoning effort through the levels that model takes, andctrl+ysteps the profile of a tool that has profiles, from the bar or the sheet (see Model, effort and profile).ctrl+gsteps the environment profile the agent launches under, starting from the target group's (see Environment profiles).ctrl+t(oralt+w) toggles whether the new agent spawns into its own git worktree, starting from that last session's pick, or the Settings default before any. The target row reads⎇ onor⎇ off, or⎇ no repowhen the target directory cannot hold one; Compatible mode usesYin place of⎇. Answering an existing session ignores the toggle, since there is no new session to place in a worktree. The agent starts working on the prompt immediately.
ctrl+v pastes an image from the system clipboard as an [Image #1] chip at the caret. The image is saved under agent-manager-pastes in your temp directory, and on send each chip is swapped back for its path, so the paths reach the agent in the order and the places you pasted them. backspace next to a chip removes the whole chip, and an edit that swallows one releases its image. A clipboard holding text rather than an image pastes as text. Pasted images older than seven days are cleared at startup and once a day while the manager runs, so an agent can still open one from an earlier session while temp stays tidy.
esc closes the bar. enter on an empty prompt closes it too.
The new-session form's optional prompt field launches an agent the same way, and its ↑↓ move the caret between rows the same way, ↑ leaving the field only from its top row and ↓ only from its bottom row. It takes ctrl+v and its chips too, since a first task is often the screenshot that explains it: paste the design to match or the crash to read, and the agent opens the file on its first turn. Leaving the form without creating the session releases the images it was holding, the way closing the bar does. How the prompt reaches the agent depends on the CLI: most take it as a launch argument, and a persistent CLI that accepts none has it typed into its composer as soon as that composer is ready.
The "sessions layout" row in Settings (s) hands the session list the whole terminal: ← or → swaps it to full screen, the preview column steps aside, and every row takes the full width. The same keys return it to split, the default, and the choice is persisted like the split ratio.
Session rows read the same way in either layout, and the list density setting picks their rhythm. Compact keeps a session to one line: mark, name and badges, then a state-picked value riding to the right of the name with state · tool · age against the right edge. That value is the agent's last message whenever it has said anything (the question it waits on, its progress, its result) behind a static ↳ washed in the state color, and the task it was given behind the accent's ❯ only while it has not. Comfortable unfolds each session to three lines: the name line, your last message behind a ❯ in the accent, and the agent's last message under it. A terminal keeps two of them, its name line and its last output, since no one is prompting a shell. Both messages come from the session's own record: the prompt echoed into its transcript (typed in an attach, the focus view, or quick prompt mode, all the same) and the reply read from above its input box, recovered from the tool's session store when it scrolled away. pi and omp draw a prompt with no mark that tells it from a reply, so theirs is read from the session file each keeps. A waiting session's message wears its state color at full strength, the other states at a wash of theirs; a working session that has not said anything yet animates a loader. Groups stay one line at any density. In the full-screen layout the meters condense to one labeled line above the key legend: cpu, mem, swap, disk, battery (when present), temperatures and net. The separate header and computer stats settings apply in either layout and return hidden chrome to the session list. Hiding computer stats removes the whole lower block, including its separator. Messages open automatically when new notices arrive. M reopens them, and so does a click on messages in the key legend while any message is left. In Compatible mode, the prompt and reply prefixes are > and <.
Sessions size themselves to the layout that shows them: the full-screen layout pins their tmux windows to the whole terminal body, so an opened or attached session spans the full width, and switching back to the split re-pins the width. A pane that grew taller follows the box back down when its agent runs on the terminal's alternate screen (Claude Code, OpenCode) or keeps its scrollback through a height change (Grok). Any other pane keeps its height and is cropped on screen instead, because a height change makes Codex clear its whole scrollback.
Opening a session (enter, or →) takes the whole body too, through the same pipeline focus mode uses in the split: keys go to the agent, ctrl+r, F3 and the footer stay alive, and ctrl+q, the mouse back button, or ← with the caret at the start of the agent's prompt, returns to the list. A still hands the terminal over with a real tmux attach. Every footer that replaces the key legend for a moment, focus's and rename's takes a single row in this layout and leaves the rest to the body; in the split those rows are held so the preview box beside them stays where it is. A line of its own says which session you are in, a hairline holding it off the header band above and the pane below: its state dot and name, the tool, the state and how long it has held it on the left, then its directory, its worktree branch, its own cpu and memory, how long ago it started, and a queued count when messages are waiting, against the right edge. The keys are in the footer under the pane. As the terminal narrows the readings give way one at a time, the least telling first, so what fits still shows.
Every configured tool is offered when you create a session, which is more than most people run. Settings (s) has a CLIs row: enter opens a checklist, space or enter unchecks the tool under the cursor, esc saves, and the ones left checked are what the n form's tool picker and quick prompt mode's tab cycle through. The last checked tool cannot be unchecked, since a picker with nothing in it could not create a session. It only narrows the pickers, so a session already on an unchecked tool keeps running and revives on that same tool. The last row, request CLI support, opens an issue for a CLI we do not ship rules for yet.
Both pickers start on the default tool row of Settings. A local session you create from them sets that row to its tool; a session on an SSH connection does not. The next session, after a restart too, starts on the CLI you last picked, and so does an agent-manager spawn with no --tool from a terminal tab or a script. Changing the row in Settings moves the starting point, the same as a pick does.
Settings (s), row saved prompts. n creates one, enter edits it, d deletes it. tab moves between the name and the text, ctrl+s saves, esc backs out. From a shell, agent-manager prompts add.
On a new session, left and right pick one. ctrl+o or enter opens the list. The text is placed in front of the task. In the quick prompt, ctrl+o drops a chip that becomes that text when you send. In a focused session, f4 pastes it and does not send. f4 can be changed with the other session keys.
agent-manager prompts add reviewer "Review the parser changes"
agent-manager spawn --saved reviewer --prompt "Start with the tests"
agent-manager send <session-id> --saved reviewercreate_session and send_session take the same name in saved. A missing name is refused. Changing or deleting one leaves a session that already started alone.
The n form has model and effort rows under tool, and a profile row above them for a tool that has profiles. Quick prompt mode has the same choices on ctrl+l, ctrl+x and ctrl+y, and agent-manager spawn takes --model, --effort and --profile. Every value comes from the CLI itself. The manager asks it through the interface it offers programs, so a model that ships next week shows up in the list without an Agent Manager release.
Left alone, each row keeps the CLI's own default, which is whatever you set up in that CLI. Each CLI remembers the model, effort and profile you last picked for it, in the form and quick prompt mode alike, and the next session on that CLI starts there. In the form, the model row's list stays shut until you ask for it, so tab and the arrows pass over the row: typing opens it filtered, and ctrl+o or a second click on the row opens it on every model. The model list filters as you type, the way dir suggests paths, the arrows scroll through every model the CLI lists, and only a listed model can be picked. A model typed there or passed to spawn --model matches by its id, or else by its name in the list in any case, so --model sonnet picks the model Claude on Bedrock lists by its Bedrock id and names Sonnet. The first row, cli default, goes back to the CLI's own default, and your last picks for that CLI come next. The effort row offers the levels the chosen model takes, or the levels of the model the CLI starts on while none is picked, and it leaves the form for a model that takes none. The choice is saved on the session, so restart (R), revive (v), a relaunch inside its pane and fork (f) all run on it.
| CLI | Asked through | Model | Effort | Profile |
|---|---|---|---|---|
| Claude Code | the Agent SDK initialize request |
yes | per model | · |
| Codex | codex app-server |
yes | per model, with its default | not supported |
| Grok Build | ACP over grok agent stdio |
yes | per model | · |
| Pi | pi --mode rpc |
yes | per model | · |
| Muse Code | muse serve |
yes | per model | · |
| OpenCode | opencode models |
yes | not supported | · |
| Gemini CLI | ACP over gemini --acp |
yes | not supported | · |
| Hermes Agent | hermes serve |
per profile, with the provider | typed | yes |
| Antigravity CLI | agy models |
yes | per model | · |
| Command Code | nothing a program can ask | not supported | not supported | · |
| Cursor CLI | ACP over cursor-agent acp |
yes | carried in the model id | · |
| Kiro CLI | not asked yet | not supported | not supported | · |
A row the CLI cannot fill reads "not supported". OpenCode and Gemini CLI take no effort when they launch. Cursor CLI carries effort inside the model id, so the form offers no separate effort control. Antigravity CLI lists each thinking level as a model of its own, "Gemini 3.8 Flash (High)" beside "(Medium)" and "(Low)", so the form folds them into one model with those levels as its efforts. Codex's -p reads <name>.config.toml files that none of its interfaces list, so it has no profile row. Hermes says which models reason but not their levels, so its effort is typed, and only a model that reasons shows the row. Pi's list needs Pi 0.84.3 or later, because earlier releases save every model they are asked about as your default. An older release opens the update dialog instead of listing models or starting the session. When a CLI fails to answer for any other reason, the model row says why, the session launches on the CLI's defaults, and the next form asks again once half a minute has passed.
The answer is kept under catalogs in the config directory for six hours, and an upgraded CLI is asked again at once. The manager asks from its own catalogs/work directory, because some of these interfaces open a session to answer, and that session must never land in a directory a real session works in. Gemini CLI records a short chat for that directory each time it answers.
An environment profile is a named set of environment variables a session launches under, on top of the environment the manager itself runs in. It works the same for every CLI and for terminals, since the variables are exported in the pane before the CLI starts. One use is running a CLI against a second account or config directory, such as Claude Code under a separate CLAUDE_CONFIG_DIR for work:
agent-manager env set work CLAUDE_CONFIG_DIR="$HOME/.claude.work" KUBECONFIG="$HOME/work/kubeconfig"
agent-manager env list # names and the variables each sets
agent-manager env show work # the values too
agent-manager env unset work KUBECONFIG
agent-manager env rm workProfiles are defined from the shell alone, because a value can be a token. Settings (s) lists them on its environments row, by name and variable, never by value; the row appears once a profile exists. Values are stored as given: the shell expands $HOME as you type the command, and the manager expands nothing. A variable the manager sets itself (AGENT_MANAGER_*) cannot be set by a profile.
The n form has an env row once a profile exists, quick prompt mode steps it with ctrl+g, agent-manager spawn takes --env <name>, and create_session takes environment. A group can carry a default: the env row of New Group (g) and of a group's edit (r), shown once a profile exists, steps through the profiles, and every spawn into that group or a subgroup under it starts on it, marked (group) on the form. A spawn that names no environment takes the group's, and an agent's spawn, or a terminal opened under a session, takes that session's when the group has none. --env "" launches under none.
The profile is saved on the session by name, and its variables are read again at every launch, so restart (R), revive (v), a relaunch inside the pane and fork (f) run under the profile as it stands then. A session naming a profile that was since removed refuses to launch and says so, rather than starting under the wrong account. A variable the profile no longer sets is unset at the next launch in that pane, not restored to the value it had before the profile set it, so a profile that drops PATH can leave a bare command such as claude unresolvable; keep PATH in a profile whose agent needs it. The models a form offers are still read under the manager's own environment.
T opens a shell tab: a session like any other (same list, same row keys, same enter, x, v and R) with your shell in the pane instead of an agent. On an agent, the new shell nests under that session, in that agent's group and directory. On a group, it lands in the group as an un-nested sibling, in the group's default path. On a nested shell it joins the same parent; on an un-nested shell it stays un-nested in that shell's group. Either way it opens in that shell's own directory, so a shell you have cd'd somewhere hands the next one the same place. A nested shell is named after the session it hangs under, terminal-review-done rather than terminal-0ab5, and the next one under that session counts up to terminal-review-done-2; a shell with no session over it keeps the generated name, and r renames any of them. Its status rests at idle throughout: turn tracking belongs to agents, and a shell has no turns.
The pane opens on $SHELL, so it is the shell you already use everywhere else.
Shells live in the tree with the agents they belong to, marked with ❯ where an agent carries its status dot. m on a terminal moves it onto an agent (nests under that session) or onto a group (un-nests into that group). A group's dots and counts describe its agents, so only agent work shows as in progress.
The keys that write into a pane refuse a shell. space and the review screen's C both paste their text and press Enter, so on a shell a sentence meant for an agent would run as a command. Both say the row is a shell and send nothing; enter the session (↵) to type there, where what you type is plainly a command. f says the same, since a shell has no conversation to fork.
agent-manager rename run in a T terminal renames that terminal's own row: the manager finds the row from the tmux pane the command runs in. r in the list is how you rename any other row.
o opens the row under the cursor in your editor: a session's live working directory (wherever its shell or agent has moved to, not only where it started), the directory it was created in when the live one cannot be read, or a group's default path. It works on a terminal tab too — the shell you ran the build in is usually sitting in the directory you want open.
The editor row in Settings (s) picks it. ←→ steps through auto, each GUI editor found on your PATH (code, cursor, windsurf, zed, subl, idea), the editors $VISUAL and $EDITOR name, and custom, where ↵ opens a field for a command of your own. auto names the editor it resolves to: $AGENT_MANAGER_EDITOR, then the first of those GUI editors on PATH, then $VISUAL or $EDITOR. The environment comes last because it usually names the editor you set for git commit messages, and a project is better opened in a windowed one.
The line is run directly, never through a shell, so nothing in it is expanded and an .envrc that sets EDITOR cannot smuggle a command in behind it. A custom command takes arguments, and quotes group one that carries a space: code -n, open -a 'Visual Studio Code'.
Inside a session, attached or focused, F3 opens that session's directory the same way. It costs an attach its client, so the manager steps back into the session once a windowed editor is running, or once one that draws in the terminal exits. An editor that fails to start keeps the manager on screen, where you can read why.
Like ctrl+q and ctrl+r, the manager keeps F3 for itself inside a session, so a program running in there stops seeing it; ctrl+] joins them while the session is focused, since an attach has no split. Every other ctrl combination reaches the program, ctrl+o included: Claude Code shows more lines with it, Gemini CLI toggles copy mode, and in a terminal tab nano writes the file out. The keybindings row in Settings moves any of these keys, or turns one off so the agent gets it (see Key bindings).
A known windowed editor (the six above, plus open and xdg-open) starts detached and the manager stays on screen, with the status line naming what opened. Everything else takes the terminal over the way an attach does and hands it back on exit — that way round because a terminal editor started detached would have nowhere to draw, while a windowed one launched this way only costs a repaint.
A session can spawn into its own git worktree instead of the shared working directory: the n form has a worktree field between dir and prompt (◂ on ▸ / ◂ off ▸, toggled with ←→), and quick prompt mode's ctrl+t does the same for a group spawn. Settings (s) has a "spawn in worktree" row that sets the default both start from, and the last session you created in this run carries its pick over to the next one.
The worktree lives at <repo>-worktrees/<name> next to the repo, on a new branch am/<name>. Its starting point is the branch the repo's work merges into. In a repo with an upstream remote, which GitHub's fork layout makes the parent repository, that is upstream's default branch. Otherwise it is origin's default branch, then a local main or master in a repo with neither, and finally HEAD. The default branch's name comes from the remote's HEAD, which git clone records, and an upstream without one borrows origin's. A worktree that fails to create blocks the spawn with an error instead of falling back to a shared directory.
A group can name the starting point itself. The base row of the g form, and of a group's edit card (r on the group row), steps with ←→ through auto and the repo's branches. A group left on auto takes its parent's base, and with no base set anywhere up the tree the starting point is detected as above. The same base is what review's "vs target" compares that group's sessions against, until a target is picked in review. It suits a team that branches off develop, and a repo whose upstream remote is a mirror rather than the target of its pull requests.
While the n form or quick prompt mode is set to spawn a worktree, the manager fetches the starting point's branch from its remote, that one branch alone, at most once a minute for the same directory, so the new branch starts from the remote's tip. The n form shows the starting point in a base row under worktree, marked (group) or (auto) by where it came from, and says while the fetch runs and when it failed. A spawn that beats the fetch, or one made offline, starts from the last fetch. Sessions created through create_session fetch before the worktree is made. The "fetch on spawn" row in Settings (s) turns the fetch off, for SSH keys that ask for a tap on every use, slow networks, or servers that count fetches, and worktrees then start from whatever the last fetch left.
A branch that starts from a remote other than origin, such as the parent of a fork, keeps tracking it, so git pull brings in the parent's changes, and git push sends it to origin, your fork. A remote.pushDefault you set routes pushes instead.
A directory that is not a git repo cannot hold a worktree, so the field reads unavailable (not a git repo) and quick prompt mode's target row ⎇ no repo in place of on/off, the toggle says why when pressed, and the session spawns in that directory as a plain session. This is what a group path sitting above several repos does: the umbrella itself is not a repo, so its sessions launch in it directly.
Renaming a session (r, or the agent's own agent-manager rename) keeps its worktree directory at the spawn-time path and renames only its branch to am/<new name>. The directory keeps the slug it was given at spawn (for example claude-7a72) for as long as the worktree exists, even as the session name and am/ branch change. The stable directory keeps the running agent's working path valid, while the branch still carries the name that appears in review and the eventual PR. A branch that already exists reports that and keeps the session on its old name. A worktree you have renamed or removed by hand, switched to another branch, or left detached mid-rebase is left alone and the session still takes the new name.
Deleting (d) a session that holds a worktree removes the worktree and its branch when it is clean: no uncommitted changes, and no commits that exist nowhere else. Both the worktree's checkout and its am/ branch are checked, so a worktree switched to another branch or detached still keeps a branch that holds unsaved commits. The base is the starting point above, and a base of HEAD means the repo's own checkout. A branch whose changes are already in the base counts as merged, including after a squash or rebase merge whose remote branch was deleted and pruned. A branch that is itself the group's base is kept, since other sessions build on it. Spotting such a merge needs git 2.38 or later. Commits ahead of the base are also fine once they are pushed, since the base ref only moves on fetch and a merged branch would otherwise keep its worktree forever. The branch itself is kept in that case: a remote-tracking ref is a local cache, and holding the branch keeps those commits reachable even if the remote branch is gone. A dirty worktree is left in place and its path shown, so nothing is lost. Note that "clean" is judged by git status, so gitignored files inside the worktree (a .env, local config, build output) are removed along with the directory. Killing, archiving, and reviving a session never touch its worktree. agent-manager delete <id> and the delete_session tool delete a session the way d does: a worktree with unsaved work, or one another session still works in, stays with its branch, and the result's notice says so.
x ends a session that is holding RAM you want back, and on a group row it ends every live session under it; X ends every live session in view. Each asks to confirm first, and what it ends is the tmux session, not the record: the row stays in the tree, marked dead, with its name, group, and conversation id intact.
v relaunches a dead session under its old id, keeping its name, group, and history. When the manager holds that session's own conversation id, revive resumes that exact conversation through the tool's resume_by_id_command: claude --resume {id}, codex resume {id}, opencode --session {id}, grok --resume {id}, gemini --resume {id}, pi --session {id}, hermes --cli --resume {id}, cmd --session {id}, muse resume {id}, agy --conversation {id}, omp --resume {id}, cursor-agent --resume {id}, kiro-cli chat --resume-id {id}.
The row follows the conversation the agent is on. A /clear, /new, /resume, /fork or other switch inside the agent moves the row onto the conversation it switched to, so v reopens that one rather than the one the session started with. Claude Code, Pi, Oh My Pi, opencode and Command Code report each switch as it happens, through a hook the launch loads from the manager's own directory. Codex reports through the same kind of hook at the next prompt, and asks once to review the hooks before it runs them. Gemini CLI, Muse, Grok and Antigravity are read from state each keeps for the agent's process. The manager reads it while its screen is open, and once more when agent-manager kill, kill_session, agent-manager revive or revive_session runs. For Gemini CLI that state is local telemetry the launch writes to a file in the manager's directory. When your own Gemini CLI telemetry settings are on, the pane prints a notice and that session is not followed. Hermes names a /branch or /resume only as it closes, so its row moves once the agent has quit. Cursor CLI and Kiro CLI stay on the conversation captured at launch. Only the agent a launch started moves its row. A CLI the agent runs as a tool, a teammate, and an agent you type into the pane by hand leave it alone.
Quitting the agent inside a session leaves the window alive on a shell, and v brings it back there: the manager types the launch command into that shell, so the agent returns in the pane it left, carrying the session id, the MCP registration and the hook settings a launch gives it. The pane names that key the moment the agent exits. Those values stay exported in the shell as well, so agent-manager rename and the rest of the subcommands keep working from it, and so does an agent you start there by hand.
The id arrives one of two ways: tools with a session_id_flag launch under an id the manager mints, and tools that mint their own are read back by a session_store capturer (codex, opencode, gemini, hermes, command-code, muse, antigravity, omp, cursor, kiro). The comfortable list density shows the id once it is known. Without one, a tool with a resume_picker_command opens its own session picker in the pane on revive (claude --resume, codex resume, cmd --resume, pi --resume, bare grok, gemini -i /resume, hermes --cli sessions browse, muse resume, omp --resume, cursor-agent ls, kiro-cli chat --resume-picker), so the user picks the conversation; opencode's and Antigravity's pickers exist only inside their TUIs, so revive launches them bare and the manager types /sessions or /resume at the composer once the caret rests there. A relaunched session binds the picked conversation's id back after the pane settles on it: the manager snapshots the tool's store right before the relaunch and binds only the single conversation whose activity outruns that snapshot on two consecutive polls, so a conversation merely written before the revive is never mistaken for the pick. Tools without a picker fall back to revive_command (claude --continue), which resumes the working directory's most recent conversation, and the manager says so in the status line, since sessions sharing a directory would otherwise land on the wrong one. On a group row v revives every dead session under it, and V revives every dead session in view. Each asks to confirm first when that is more than one session, and a single dead session comes back at once. Both revive what they can and name the first failure rather than stopping.
R keeps the row and drops the context: same name, group, tool, and working directory, a managed worktree included, launched on a conversation the agent has never seen. It is what you want when a session has piled up context you are done with, where reviving it would spend the budget re-reading history or land straight in a compact.
It asks to confirm first, and it works on a live session too: the running agent ends, then the fresh one launches. The conversation it was on is retired rather than resumed: the manager mints a new id for tools that take one (session_id_flag) and captures the new one for tools that mint their own (session_store). The retired conversation is left on disk untouched, and the row stops pointing at it, so a later v resumes the conversation the restart started rather than the context it dropped. The row changes hands only once the new agent is up, so a launch that cannot start (a tool gone from PATH, a directory that moved) leaves the session on the conversation it had, still there for v.
- Select a session and press
f. - Enter a name.
- Press
enter.
The fork uses the source session's tool, group, working directory, and conversation history.
Claude Code, OpenCode, Codex, Grok, Gemini CLI, Pi, Command Code, and Muse Code include default fork commands. The source session must have a captured conversation ID.
Muse forks only from inside the running source, so f types /fork into the source session and opens the fork Muse records in a new pane. The source has to be running and at rest with nothing typed at its prompt. Otherwise f says what to do first and types nothing.
A fork shares its source session's managed worktree. Agent Manager keeps the worktree until you delete the last session that uses it. You cannot rename the worktree while another session uses it.
Sessions spawned without a custom name (every quick spawn, and the form with the name left blank) get a placeholder like claude-a1b2, and their first prompt opens by asking the agent to run agent-manager rename "<name>" once with a short name for the broad feature of the session (not a single subtask). The directive also tells the agent not to rename again unless you ask. When the first prompt cannot carry the directive (a /slash command, or no prompt at all), the manager sends it as its own message once the tool's input box appears in the pane and the turn it launched on has ended. The subcommand drops the name into a per-session file; the manager picks it up on the next poll and updates the sidebar row and the tmux status bar. The subcommand waits for that poll and answers with the name as applied, or with the reason the session keeps its name (a worktree branch the new name cannot take, for instance). With no manager open it reports the name as queued, to be applied when one opens. This works with any tool, since it only needs the agent to read its prompt and run one shell command.
Sessions you name yourself keep that name: the first prompt only notes that agent-manager rename is available later if you ask, and does not instruct the agent to rename now. You can still ask an agent to rename its session later, or run agent-manager rename yourself from a shell inside the session.
A session's working directory is often an umbrella folder holding many repos, so review can only guess which one the agent means. An agent that knows which repo it is working in can say so by running agent-manager review-repo <path> from a shell inside its session. The subcommand checks that the path is (or sits inside) a git repo, resolves it to the repo root, and drops it into a per-session file; the manager picks it up on the next poll and review opens on that repo the next time you open it. A path that is not inside a git repo is rejected, so a declaration is always a fact rather than a guess.
An agent can also declare what its branch diffs against by running agent-manager review-base <ref> from inside its worktree: the ref is validated in that repo, stored per session and repo, and the "vs target" scope uses it from then on. agent-manager review-base --clear returns to the group's base, or to automatic detection when the group has none. A stored ref that stops resolving surfaces as an error in review, and B opens a target picker (the repo's branches plus an auto entry) to set or clear it by hand.
Agents usually work in git worktrees, one branch per worktree, and those worktrees can live anywhere on disk. A declared path that is a worktree root is accepted wherever it lives, so one review-repo call names both the repo and the branch under review. Review resolves its target in a fixed order: a repo or worktree you picked by hand with r or b wins for as long as the manager is running, then the agent's declared repo, then the ranking (dirty working trees first, then most recent commit). When the picked or declared path stops being a git repo, review says so in the status line and r is there to pick the right one.
Every session of an MCP-capable tool carries the agent-manager MCP server on spawn and revive, so its agent sees the whole workspace as native tools with descriptions telling it when to call each: its own session, the other agent sessions running beside it, the groups they are filed under, and the managed terminals. No per-project setup. Pi is the shipped tool whose agent has no MCP client, so those sessions rely on the subcommands alone. The server lives in the same binary (agent-manager mcp, stdio) and identifies the calling session through its environment.
| Tool | Action |
|---|---|
rename |
Rename the calling session |
review |
Declare the repo under review, the base ref and the diff scope, in one call |
review_comment |
Mark a sent review comment handled after addressing it, or reopen it |
report_issue |
File a bug report or feature request on the agent-manager repo for the user: a preview first, and posting only with the id that preview returned |
list_sessions |
List every agent session with its id, CLI, group, directory, worktree branch and status |
create_session |
Start another agent CLI on a named task, optionally in its own git worktree |
read_session |
Read what another agent's screen currently shows |
send_session |
Queue a message for another agent, delivered once it is at rest |
message_status |
Check whether a message is queued, held, delivered, dropped or answered |
wait_for_session |
Park until another session stops working, instead of polling it |
revive_session |
Bring a dead session back, resuming the conversation it held |
kill_session |
Stop a running agent, keeping its row and last screen |
delete_session |
Delete a session and its terminals the way d does, removing its worktree and am/ branch as d would; a worktree with unsaved work, or one another session uses, stays and the notice says so |
archive_session |
File a finished session out of the active list, or restore it |
move_session |
File a session under another existing group, the way m does; its nested terminals go with it |
archive_self |
Archive the calling session once its current turn ends, the way a does |
kill_self |
Kill the calling session once its current turn ends, keeping its row for revive, the way x does |
task |
The shared work list in one tool: action is list, create, claim, finish, release or delete |
reserve_files |
Declare the files this session is editing, and see who else claims them |
release_files |
Give those claims back |
list_reservations |
See what every session is editing right now |
list_groups |
List groups with their default directories, worktree defaults and session counts |
create_group |
Add a group, nested with a slash path, to file a fleet under |
delete_group |
Remove a group whose work is done; sessions still filed there move to the root rather than stopping |
list_terminals |
List active managed terminals and their current directories |
create_terminal |
Open a terminal under the calling session, or beside it when that session is itself a terminal, unless nest is false |
send_terminal |
Submit a command or send exact keys to a running terminal |
read_terminal |
Read the plain-text content currently visible in a terminal |
close_terminal |
Close a finished terminal nested under the caller: kill the pane and delete the row |
When you have added SSH connections, list_sessions, list_terminals and list_groups refresh every connection at once and list its rows after this machine's, each with host set to the connection's name and its id written host::id. A host that cannot be refreshed never fails the list: its last rows come back with stale: true, and connection_errors says what went wrong. read_session, send_session, kill_session, delete_session, revive_session, archive_session, move_session, read_terminal, send_terminal and close_terminal take a host::id and run on that host. A message sent there comes from <session name> on <this machine's hostname>, and message_status cannot follow it, so read the agent's screen instead. create_session, create_terminal, create_group and delete_group take a host argument; a session or terminal created there inherits nothing from the caller, so it lands in the root group and the remote user's home directory unless the call says otherwise, and the terminal hangs under no session. Only the session that opened a terminal there can send to it or close it, the way a session here drives only the terminals nested under it; one you opened with T on the connection row stays yours. A terminal opened in the host's own manager, or under one of its agents, is listed but cannot be sent to or closed from here. wait_for_session, task and review_comment refuse a host::id, since that state stays on each host. A connection added in the manager while an agent runs reaches its MCP server on the next call.
The coordination row in Settings (s) sets how far agents go with the other sessions on their own. on request, the default, tells each new session that the others exist and that it lists, messages, spawns or waits on them, and creates or claims shared tasks, only when you ask. "Spawn an agent for this" and "wait for the api session, then deploy" keep working, since every tool stays registered. proactive has agents delegate a parallel workstream to a new session and check the shared task list before starting work, without waiting to be asked. The mode reaches an MCP client through the server's initialization instructions and the create_session and task descriptions, and Pi through a note on its first prompt and the agent-manager help text. A session is briefed when it starts, so the ones already running keep the mode they started with.
create_session gives an agent the same spawn the n form gives a human: a name, a CLI, a group, a working directory, a first prompt and a worktree choice. A session created this way is a normal row in the list, and the manager picks it up on its next poll, so it attaches, revives, forks and reviews like any other.
Each field falls back the way the form does. The CLI defaults to the one the calling agent runs, the group and directory default to the caller's, an explicit group uses that group's nearest inherited default path, and an explicit directory wins over both. A name is the agent's to choose and should describe the work; leaving it empty generates a placeholder and asks the new session to rename itself, exactly as a promptless spawn from the form does. Passing worktree: true adds a git worktree and branch off the directory's repo, which is what keeps several agents working in one project from editing the same checkout; omitting it inherits the group's default, then the global setting. model, effort and profile launch the CLI on values it lists instead of its defaults, the way the form's rows do (see Model, effort and profile). A value the CLI does not list is refused with the ones it does. environment names an environment profile to launch under; omitted, the session takes the group's, then the calling agent's own (see Environment profiles).
resume brings in a conversation the CLI saved before, outside the manager or in a row since deleted. It takes the CLI's own conversation id, and the session launches on that tool's resume_by_id_command instead of a new conversation and keeps it on every revive. Pass the directory the conversation was saved in. The manager looks for it in the CLI's own store, read under the session's environment profile, and refuses an id it does not find there. A resumed session never opens a worktree, and worktree: true beside resume is refused. Nothing is sent into the conversation unless prompt is set, which is typed in once the agent is up. Without a prompt the agent gets no message to rename itself in, so a promptless resume needs a name. The manager refuses a conversation another row of the same CLI already holds, and when an agent switches onto a held conversation itself, its row takes the conversation over. list_sessions reports each row's agent_session_id, so an agent importing saved conversations can skip those first. From a shell the same is agent-manager spawn --tool codex --name api-login-fix --directory ~/src/api --resume <id>.
read_session returns the target's current screen, and its last captured screen once the session has stopped. kill_session ends the process and leaves the row dead with its last screen, revive_session brings it back on the conversation it held, and archive_session files a finished row away or restores it. delete_session removes the row for good, with its terminals, and cleans up the worktree it created the way d does. A worktree with unsaved work, or one another session still works in, stays with its branch, and the result's notice says why. An agent that quit while its window stayed open is relaunched inside that pane, so the row keeps the screen its last life left there.
An agent ends its own session with archive_self or kill_self (agent-manager archive-self and kill-self from a shell), so "archive yourself when it is merged" needs no trip back to the list. The call files the request and returns, the agent finishes its reply, and the manager acts on the first poll that reads the session at rest: finished, waiting on a question, idle, errored or dead. Archive and kill then take the same steps as a and x, nested terminals included. Until then the row wears ↓ (archive) or ■ (kill), or A and K in Compatible mode, next to its name, and the preview header says when it goes. c, or Cancel in the row's menu, keeps the session. The agent can withdraw it too with cancel. A restart or revive in between drops the request, since it came from the run that ended.
send_session queues a message rather than typing it immediately. Several agent CLIs keep their input line drawn underneath an approval dialog, so a message written at that moment would answer the dialog instead of being read. The manager holds it and types it in on the first poll where the target is at rest: its input region is drawn, its status is not mid-turn, its own rules report no dialog on screen, and nobody has a line part way written at its prompt. Delivery is at most once, and a message the manager cannot prove reached the pane is retired as dropped rather than repeated, so its sender knows to send it again. The list shows ✉ in Advanced mode or @ in Compatible mode, with the waiting count on the recipient's row until that paste lands.
The gate is the recipient tool's own rules, because text typed onto a dialog picks an option: while one is on screen the queue waits, and message_status reports those messages as held, naming the session to go and answer. A question the agent left at a resting prompt trips no rule, and a message goes in there as an ordinary turn would, labelled as coming from another agent. held also covers a recipient the manager will never type into as things stand, a session archived or stopped since the message was queued, and says which it is.
The message arrives labelled as coming from another of the user's agent sessions, with the sender's name and the id to answer on. The sender's own text sits inside a fence the manager mints at delivery, so a message written to imitate that label reads as what it is: the sender wrote it before the fence existed and cannot reproduce it. A receiving agent treats it as an instruction from the same operator and does the ordinary work the message asks. Permission prompts and that session's CLI settings stay with the person at the keyboard. Commit, push, merge, publish, and delete wait for them too. The envelope names how to reply when something is still needed, and tells the recipient to stop when the work is done. Queue caps, a per-sender rate limit, a size cap on one message and a whitespace-insensitive fingerprint keep two agents from talking each other into a loop. message_status reports whether a message is queued, held, delivered, dropped or answered; answering a session acknowledges everything it sent.
Delivery needs the manager running, since its poller is what types the message in. A message queued while Agent Manager is closed waits until it opens again, and send_session says so in its result rather than implying the message landed. A target that could never be reached is refused outright rather than queued: a session that is not running, an archived one, which the poller skips, and a tool declaring no activity_cutoff, which leaves nothing to read readiness from.
wait_for_session parks a single tool call until a session reaches one of the states that mean it stopped working, so an agent that spawned work does not read screens in a loop while it waits. A timeout returns the session's current state with reached false, because a timeout is an answer rather than a failure; outcome separates that from the session dying before it ever reached one of the awaited states. The wait counts from the caller's own handoff. While a message it sent is still queued, the session's state describes the turn before, so the wait carries on until that message goes in and its turn ends. When a dialog or an error holds the message, the wait returns that state straight away. It is an ordinary tool call, which is what makes it work with every MCP client.
The task list is the manager's shared to-do list, visible to every session, all of it behind the one task tool. create puts work on it, claim takes a piece (by id, or the oldest one nothing is blocking), and finish marks it done, which unblocks every task that depended on it. A claim is a single atomic write, so two agents racing for the same task cannot both win: the loser is told who holds it. A session that is deleted hands its claims back to the list rather than parking them forever.
A worktree per session stops two agents overwriting one checkout, and that is the right answer whenever the work divides cleanly. It does not help when sessions deliberately share a checkout, and it defers the other kind of collision to merge time: two agents making incompatible decisions about the same interface find out only when the branches meet.
reserve_files declares the paths a session is about to edit. Overlap with a lease another session holds comes back as conflicts, naming the holder and what they said they were doing, so the two can settle it through send_session before either commits. The lease is advisory throughout: nothing is blocked, and an agent may edit anyway. It expires on its own, so a session that dies holding one never keeps the repo to itself, and release_files hands it back as soon as the edits land. An exclusive lease conflicts with any other lease on the same paths; two shared leases sit side by side. Matching compares a pattern against a literal path in both directions, so two patterns that each contain wildcards are only compared exactly, which is another reason these are a conversation starter rather than a lock.
create_terminal nests under the calling session unless nest is false, and a call from a terminal opens the new shell beside it: under the same agent, or un-nested in the same group when that terminal is itself un-nested. It defaults to the calling agent's group and live pane directory. A group other than the caller's needs nest: false, since a nested terminal lives in its parent's group; that group then supplies its nearest inherited default path, and an explicit directory wins over both. close_terminal kills the pane and removes the row once the job is finished, and it reaches only the terminals nested under the calling session: a shell someone else opened, or one deliberately left un-nested, is the user's to close. send_terminal accepts exactly one of a command, which is pasted and submitted with Enter, or a sequence of tmux key names such as C-c, Up, and Enter. read_terminal returns the current screen rather than unlimited scrollback.
The server's MCP initialization instructions teach agents when to use these tools. They treat the other sessions the way the coordination mode says, and open a terminal for human-visible work such as SSH, when the user should be able to watch it, attach, or take over. They list and reuse a relevant running terminal first; create_terminal nests under the caller unless nest is false; they send the command and read its screen while the job runs; and they call close_terminal when that job ends, unless the terminal is being left for the user. One-shot local commands stay in the agent's normal tools. They also say to offer report_issue when the user hits a bug in the manager itself or asks for something it lacks. The same guidance is repeated in the individual tool descriptions for clients that expose tools but not server instructions.
Every one of these tools acts on the user's machine. Agents should treat send_terminal with the same care as typing into an attached shell, and treat create_session and kill_session as what they are: starting a real agent process that spends tokens, and interrupting one that may be mid-task. Inspect the target returned by list_sessions or list_terminals first, and read the result before continuing.
Registration is per tool. Claude gets a generated --mcp-config file. Codex gets -c mcp_servers... overrides. OpenCode gets an OPENCODE_CONFIG merge file. Grok, Gemini, and Command Code each get a one-time mcp add --scope user entry on their first launch, and Antigravity a one-time agy mcp add. Muse has no command that adds a server, so its first launch writes the entry into Muse's own settings file (see Configuration). Hermes gets its own one-time mcp add flow, which needs the MCP SDK its installer treats as optional: a Hermes still missing it refuses the spawn with a dialog offering the pip install mcp line for the Python that runs Hermes, read from hermes --version, so a Hermes session always carries these tools. A CLI that does not finish its registration within two minutes (the limit covers all the commands a tool's registration runs) does not hold the session back: it starts without these tools, the status line warns, agent-manager spawn and the MCP create_session and revive_session results carry a warning, and the next launch registers again. A spawn whose CLI is not on PATH is refused the same way, with the vendor's portable installer for a built-in agent, or the package manager on this machine for anything else. A CLI older than the oldest release the manager supports is refused with the same card, labelled update; one under /nix/store gets no installer and is asked to update the way it was installed. The dialog names the version on PATH and the one it needs, and the vendor installer updates it in place, with i labelled update. A CLI still too old after that installer exits opens the dialog again. When that command is the vendor's installer, c copies it and i runs it in a shell tab named after the CLI, where you can watch it and answer its prompts; when it exits 0 and puts the CLI on PATH the refused spawn goes ahead on its own, and a failure, or an installer that leaves the CLI somewhere PATH does not name, leaves the tab open with the output and the reason on the status line. A package-manager line stays a suggestion to read, since the package that carries a tool's name is yours to choose. A click on the command copies it, the same as c, and i, c and esc in the dialog's foot answer a click.
Pi does not include an MCP client. Its sessions reach the same workspace through the subcommands: agent-manager --help lists them, from sessions, spawn, send and wait to the shared task list, file reservations, terminals and the review declarations. update and settings need no caller at all, and issue and feature use only the session id the launch exported. Every other subcommand acts as the session or terminal tab whose pane started it, so the same subcommands work from a shell you opened with T. A Claude Code conversation the manager launched keeps acting as its session after /background, /fork or the agent view moves it into Claude's daemon, since its startup hook reports the conversation as the session's own. A Claude started by hand in a pane and moved there has no caller. A spawn from a terminal tab with no --tool runs the CLI picked in Settings. move also takes a host::id from one of your SSH connections and moves that session there, as move_session does.
sessions, groups, snapshot, spawn, read, wait, kill, delete, revive, archive, move, create-group and delete-group also run with no caller at all (a move of a host::id excepted, which needs one the way the MCP tools do), so a script, a cron job or a CI step outside Agent Manager can open sessions that show up in your list. Such a spawn runs the CLI picked in Settings, in the root group and the directory the script runs in, unless --tool, --group or --directory says otherwise:
agent-manager spawn --tool claude --group "Sprint Manager" --worktree \
--name ticket-123 --prompt "Fix TICKET-123 and open a pull request" --jsonsnapshot --json prints this machine's whole list as one JSON document: every session and terminal, archived ones included, the groups, and whether a manager is running here to deliver queued messages. It is what another manager reads over an SSH connection.
send <session-id> "<message>" --from <name> queues a message from a sender with no session on this machine, such as an agent on another machine sending over SSH. The name is up to 64 bytes with no control characters, and --from is refused from inside a session, which sends as itself. The delivered message names the sender as being on another machine and says a reply cannot reach it.
type <session-id> "<prompt>" submits a prompt in an agent's pane at once, as you, the way quick prompt mode does: no envelope, no queue, no wait for the agent to be at rest. It is how another machine's quick prompt mode answers an agent here over SSH, and it is refused from inside a session, which sends instead.
terminal create takes --name, the way spawn does, so a shell opened for a long job reads for that job instead of the session it hangs under. terminal create, send, read and close run with no caller too. There a new terminal hangs under no session, in the group --group names or the root, and only terminals opened that way can be driven: a terminal nested under a session stays that session's, and one you opened in the manager or a session opened stays out of reach.
The commands that run with no caller are a convenience for a manager reaching this machine over SSH and for scripts, not an isolation boundary. Anything running as your user can call them, and an agent that drops its session environment is treated as a caller with no session. What they keep is a guardrail: such a caller cannot drive a terminal it did not open, and every send --from counts against one shared set of message limits, whatever name it gives. type is outside that guardrail: it speaks as you, with no envelope and no limit, so a process that escapes caller detection can type into any agent as you. It waits for a send already reaching the same pane, from this or another process, so the two never submit as one prompt.
Queued messages, status and after-turn archives and kills move only while a manager runs. agent-manager serve runs one with no screen, on a machine where nobody keeps the TUI open, until it is interrupted or sent SIGTERM. serve --background starts that manager detached, with its output appended to serve.log in the profile directory, unless one is already running, and prints {"started":true,"pid":N} or {"started":false}. A serve holds a lock on serve.lock in the profile directory while it runs, so a second serve exits at once with a note that one is already running, and serve --background answers {"started":false} even before the first one has polled. It runs on macOS and Linux.
The MCP tools always act as the session that runs them, and refuse every call, host::id targets included, from a server with no session, since several CLIs keep the server registered for their runs outside Agent Manager too. report_issue is the exception: it touches no session, so it stays open there.
report_issue files a bug report or a feature request on the agent-manager repository for the user, from inside the session where the problem showed up. kind is bug or feature, title is the one-line title and body the report in markdown. The tool adds the context the issue forms ask for on its own: the agent-manager version, the operating system, the tmux version, and the CLI the calling session runs with the version it reports.
A call without preview_id composes the issue and returns a preview: the title, the body exactly as it would be posted, how filing would go, and an id for that exact combination. Nothing is posted by that call. The agent shows the preview to the user and calls again with preview_id set to that id once they approve. The id covers the issue, the route and the GitHub account, so an approval that was given for a preview posting nothing cannot file once gh appears or logs in as somebody else: filing is refused and the agent previews again. One approval posts one issue: a repeated call with the same id, as after a timed-out tool call, returns the issue already filed. Filing goes through the gh CLI as the user's own GitHub account when gh is installed and logged in, and the result is the new issue's URL. Without gh, the result is the repository's issue form prefilled from the preview, field by field, for the user to open in a browser; the preview says which route applies and why. The body is public, so secrets and private paths stay out of it.
Press ctrl+r on a session to open a full-screen review of its repo: changed files with +/− counts on the left, the whole file on the right with syntax highlighting and changed lines tinted, so every edit reads in full context. The diff refreshes as the agent keeps editing.
The footer offers ctrl+r review mode on every agent row, filled like quick prompt mode, with the reminder tell your agent "set review mode" beside it. Tell your agent what you want to review in Agent Manager. Your agent can declare the repository or worktree, target and scope together, so the panel opens on those changes when you press ctrl+r, without you configuring each picker.
| Key | Action |
|---|---|
↑↓ / jk, ctrl+d / ctrl+u, pgup / pgdn |
Scroll the file |
g / G |
Jump to top / bottom |
J / K (or tab / shift+tab) |
Next / previous file |
n / N |
Jump between changes |
u |
Toggle unified and side-by-side |
s |
Cycle the scope: uncommitted, vs target, commit, staged. The session's review reopens in the scope picked last, after a restart too; a session with none opens in the review scope picked in Settings |
[ / ] |
In the commit scope, step to the older / newer commit |
{ / } |
In the commit scope, jump to the oldest commit / HEAD |
L |
In the commit scope, pick the commit to review (type to filter) |
r |
Pick the repo when the session's directory holds several (type to filter) |
b |
Switch review to another of the repo's worktrees, listed by branch |
B |
Pick the target (merge-into branch) the "vs target" scope compares against |
space |
Mark a file reviewed in the current scope |
f |
Show code files only, hiding images, compiled assets and lock files from the list; press again to show them |
c / d |
Write or drop a draft; mark feedback from a sent round handled or open |
C |
Send the current drafts to the agent as one review prompt (enter or y confirms, esc cancels) |
o / F3 |
Open the current file in your editor |
Help binding (default ?) |
Review bindings only; esc returns to the review |
esc / q |
Close the review |
Each changeable value in the header wears its own key, so the scope, layout, repo, and target pills read as s, u, r, B legends at a glance.
Comments and reviewed-file marks are saved as you work and return after Agent Manager restarts. A reviewed mark belongs to the scope it was taken in: it records that you reviewed the exact diff that scope showed, so each scope keeps its own marks and cycling scopes leaves them untouched. C sends only the current drafts as one prompt and records them as the next numbered review round. Every sent comment stays inline as the session's review history, labelled with its review round and point number. Open comments keep the accent wash; handled comments settle into a subtle dark green wash, and d toggles the status locally.
Each point sent to the agent carries a stable comment id. After addressing it, an MCP-capable agent marks it handled with review_comment; an agent using shell commands runs agent-manager review-comment <comment-id>. Either can reopen it, with handled: false or --reopen. The status is stored immediately, so opening review shows the current state at once; a panel already open picks it up on its next refresh. The comment itself remains in place. The header names the latest review round and marks it changed when the scope or the code differs from what was sent. A comment whose original code can no longer be found is marked outdated instead of silently moving to an unrelated line.
In Review, local action keys take precedence over a conflicting Help binding. For example, if Help is bound to both b and H, b still opens the branch picker and H opens Help. The Review footer and key map show only the available Help keys.
Groups are paths (backend/api/auth) forming a tree of unlimited depth. Sessions can live at any node, including the root. Create subgroups inline with g, reorder both groups and sessions with K / J (or shift+↑↓; the order persists), fold a subtree with enter on its row, fold or unfold the whole tree in the active view with F, hide or restore empty groups visually with e, and edit a group's name, default path, worktree choice, base and environment profile with r. On a session, r renames it and tab cycles the tool. Quitting one CLI in a session's pane and starting another there moves the row onto that CLI on the next poll, with the status rules and the revive command that come with it. The move needs one answer: exactly one built-in CLI has to run the binary the pane is running, so a CLI whose process name is its runtime rather than itself (one installed as a node script, say) leaves the row where it is and tab sets it by hand.
Group archive and restore apply to the whole subtree, including sessions hidden by search or status filters. The archive card counts every session it touches, including those already archived. Restore counts archived sessions and leaves intentionally stopped active sessions stopped. Restoring a subgroup also reveals its ancestor groups without restoring their other sessions. Group kill/revive and X/V use the filtered list instead.
The archived view offers management and Restore actions. Revive, restart, kill, contextual creation, group folding and Fold All are inactive there. CLI/MCP archive can leave a pane running: Restore returns that row to active controls while keeping its current pane and conversation, then Kill stops it. Delete also removes the row and is not a substitute for Kill. Fold All (F) is available in the active view.
C adds an SSH connection: a name, a destination, user@host or an alias from ~/.ssh/config, and optionally the path of agent-manager there. The other machine must run Linux or macOS, since the calls run in its POSIX login shell; a Windows host is not supported. It needs agent-manager on its login shell's PATH, or at that path (absolute or under ~/), and a key this machine's ssh can use without a prompt; the manager never asks for a password and never touches your SSH config. Connect once by hand first (ssh user@host) so the host key is already known: the manager's ssh runs in batch mode and shows a host it has never seen as unreachable with "Host key verification failed".
The connection sits in the list after your own groups, in its own color with an ssh label, and the other machine's groups, agents and terminals nest under it. It folds like a group. Each poll refreshes every connection in the background, one call per host at a time, and a host whose refresh fails keeps its last rows with a note saying why (unreachable, agent-manager missing, agent-manager too old or agent-manager newer, otherwise error) and the full message in the detail pane, and is tried again after a pause that grows from two seconds to half a minute while it stays down. The first refresh starts a headless manager there (agent-manager serve --background) when none is running, so messages sent to its agents get delivered.
On a connection's rows:
enterandAattach over SSH in this terminal; detaching returns to the manager. A remote pane is never embedded.- Quick prompt mode types into a remote agent's pane as you, the way it does on this machine, or starts a new agent on the CLI, model, effort and profile the bar shows when a connection or remote group is selected.
nstarts one there too; the directory and the worktree default are the other machine's unless you set them. Topens a terminal there andgcreates a group there, under the selected one;xkills an agent or closes a terminal,vrevives,aanduarchive and restore.ddeletes an agent there the way it does here, its worktree included when clean, and asks first; on a terminal it closes it, likex.- On the connection row itself,
redits it anddremoves it. Removing asks first; its sessions keep running on that host.
Rename, move, deleting a group, restart, fork, review, the editor, copying a reply, reordering, marking idle, cancelling an after-turn end and kill all or revive all are refused on a remote row with a message naming the gap. A failed call shows the other machine's error. Nothing from a connection is written to this machine's store. See SSH connections for the protocol.
Each session's tmux pane is polled (default every 2s) to derive a status:
| Advanced | Compatible | Status | Meaning |
|---|---|---|---|
◐ |
* |
working |
The agent is busy on a turn |
◆ |
? |
waiting |
Blocked on you: a dialog, a permission ask, or a plain-text question. . marks it idle until the screen changes |
● |
+ |
finished |
Turn ended — an alert that clears to idle once you enter the session, or on . |
✕ |
x |
errored |
The tool reported an error |
○ |
. |
idle |
Nothing running |
✕ |
x |
dead |
The tmux session is gone |
◌ |
~ |
starting |
The pane is still launching |
Every row carries its mark, and each state has its own color from the active theme, so a glance down the rail tells you who needs you. The key map (?) lists the marks under "the mark on a session row".
In Compatible mode, starting rows animate with an ASCII spinner; ~ identifies the state in the details and group roster. Group rows use > when collapsed and v when expanded. Y marks a worktree branch or a conversation fork.
A session with messages from another agent waiting to be typed in wears @ in Compatible mode or ✉ in Advanced mode, with the count next to its name. The count clears when the manager delivers them.
A session that asked to be archived or killed once its turn ends wears ↓ or ■ (A or K in Compatible mode) next to its name until the manager does it, or until c cancels it.
A session stuck on the wrong mark is a rules question, and the rules are ours: they ship in the binary, so an upgrade is what moves them. Configuration has what to put in the issue and how to read the pane the poller reads.
w narrows the list to sessions that need attention (waiting, finished, errored). Press again to show every status. An ATTENTION badge sits over the list with the key that clears it, and the session counts follow the filter; folds open so matches are not hidden. The archived view (t) and hidden empty groups (e) label themselves the same way. The badges take whatever room the rail has: padded away from the entries on a tall terminal, tight against them on a short one, and yielding to the entries once the list is down to its last rows.
Each row carries its status and tool inline, and a folded group keeps a count per status so a collapsed subtree still tells you whether anything needs you. Selecting a session shows the tail of its pane on the right, which is how a waiting agent's actual question reaches you without attaching. A session with no window left, archived or killed, shows the snapshot taken when it still had one.
Detection matches per-tool regex rules against the visible pane, analyzes the newest turn to tell finished from waiting, and treats streaming output (content changing between polls) as working. A turn that ends without any turn-summary line still resolves: when a working pane goes quiet, the turn counts as finished, or waiting when it ends on a question. Work that outlives the turn which started it and reports back to the agent (background agents, dynamic workflows, and an MCP call Claude Code moved to the background) is matched by busy_line, so a turn-end summary keeps reading as working while that work runs. A background shell or monitor can run long after the agent is done with it, so a turn that leaves one running ends like any other. So does a turn whose summary folds different kinds into one N background tasks count, since that line no longer says which kinds are running. When the shell finishes and wakes the agent, the turn that follows reads working until it ends. A usage or rate-limit banner (limit_line) is errored, and so is a provider error opencode prints above the turn's summary. A footer the tool paints only while a turn runs (busy_footer) reads as working on its own, which is how an opencode turn that streams no marker into the transcript is told from a resting one, and a working marker that outlives that footer belongs to a turn that died, which is errored. Polling keeps running while you are inside a session, so statuses stay live. The selected session's pane tail renders in the preview panel, and moving the cursor fetches the preview immediately.
For Claude Code, built-in status detection reads hook events: sessions launch with a generated --settings file whose hooks write the lifecycle state (working, waiting, finished, idle) to a per-session status file that the poller reads first. A StopFailure of any error type (a usage limit, a signed-out or unpaid account, a failed request) writes errored, which holds over the failed turn's own summary until the next prompt or a pane that shows the agent working or waiting. Pane rules still refine it — hooks cannot see a plain-text question, an Esc interrupt, or an error line, so a matching pane verdict upgrades the hook status — and they take over fully as fallback when the hook file is missing or stale.
When a session's status flips to waiting or errored, the manager fires one notification with the session name, tool, and state — once per transition, never per poll — so you can look away from the list without missing an agent that needs you. The title names the session, its directory, the branch when the manager made a worktree for it, and the tool (deploy · api · am/fix-login · codex), so two sessions sharing a name read apart. The banner quotes what the session's row shows: a waiting one carries the question the agent is asking (◆ Waiting: Do you want to create probe.txt?), a finished one the prompt it was given (● Finished: write the release notes), so you can tell from the banner alone which task ended and what the agent needs. The line is cut at 120 characters, and the state word stands alone when the row has nothing to quote; errored banners keep the state word. This is tool-neutral: every configured CLI reaches the same notification path after the manager classifies its status, and the quote is the same one the session list shows. Clicking a notification puts the cursor on the session it named, and brings the terminal running the manager to the front on macOS and on Linux under X11. On macOS the banner is the manager's own: the first time one fires, macOS asks whether Agent Manager may send notifications, and from then on every banner carries the manager's name and icon, with waiting, finished, and errored getting the Funk, Hero, and Basso sounds. The manager keeps a small app bundle of itself under ~/Library/Application Support/agent-manager for this and refreshes it after an upgrade. Should that bundle ever fail to build, the older AppleScript notification still fires so the ping is not lost; macOS attributes that one to Script Editor, and clicking it opens Script Editor. Linux sends matching standard sound, icon, category, and urgency hints through notify-send; the desktop notification server uses the capabilities it supports and safely ignores the rest. Acting on a click needs a notify-send new enough to report actions, which is libnotify 0.7.9 and later; with an older one the banner still appears and the click does nothing. Where it is supported, the click raises the terminal window on X11 (through xdotool or wmctrl when installed) while Wayland compositors leave the window where it is. Under WSL the banner is a native Windows toast posted through PowerShell, which replaces the bell there; Windows attributes a toast to whoever posted it, so that click does not reach the manager and carrying it across is left for a follow-up. Inside Ghostty or cmux the state travels as an OSC 777 escape to the drawing terminal, which owns its presentation and sound and attributes it to the right window and workspace. Because that escape rides the terminal connection, it also reaches you when the manager runs on a remote host over SSH. A headless box without a desktop falls back to the terminal bell. Settings (s) has a notifications row that silences them (on by default) and a notify on finish row that adds finished transitions (off by default).
To send notifications somewhere else as well, such as your phone, a chat, or a script, set a shell command with agent-manager settings set notify_command '<command>', and clear it with agent-manager settings set notify_command ''. It has no row in Settings, so agent-manager settings get notify_command is where to read it back. A running manager uses the new value from its next notification. The manager runs it through sh -c for every notification it fires, after the native banner and in addition to it. The notifications and notify on finish rows gate it the same way, and with several managers open it runs once per transition, from the manager that posts the banner. The command gets the event in its environment:
| Variable | Value |
|---|---|
AM_NOTIFY_KIND |
waiting, finished, or errored |
AM_SESSION_ID |
the session's id |
AM_SESSION_NAME |
the session's name |
AM_TOOL |
the CLI it runs |
AM_CWD |
its working directory |
AM_BRANCH |
its branch, when the manager made it a worktree; empty otherwise |
AM_TITLE |
the banner's title |
AM_BODY |
the banner's text |
The values come from the session and the agent, so quote them ("$AM_BODY") and they stay data. Single quotes around the whole command keep your shell from expanding the variables when you set it. For example, to get a push notification through ntfy:
agent-manager settings set notify_command 'curl -fsS -H "Title: $AM_TITLE" -H "Tags: $AM_NOTIFY_KIND" -d "$AM_BODY" https://ntfy.sh/your-private-topic'On Windows the manager runs the command through PowerShell instead, the shell its panes run, so the variables read as $env:AM_BODY and the command is PowerShell. Set it from PowerShell 7.3 or later: Windows PowerShell 5.1 drops the inner double quotes before agent-manager receives them.
agent-manager settings set notify_command 'curl.exe -fsS -H "Title: $env:AM_TITLE" -H "Tags: $env:AM_NOTIFY_KIND" -d "$env:AM_BODY" https://ntfy.sh/your-private-topic'A command that runs past 15 seconds is stopped. When one fails, exits non-zero, or is stopped, the time, the session, the error, and the start of what it printed go to notify-command.log in the manager's config directory (~/Library/Application Support/agent-manager on macOS, ~/.config/agent-manager on Linux, %AppData%\agent-manager on Windows), a file only you can read, and nothing interrupts the manager.
The command runs as you, with everything your account can reach, so give it the same trust as your shell rc file. Nothing on screen lists it, so before the manager runs a command it has not shown you, it posts a New notify command banner with the command itself. That happens once for each new command, the first one you set included, and a command that changed without your knowing shows up there.
The header shows a fleet summary: per-status session counts, plus agents total usage: cpu N% · ram M% · X GB for every live agent's full process tree (shell, agent, and children). CPU is that tree's CPU time over the last poll as a share of total machine capacity (same 0–100% unit as the computer gauge). RAM is resident set as a share of installed memory, with absolute size beside it. The selected session's detail line uses the same scale for that session alone.
The Computer block in the sessions panel shows machine gauges:
- CPU: whole-machine utilization (0-100%)
- Memory: used/total. On macOS this matches Activity Monitor's Memory Used (resident RAM minus free, speculative, and reclaimable file cache). On Linux it is
Total - MemAvailable, so file cache is not counted as used. - Swap: used/total of the current swap allocation (
used/total * 100). On macOS the swap file grows under pressure, so the denominator is the live size fromvm.swapusage, not a fixed partition. - Disk: fill of the root filesystem (used / (used + available)), with free space from the kernel's available figure
- Battery: charge percent, with
chargingwhile plugged in and filling. On macOS it is the figure the menu bar shows. It stays hidden when the machine has no battery. Peripheral batteries that report no charge (a wireless mouse on Linux) are ignored. - Network: up/down rates on real NICs only (loopback, utun, bridges, and similar virtual interfaces are excluded)
- Temperature:
cpu,gpuandsocreadings in °C, each the hottest sensor in its category, sampled every 5s. Apple Silicon draws no CPU/GPU line, so its dies report as onesocfigure. A reading appears when the machine exposes that sensor.
On Windows under WSL2, agent-manager runs inside the Linux guest, whose /proc describes the VM rather than the machine. There the CPU, memory, disk, and agent-percentage figures come from the Windows host instead, sampled through PowerShell interop every 30 seconds; swap, network, and temperatures remain the guest's own. If interop is unavailable, the guest numbers show unchanged.
s opens Settings, where ↑↓ or the mouse wheel move between fields and ←→ change the focused one. Short windows scroll to keep the focused field and key hints visible. With the mouse, click settings in the footer, or open the root row’s menu ([…]) and choose Settings. A click on a row moves to it, and a second click changes it or runs it. docs, saved prompts and the symbols preview act on the first click. save and close sits in the footer with the other keys, and a click on it saves.
symbols switches between Advanced (the default) and Compatible. Compatible uses ASCII marks for session status, loading, inbox, drag handles, group folds, terminal rows, worktree or fork indicators, prompt/reply prefixes, search, dialog titles and selections, notices, pending actions, and diff outcomes. Compatible also spells Enter and Backspace as enter and backspace in key hints and draws the top edge as a plain line. It also uses flat pane edges, square card corners, plain choice arrows, thin rules, and whole-cell meters. Advanced uses geometric symbols and a Braille spinner. The row previews the selected marks; change it with ←→ or a click, then press ↵ or esc, or click save and close in the footer. The choice takes effect immediately and is restored on the next run. Fonts are not detected automatically. Compatible retains the thin box-drawing lines and full block checked in the font audit. Arrow-key hints read up/down or left/right, overflow counts name rows above or below, and directional indicators use simple marks. Literal user text and agent output are unaffected.
An installation without an explicit symbols choice follows the release’s default. Saving other Settings does not pin that default; explicitly choosing either mode preserves it across later default changes.
Eighteen palettes ship. Eleven dark: classic, solarized dark, catppuccin mocha, tokyo night, gruvbox dark, nord, dracula, rosé pine, monochrome, kanagawa wave, and onedark. Seven light: solarized light, catppuccin latte, tokyo night day, gruvbox light, rosé pine dawn, paper, and kanagawa lotus. The swatch strip beside the name previews the palette, and the theme applies as you step through it, so the picker is a live preview of the whole UI. The manager also sets the terminal's own text and background colors to the palette's, so the window has no seam against it and an agent's plain text reads on it, and restores the terminal's colors on exit. Your pick is saved with the rest of the state and restored on the next run.
theme follows OS resolves the palette at startup from the environment's light/dark preference: the OS setting on macOS and Linux desktops, and the terminal's own background elsewhere, including over SSH. A theme already on the detected side stays; only a mismatch switches. While the manager runs, it also switches when the terminal reports a light/dark change (mode 2031), locally, over SSH, and under tmux 3.7 or later; a flip made while an attached session or editor had the screen is picked up when the manager comes back. A terminal without those reports keeps the palette picked at startup. tmux 3.6 does not pass the change on, because it works the scheme out from the background color, which the manager sets itself. Native Windows keeps the startup palette too: the console delivers the report one key at a time, so the manager does not ask for it there. A palette that ships in both a dark and a light variant switches to its other half: solarized dark and solarized light, catppuccin mocha and catppuccin latte, tokyo night and tokyo night day, gruvbox dark and gruvbox light, rosé pine and rosé pine dawn, kanagawa wave and kanagawa lotus. Any other palette switches to classic or solarized light. Your manual pick is kept separately, so turning the toggle off returns to it, and stepping the theme picker by hand turns the toggle off. Agent panes render on the theme's own backdrop and text color, and the pane declares both to the agent inside it, so an agent that auto-detects its palette resolves to the same side the manager is drawing. An agent that asks the terminal for its colors gets them from tmux 3.2 on, and every version hands it the same pair in COLORFGBG. A session already running keeps the palette it resolved at launch until it is restarted.
background picks what fills the cells behind the UI. theme, the default, gives every cell that would otherwise show the terminal's own colors the palette's background and text color, so the colors hold even on a terminal that ignores the color request. Cells with colors of their own, agent output included, keep them. terminal leaves those cells on the terminal's own colors, for a translucent or blurred window, where painted cells would read as a solid block inside the see-through padding. The row applies as you step it.
agent-manager export [file] writes settings, keybindings, the editor, presets,
groups and SSH connections as JSON. agent-manager import [file] merges that
configuration by matching keys and names. Both accept --settings, --presets,
--groups and --connections. Exports may contain secrets. See
Export and import for scope, conflict
behavior and file handling.
agent-manager settings reads and changes the same settings the modal does, without opening the manager, for a setup script, a dotfiles repo, or a manager on a remote box. settings list prints every key with its current value, the Settings row it belongs to, and the values it takes. settings get <key> prints one value, the default when none is stored, and settings set <key> <value> writes one. A value is checked against the choices that row steps through (on or off, a theme name, a CLI name), and a key the manager does not know, or a value outside its choices, is refused with the choices named. An empty default_tool means the first CLI the picker offers, and an empty editor means the editor found on PATH or in $VISUAL and $EDITOR. The keybinding tables keep their picker. --json prints records instead of lines.
agent-manager settings set theme "tokyo night"
agent-manager settings set notifications off
agent-manager settings get list_densityA running manager shows the change the next time Settings (s) is opened and uses it from then on, or from its next start. Keys it reads each time it uses them, such as notifications, coordination and notify_command, apply at once. notify_command is the one key with no Settings row. A command does not fit a one-line field, so it is set from the shell alone (see Notifications).
agent-manager update brings the installed binary to the newest release from a shell, without opening the manager. An install owned by a package manager (Homebrew, mise, Arch) hands the terminal to that manager's upgrade command; a direct install downloads the newest release, verifies its checksum, and swaps the binary in place. --json prints the outcome as a record instead of a sentence.
Settings (s) has a row that opens the bug report form and one that opens the feature request form in your browser. Over SSH they print the link on the plain terminal instead, the same way a clicked link does. From a shell, agent-manager issue "<title>" --body "<text>" drafts a bug report and agent-manager feature "<title>" --body "<text>" a feature request; both print a preview with the context the forms ask for (version, OS, tmux version, and the CLI of the session the command runs in) and post nothing. Rerun with --confirm <preview-id>, passing the id the preview printed, to file it: through gh as your own account when it is installed and logged in, otherwise the command prints the prefilled issue form URL to open. The id is refused once anything it covers has changed, so what gets filed is what you read. --json prints the preview or the filed result as a record. Agents reach the same flow through the report_issue MCP tool.
![Mouse demo with the geometric marks used by Advanced mode: the wheel moves the cursor, clicks focus and leave sessions, the ⠿ handle drags rows, and […] opens row actions](/wainmann/agent-manager/raw/main/docs/demo-mouse.gif)









