Quick Start

Quick Start

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

1. Start the server

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.

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.

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.
• 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 and 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) 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 and 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. If you want a phone notification when an agent needs you, that is 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 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, then Mobile Guide.

Understand what you just used. Core Concepts explains cases, sessions, run modes, and what state lives where.

Automate it. Cron Jobs for scheduled work, Driving Codeman From An Agent for agents that spawn and supervise other agents.