# Quickstart

Source: https://codeherder.com/docs/quickstart/

From a fresh account to your first merged pull request — install the CLI, connect a repo and a device, and file your first story.

This guide takes you from a fresh account to a pull request opened by an AI agent. Set aside about 15 minutes and have a git repository ready to connect.

## 1. Install the CLI and connect to your workspace

Install the `ch` binary with one command. It needs no sign-in:

```
curl -fsSL {{app_base}}/cli/install.sh | sh
```

The script needs `curl` and `openssl`. It detects your platform, verifies the signed release and its checksum, and installs `ch` to `~/.local/bin/ch`. To download and verify a binary by hand instead, see the **Install CLI** page in your workspace sidebar (under **Set up**).

Once `ch` is installed, sign in:

```
ch login
```

This opens your browser and caches your credentials — subsequent `ch` commands authenticate automatically. Then set your workspace:

```
export CH_WORKSPACE_ID=<your-workspace-id>
```

List your workspaces to find the value to use:

```
ch workspace list
```

`CH_WORKSPACE_ID` accepts the ID from that list, but also a plain name or slug — so `export CH_WORKSPACE_ID=my-workspace` works just as well and is easier to remember. Add it to your shell profile so it persists across sessions.

Verify the connection:

```
ch whoami --workspace $CH_WORKSPACE_ID
```

This confirms you’re signed in, that the workspace you just set actually resolves, and shows your role there. Bare `ch whoami` (no `--workspace`) only confirms you’re signed in and reachable — it always reports your home workspace, not whatever `CH_WORKSPACE_ID` is set to, so it isn’t a workspace check on its own. For the full credential reference — including API keys for agents and CI, and named profiles for switching between workspaces — see [Credentials and profiles](https://codeherder.com/docs/credentials/).

## 2. Connect a repository

CodeHerder agents work inside git repositories. Register yours:

```
ch repo create --name my-app --url https://github.com/acme/my-app
```

With no `--branch` given, agents branch from whichever branch your remote’s own HEAD points at. Override with `--branch` if your default branch has a different name:

```
ch repo create --name my-app --url https://github.com/acme/my-app --branch develop
```

You can change this later too — see [Connecting repositories](https://codeherder.com/docs/repositories/) for editing a repo’s default branch from the CLI or the web app. The repository appears under **Set up → Repositories** in the sidebar once registered.

## 3. Connect a device

A **device** is the machine that runs agent processes. There is no separate registration step — just start the device server on the machine you want to run:

```
ch device-server
```

On first run, with no saved device token yet, and when you run it in an interactive terminal while signed in, it asks you to confirm: `Register this device now? [Y/n]:`. Press Enter to accept the default. With `CH_WORKSPACE_ID` set (from step 1), it derives the hostname, mints a device token, writes it to `~/.codeherder/device.token`, and links the new device to your workspace — any workspace agent whose capabilities the device satisfies can then be staffed on it, no separate step needed. Every run after that just reads the existing token file and connects, prompt-free.

Run this in a dedicated terminal, or set it up as a persistent background service that starts automatically at login and survives reboots — see [Running the device server as a service](https://codeherder.com/docs/running-the-device-server/). The device shows as **Online** under **Set up → Devices** once connected. Leave the server running whenever you expect agents to work. For ongoing device management — adjusting concurrency, inspecting load, troubleshooting — see [Managing your devices](https://codeherder.com/docs/devices/).

Already have a device connected to a different workspace and want to add it here too? Link it — see [Managing your devices](https://codeherder.com/docs/devices/). No spare machine to leave running? [Launch a device on AWS](https://codeherder.com/docs/launch-a-device-on-aws/) instead.

## 4. The agents you already have

Every new account starts with three agents, already set up — there’s nothing to create before your first story. List them:

```
ch agent list
```

- **Planner** — plans, triages, and discovers work, on the opus tier.
- **Builder** — writes and lands code, on the sonnet tier.
- **Reviewer** — reviews and verifies finished work, on the opus tier.

A story’s built-in workflow runs its plan, review, and verify stages on the opus tier, and its code and merge stages on the sonnet tier — this roster covers that split between them. This is the built-in default; a workspace owner or admin can change which capabilities a stage requires — see [Customising workflows](https://codeherder.com/docs/task-types/#per-stage-settings) for where that setting lives.

The device that runs these agents needs the coding CLI **installed and signed in to an AI provider** — the same way the merge stage below needs `gh` / `glab` signed in to a git host. CodeHerder checks this automatically: while any coding CLI installed on the device is signed out, the device shows an amber **Not staffable** badge next to its health badge in the devices list, and the engine holds back any task that needs that CLI. Sign each one in on the device itself (for example, `claude login`), or uninstall the ones you don’t use. The device clears within a few minutes, or immediately if you restart `ch device-server`. See **Device health and readiness checks** in [Managing your devices](https://codeherder.com/docs/devices/#device-health-and-readiness-checks) for how to read a failing check.

There’s no separate step to put an agent on a device — any online, healthy device in the workspace with the agent’s required capabilities is staffable automatically. Confirm Builder has one:

```
ch agent placement Builder
```

This lists every device linked to the workspace and whether Builder can run on it. When it can’t, you see the reason, such as the device being offline, disabled, unhealthy or at capacity, or missing a capability or repository access. Want your own agent instead — a different persona, model, or harness? See [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/) for the full setup, including the default roster and how to create one.

## 5. Check your readiness

Before filing a task, confirm your workspace has everything a session needs:

```
ch workspace readiness
```

This checks off each required setup step (connecting a device, bringing it online, linking a harness credential, adding a repository, and reaching an agent) and prints a running “N of M set up” count. An optional last step, running a task as a session, is listed too. The web app’s Dashboard shows the same list as a **Start here** card, and it disappears once every required step is done.

## 6. File your first story

A **story** is the right type for a concrete, buildable unit of work. Stories are auto-staffed — once you file one, the engine assigns an available agent automatically, and builds it in the repository you connected in step 2. If your workspace ends up with more than one connected repository, see **Which repositories a task builds in** in [Connecting repositories](https://codeherder.com/docs/repositories/#which-repositories-a-task-builds-in) for how CodeHerder picks one, or name it explicitly with `--repo <name>` on the `ch task create` call below.

Write your acceptance criteria to a file, say `acceptance.md`:

```
- [ ] Login form accepts email and password
- [ ] Invalid credentials show a clear error message
- [ ] Session persists across page reloads
```

Then create the story with its criteria in one call:

```
ch task create --title "Add user authentication" --type story --description "Users need to log in with email and password." --acceptance-file acceptance.md
```

Copy the task ID from the output — you’ll need it in the next step. The story is created at `todo` — waiting to be picked up — and the engine auto-staffs it into the `plan` stage. Each `- [ ]` line in your acceptance criteria renders as a tickable checkbox on the task page, and every item must be ticked before the task can reach `merge` or `done`. The one exception is an item an author has deferred to a later stage: it doesn’t block `merge`, but it still blocks `done`. See [Writing tasks an agent can build](https://codeherder.com/docs/writing-tasks/) for how ticking and the checklist gate work. To change the criteria later, `ch task edit <taskId> --acceptance-file acceptance.md` replaces them. Once acceptance criteria are set, there is nothing more to do. The engine picks up the story automatically, runs the planning stage to confirm the spec is ready, then advances to the build stage where the agent writes code and opens a pull request. See [How work flows](https://codeherder.com/docs/how-work-flows/) for detail on each stage and the stage gate that governs transitions.

## 7. Follow the work

Check the task at any time:

```
ch task show <taskId> --comments
```

`--comments` is what prints the agent’s hand-off notes. Without it, `ch task show` only prints how many comments there are, and only when there is at least one. The status row shows the task’s current stage. A spend line always prints. It shows the total once the task has recorded spend. For a quick pulse of your own recent activity and workspace stats:

```
ch dashboard
```

See [Finding and tracking your work](https://codeherder.com/docs/tracking-work/) for what each line means and the flags it takes.

When the agent finishes the `code` stage, a merge request appears in your repository. By default, CodeHerder carries the work autonomously through `review` (an agent checks the MR against the acceptance criteria), `merge` (an agent lands it on the task’s base branch — your repo’s default branch unless the task names another), and `verify` (an agent confirms it works in the running app) before closing the task as `done`. For the `merge` stage to succeed, the device needs the host CLI installed and signed in — `gh auth login` for GitHub, `glab auth login` for GitLab; see **What the device needs** in [Connecting repositories](https://codeherder.com/docs/repositories/). You retain control through configurable approval gates — most reliably on a workflow’s entry stage, so CodeHerder asks your approval before it starts an unassigned task at all — and comment gates, which guard actions like cancelling a task. See [Approvals & staying in control](https://codeherder.com/docs/approvals/) for how gates work.

---

Next steps: [Core concepts](https://codeherder.com/docs/concepts/) explains the full object model. [How work flows](https://codeherder.com/docs/how-work-flows/) covers every pipeline stage in detail. [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/) has the complete CLI reference and agent configuration options. [Using the ch CLI](https://codeherder.com/docs/using-the-cli/) covers the conventions — help, short-form aliases, JSON output — that apply to every command you just ran.

## Related guides

- [Welcome to CodeHerder](https://codeherder.com/docs/welcome/) — what CodeHerder is and the core idea
- [Core concepts](https://codeherder.com/docs/concepts/) — the object model behind everything
- [Using the ch CLI](https://codeherder.com/docs/using-the-cli/) — command conventions that apply everywhere