---
title: "Sessions and groups"
description: "Every agent is a real tmux session: killing, reviving on the same conversation, the group tree, archiving, and self-naming."
canonical: "https://agent-manager.dev/docs/sessions/"
last-updated: "2026-09-14"
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.

## 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; the quick prompt's `alt+w` does the same when you spawn into a group. Settings sets the default both start from.

The worktree lives at `<repo>-worktrees/<name>` next to the repo, on a new branch `am/<name>`, based on the remote default branch when that resolves. A worktree that fails to create blocks the spawn instead of falling back to a shared directory. 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 carries its worktree and branch along. 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}
hermes --cli --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`). |

> **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. Both revive what they can and name the first failure rather than stopping.

## 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 and Pi ship fork commands.

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

## 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 and default path. |
| 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.