---
title: "First-run setup"
description: "The first launch picks the agents, the layout, the density and the theme, walks the main keys, and can import conversations the CLIs already saved."
canonical: "https://agent-manager.dev/docs/setup/"
last-updated: "2026-11-01"
section: "Documentation"
language: "en"
source: "agent-manager"
---

# First-run setup

The first launch, when no version has been stored yet, opens a setup instead of the list. It picks the agents you use, the layout, the density and the theme, walks the keys, and can bring in conversations the CLIs already saved. There is still no config file to write and no daemon to start.

## When it opens

A later launch opens the list. The first launch after an update opens the what's-new notice, as before. Settings (`s`) has a `first-run setup` row, labelled walk through it again, that opens the same setup any time.

`enter` moves forward. On the welcome step it starts the setup, and on the last step it imports and starts when an import is ready. `backspace` or `shift+tab` goes back after the first step. `esc` asks before leaving. What you set so far stays, and the same Settings row brings the setup back. A click and the wheel work on every step.

## The choices

Four steps save as you make them, into the same Settings rows you can change later. The tour after them does not save anything.

| Step | What you pick |
| --- | --- |
| Agents | Which CLIs the new-session form and quick prompt mode offer. Agents found on `PATH` start checked, until you change one. At least one stays checked. |
| Layout | `Split` keeps the list beside a live view. `Full screen` gives the list the whole screen. |
| Density | `Compact` is one line per agent. `Comfortable` puts the status on its own line. |
| Theme | `Follow the OS` (`space` toggles it) plus the palettes. Picking a palette turns follow-OS off. The screen previews the palette as you move. |

## The key tour

The next steps name the keys as they are bound now, and act them out. A key the tables leave unbound is left off its line. When the `←→` step in and out pair is off, or those keys are unbound, the tour shows `enter` to focus a session and the detach key to come back.

| Step | What it shows |
| --- | --- |
| Quick prompt | On a group, type the task and start the agent. It also names the new-session form and a new group. |
| Sessions | Answer the selected agent, focus it and type, then come back to the list. |
| Review | Open the agent's diff, comment on a line, and send the comments back. |
| Orchestrate | One agent can open more agents, sort them into groups, and keep them in step. The tour acts out asking one to rebuild checkout and split it across agents. |
| Places | Settings holds every choice, including this setup. Messages holds news and tips. `?` is every key, and it searches. |

## Past conversations

The last step is optional. It asks an agent to read the conversations your CLIs saved on this machine and add each one to the list, ready to pick up. It changes nothing in those CLIs, and it skips a conversation the list already holds.

Check the CLIs to read. The window starts at 7 days, and `←→` steps it through 7, 14 and 30. The runner is a CLI that is both checked and installed. With no agent CLI on `PATH`, the step says there is nothing to bring in yet. `enter` on this step imports and starts only when a runner is ready. Otherwise it asks you to check a CLI, or to press `esc` to leave.

Each conversation becomes a session with `agent-manager spawn`, in the directory it was saved in, on that conversation's id, with a kebab-case name. The prompt and the worktree are left unset, so the agent is not sent a task and the conversation stays in the directory it was saved in.

```bash
agent-manager spawn --tool <cli> --directory <dir> --resume <id> --name <name>
```

[Sessions](/docs/sessions/#resume) has the rules for `--resume`.

## Running it again

Open Settings and press `enter` on `first-run setup`. The choices you already saved are where you left them. Leaving with `esc` keeps them too.