---
title: "Sessions and groups"
description: "Every agent is a real tmux session: its model, effort and profile, killing, reviving on the same conversation, the group tree, archiving, and self-naming."
canonical: "https://agent-manager.dev/docs/sessions/"
last-updated: "2026-10-07"
section: "Documentation"
source: "agent-manager"
---

# Sessions and groups

Every agent is a real tmux session with its own directory, command and environment. Quit the manager and they keep working; close the laptop lid and they are still there.

## Model, effort and profile

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, asked 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, whatever you set up in that CLI. Each CLI remembers the model, effort and profile you last picked for it, and the next session on that CLI starts there. The model list filters as you type, your last picks come first, and only a listed model can be picked. The effort row offers the levels the chosen model takes. The choice is saved on the session, so restart (`R`), revive (`v`) 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 | · |
| Oh My Pi | `omp --mode rpc` | yes | per model | · |
| Muse Code | `muse serve` | yes | per model | · |
| OpenCode | `opencode serve` | 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 | not asked yet | not supported | not supported | · |
| Command Code | nothing a program can ask | not supported | not supported | · |

A row the CLI cannot fill reads "not supported". OpenCode and Gemini CLI take no effort when they launch. 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. When a CLI fails to answer, 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. Answers are kept for six hours under `catalogs` in the config directory, and an upgraded CLI is asked again at once.

## Own git worktree per session

Parallel agents on the same repo can each get a private checkout. The `n` form has a `worktree` field between directory and prompt, and quick prompt mode's `ctrl+t` does the same when you spawn into a group. Both start on the tool and the worktree choice you picked last time, for as long as the manager runs, and Settings sets what they start from before that.

The worktree lives at `<repo>-worktrees/<name>` next to the repo, on a new branch `am/<name>`. It starts from the branch the repo's work merges into: the default branch of an `upstream` remote when the repo has one, then origin's default branch, then a local `main` or `master`, and finally `HEAD`. A group can name the starting point itself with the `base` row of the `g` form or its edit card, and a group left on `auto` takes its parent's. While the form or quick prompt mode is set to spawn a worktree, the manager fetches that one branch from its remote, at most once a minute for the same directory, and the `fetch on spawn` row in Settings turns that off. A worktree that fails to create blocks the spawn with an error. A path that is not a git repo cannot hold one, so the field reads unavailable and the session launches there as a plain session.

Renaming a session renames its branch to `am/<new name>` and keeps the worktree directory at the path it was made at, so the running agent's working path stays valid. Deleting a session removes a clean worktree and its branch; a dirty one is left on disk with its path shown. Killing, archiving and reviving never touch the worktree.

## Terminal tabs

`T` opens a shell tab: a session like any other, 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. A nested shell is named after the session it hangs under, `terminal-review-done` rather than a generated id. 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 or onto a group.

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. Enter the session to type there.

## Killing without losing the row

`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.

## Reviving the same conversation

`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`:

`resume_by_id_command`

```
claude --resume {id}
codex resume {id}
opencode --session {id}
grok --resume {id}
gemini --resume {id}
pi --session {id}
cmd --session {id}
hermes --cli --resume {id}
muse resume {id}
agy --conversation {id}
omp --resume {id}
```

The id arrives one of two ways:

| Field | How the id is obtained |
| --- | --- |
| session_id_flag | The tool launches under an id the manager mints. |
| session_store | The tool mints its own, and a capturer reads it back (`codex`, `opencode`, `gemini`, `hermes`, `command-code`, `muse`, `antigravity`, `omp`). |

> **Without an id** Revive falls back to `revive_command` (`claude --continue`), which resumes the 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 everything dead under it, and `V` revives everything dead in view. Each asks to confirm first when that is more than one session. Both revive what they can, carry on past a failure, and name the first one.

## Forking a conversation

`f` continues the conversation under the cursor in a second session: name the fork, and it starts in the same group and directory on a copy of the history, so one line of thought becomes two. It runs the tool's `fork_command`, which references the source through `{id}` or `{session_file}`, so a fork needs both that command and a captured conversation id; a session without one, or a shell, says so instead of forking. Claude Code, OpenCode, Codex, Grok Build, Gemini CLI, Pi, Command Code and Muse Code ship fork commands. Hermes Agent, Antigravity CLI and Oh My Pi have no fork. Muse forks only from inside the running source, so `f` types `/fork` into that session and opens the fork in a new pane. The source has to be at rest with nothing typed at its prompt.

## Restarting on an empty context

`R` keeps the row and drops the context: same name, group, tool and directory, launched on a conversation the agent has never seen. It is what a session that has piled up context you are done with wants, where reviving would spend the budget re-reading history. It asks to confirm first and works on a live session too, ending the running agent before the fresh one starts. The old conversation is retired rather than resumed, left on disk while the row stops pointing at it, and the row only changes hands once the new agent is up, so a launch that cannot start leaves the session on the conversation it had.

## Full screen

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 machine meters condense to one line above the key legend, and `→` on a row focuses that session across the whole body. While any message is left, the key legend leads with `messages`, and a click on it opens them. The same keys return the layout to split, and the choice persists like the split ratio.

![Animated demo: Settings swaps the sessions layout to full screen, the list takes the whole terminal with the computer stats on its foot line, and a session is focused full screen then left.](/assets/demo-fullscreen.gif)

_Fig. 1sessions layout · full screen_

The **list density** row picks the rows' rhythm in either layout. Compact keeps a session to one line with the agent's last message riding beside its name. Comfortable unfolds each session to three lines: the name, your last message behind a `❯`, and the agent's last message under it.

![Animated demo: the same full-screen list at the comfortable density, every session on three lines with its task and the agent's last message under the name.](/assets/demo-fullscreen-comfortable.gif)

_Fig. 2full screen · comfortable density_

## Groups are a tree

Groups are paths like `backend/api/auth`, forming a tree of unlimited depth, and sessions live at any node including the root.

| Key | Action |
| --- | --- |
| g | Create a subgroup inline. |
| enter | Fold a subtree. `F` folds or unfolds everything. |
| e | Hide or restore empty groups. |
| r | Edit a group's name, default path and worktree base. |
| K / J | Reorder sessions among their siblings, or whole groups among theirs. The order persists. |
| m | Move a session to a group, a terminal into a session, or a group under another group. |
| a / u | Archive / restore a session or group. Archive kills the process and keeps the last preview; restore resumes it. Restoring un-archives whichever ancestors it needs. |
| t | Toggle the archived view. |

## Sessions name themselves

A session spawned without a name gets a placeholder like `claude-a1b2`, and its first prompt opens by asking the agent to run `agent-manager rename` once, with a short name for the broad feature it is working on rather than a single subtask. The directive also tells the agent not to rename again unless you ask.

When the first prompt cannot carry the directive, because it is a `/slash` command or there is no prompt at all, the manager sends it as its own message once the tool's input box appears. The subcommand drops the name into a per-session file, and the manager picks it up on the next poll.

> **Names you set are kept** A session you named yourself is never renamed by its agent. The first prompt only notes that `agent-manager rename` is available later if you ask for it.