Codeman maintainer
bd286bf502
The wiki was written for seven run modes and never received Grok Build, DeepSeek Harness or OMP. They now appear everywhere the others do: the modes table and per-CLI notes, install commands, environment prefixes, the Quick Start table, the requirements rows, the vocabulary, and every "seven modes" count. The 1.27 to 1.29.0 changes land on the pages that own them: attaching a case to an existing container, multi-case adoption and the copy-a-case picker (Docker Cases); file reads over ssh in remote cases and what stays unavailable (Remote SSH Sessions, Working With Files, Security); single-page app routing, frame recovery, localhost links as tabs and the egress guard (Web Tabs); DeepSeek as the one non-Claude mode with real stop/blocked signals and Approvals items, Codex's own work detection, last-response, the model-endpoint routes and refreshed counts (HTTP API, Driving From An Agent, Hooks, Notifications, Keeping Agents Running, Core Concepts); Shift+drag, right-click copy, Auto Copy, the Ctrl+Z guard, font weight, the vertical rail and its activity sort (Keyboard Shortcuts, Input And Voice, The Dashboard, Settings Reference); the 600px phone cutoff, Codex shift arrows and iPhone Duo (Mobile Guide); the Docker Compose route and its update rule (Installation, Running As A Service); four new symptom entries and a "which CLIs" question (Troubleshooting, FAQ). Custom model endpoints are deliberately left to #430, which adds that page and edits Agent CLIs, Settings Reference and the sidebar; these edits stay out of the regions #430, #428 and #376 touch, and all three still merge cleanly on top. Both READMEs: the web-tab menu entry is labelled "Add URL" in the UI, not "Add dashboard". Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
8.1 KiB
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. |
| Grok Build | xAI's CLI. |
| DeepSeek Harness | Needs a terminal profile; the menu offers to install one. |
| OMP | Oh My Pi, configured entirely through its own ~/.omp. |
| 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.