Codeman/docs/wiki/Quick-Start.md

# Quick Start

From an installed Codeman to a working agent, in about five minutes. If you have not
installed yet, start at [Installation](Installation).

## 1. Start the server

```bash
codeman web
```

It prints a URL, `http://localhost:3000` by default. Open it.

The server binds `127.0.0.1` only, so this URL works from the machine running it and
nowhere else. That is deliberate: Codeman starts agents with permission prompts skipped by
default, so anyone who can reach the dashboard can run code on this machine. Reaching it
from your phone is a separate, deliberate step covered in [Remote Access](Remote-Access).

To keep it alive after you close the terminal, use `codeman web -d` instead, or install it
as a service. See [Running As A Service](Running-As-A-Service).

## 2. Meet the welcome screen

With no sessions running you get the welcome screen:

- **Run buttons** for each agent CLI Codeman found on your PATH. If you expected one and it
  is missing, its binary is not visible to the server; see [Agent CLIs](Agent-CLIs).
- **A QR code**, if a password is set. Scanning it logs a phone in without typing anything.
- **Resume Conversation**, a list of past sessions, including Claude conversations started
  outside Codeman. Empty on a fresh install.
- **Search**, across sessions, events, and files.

You can click a Run button right now and get a working agent in your current case. The rest
of this page is the deliberate version.

## 3. Pick or create a case

A **case** is a named working directory that Codeman remembers. Every session runs inside
one. The case picker is in the bottom toolbar.

To make a new one, click **+** next to the picker. The Add Case dialog has three tabs:

| Tab               | Use it when                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Create New**    | Starting a fresh project. Creates `~/codeman-cases/<name>` and scaffolds a `CLAUDE.md` into it.                     |
| **Clone Repo**    | Working on an existing public repo. Paste the URL; Codeman preflights it as you type, offers the repo's real branches and tags, and fills in the case name. |
| **Link Existing** | The code is already on disk. Point at the folder, with **Browse** if you would rather click than type.               |

The gear next to the picker holds two per-case toggles: **Agent Teams** and
**1M Opus Context**. Both are off by default and both are safe to ignore for now.

**Create New** also has a checkbox for running the case inside a Docker container, and a
**Remote** panel for running it over SSH on another machine. Those are
[Docker Cases](Docker-Cases) and [Remote SSH Sessions](Remote-SSH-Sessions); skip them for
your first session.

## 4. Pick a run mode and hit Run

The **Run** button starts an agent in the selected case. The arrow next to it picks which
one:

| Mode                 | What starts                                                    |
| -------------------- | -------------------------------------------------------------- |
| **Claude Code**      | The default, and the mode every Codeman feature supports.       |
| **OpenCode**         |                                                                 |
| **Codex**            | OpenAI's CLI.                                                   |
| **Gemini**           | Enterprise only since Google's consumer cutover.                |
| **Antigravity**      | Google's successor to the consumer Gemini CLI.                  |
| **Pi**               | No permission prompts and no sandbox by design.                 |
| **Terminal / Shell** | A plain shell, no agent. Also the **Run Shell** button.          |

The dropdown also lists any saved dashboard URLs ([Web Tabs](Web-Tabs)) and your recent
sessions. Those do not change the run mode: Run always means "start an agent".

Click **Run**. A tab appears, and Codeman spawns the CLI on a real PTY inside a tmux
session and streams it to your browser.

The number spinner beside the button starts several sessions at once, up to 20. Useful for
fanning the same case out across parallel workers; unnecessary for a first run.

## 5. Talk to the agent

Click into the terminal and type. It is a real terminal (xterm.js over a real PTY), so full
TUIs render properly and everything the CLI supports works, slash commands included.

| Key                          | Effect                                        |
| ---------------------------- | --------------------------------------------- |
| `Enter`                      | Send.                                          |
| `Shift+Enter` / `Ctrl+Enter` | Newline without sending.                       |
| `Ctrl+C`                     | Copy if text is selected, otherwise interrupt. |
| `Ctrl+Shift+V`               | Voice input.                                   |

You can also paste or drag an image straight into the session, and register external files
as attachments. See [Working With Files](Working-With-Files) and
[Input And Voice](Input-And-Voice).

Input is delivered **exactly once**, even if your connection drops mid-prompt. A dropped
link never loses a prompt and never sends it twice.

## 6. Read the tab

The tab tells you what the session is doing without opening it:

| Signal                | Meaning                                                    |
| --------------------- | ---------------------------------------------------------- |
| Green dot             | Alive and idle.                                             |
| Pulsing green dot     | Working on a turn.                                          |
| Yellow, blinking      | Waiting for you to type something.                          |
| Red, blinking         | A question or permission prompt is blocking the agent.      |

Full tour in [The Dashboard](The-Dashboard). If you want a phone notification when an agent
needs you, that is [Notifications And Approvals](Notifications-And-Approvals).

## 7. Leave, and come back

Close the browser tab. Close the laptop. The agent keeps running, because it lives in tmux
and not in your browser.

Reopen the dashboard and the session is still there with its scrollback intact. First load
of a session pulls the full tmux scrollback, so you get the history, not just what arrived
after you reconnected.

This also survives restarting the Codeman server itself. What does not survive is killing
the tmux server or rebooting the machine.

## 8. Stop things

| To do this                | Do that                                                             |
| ------------------------- | ------------------------------------------------------------------- |
| Interrupt the current turn | `Ctrl+C` with nothing selected, or the **Stop** button.            |
| Close one session          | `Ctrl+W`, or the tab's close control.                              |
| Stop the server, keep agents | `codeman web --stop`. The tmux sessions stay alive.              |
| Stop everything            | `tmux -L codeman kill-server`.                                     |

If you are working *inside* a Codeman-managed session (`echo $CODEMAN_MUX` prints `1`),
never run `tmux kill-session` or `pkill claude` by hand. You will kill the session you are
sitting in, along with its siblings.

## Where to go next

**Make it run without you.** [Keeping Agents Running](Keeping-Agents-Running) covers idle
detection, respawn cycling, and auto-resume when a subscription limit resets. That is the
feature Codeman exists for.

**Get it on your phone.** [Remote Access](Remote-Access), then
[Mobile Guide](Mobile-Guide).

**Understand what you just used.** [Core Concepts](Core-Concepts) explains cases, sessions,
run modes, and what state lives where.

**Automate it.** [Cron Jobs](Cron-Jobs) for scheduled work,
[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for agents that spawn and
supervise other agents.