---
title: "Overview"
description: "What agent-manager is, what a session is, and where everything lives."
canonical: "https://agent-manager.dev/docs/"
last-updated: "2026-08-31"
section: "Documentation"
source: "agent-manager"
---

# Overview

agent-manager is a Go TUI that runs on top of tmux. Every agent you start is a real tmux session, so the manager is a window onto them rather than something they live inside. Quit it and they keep working.

![The session list: twenty-odd agent sessions grouped under backend, its api subgroup, frontend and infra, each with a colour-coded live status, a real Claude Code transcript in the preview on the right, and machine gauges at the bottom left.](/assets/screenshot-sessions.png)

_Twenty-three sessions, four projects, one nested subgroup. The preview is a real Claude Code pane._

## The first run

There is no config to write and no daemon to start. Install it, then:

```bash
agent-manager
```

A config file appears at `~/.config/agent-manager/config.toml` on Linux or `~/Library/Application Support/agent-manager/config.toml` on macOS, already holding working blocks for Claude Code, OpenCode, Codex, Grok Build, Gemini CLI, Pi, Command Code and Hermes Agent.

| Key | What it does |
| --- | --- |
| n | New session: name, tool, directory, an optional starting prompt, and a group. |
| g | New group. |
| space | Prompt the selected agent, or spawn one in the selected group. |
| ? | Every key, without leaving the app. |

## Where the sessions live

Agent sessions run on a private tmux server named `agentmgr`, in the `am_*` namespace, 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:

```bash
tmux -L agentmgr ls
tmux -L agentmgr attach -t am_<id>
```

> **Inside a session** `ctrl+q` detaches back to the manager when the terminal leaves it available; `ctrl+\` is an alternate. `ctrl+r` opens review and `F3` opens the session's directory in your editor. These bindings are scoped to managed sessions, so they pass straight through everywhere else.

## Where to go next

| Page | What it covers |
| --- | --- |
| [Install](/docs/install/) | Homebrew, the install script, the AUR, mise, Go, or a binary. |
| [Status](/docs/status/) | Why a row is orange, and where that verdict comes from. |
| [Quick prompt](/docs/prompt/) | Answering a blocked agent without attaching to it. |
| [Review mode](/docs/review/) | Whole-file diffs whose line comments go back to the agent. |
| [Configuration](/docs/config/) | Teaching it a CLI it has never heard of. |