Quickstart

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.

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 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. 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.

Already have a device connected to a different workspace and want to add it here too? Link it — see Managing your devices. No spare machine to leave running? 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 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 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 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 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 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 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 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. 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 for how gates work.

---

Next steps: Core concepts explains the full object model. How work flows covers every pipeline stage in detail. Agents and the CLI has the complete CLI reference and agent configuration options. Using the ch CLI covers the conventions — help, short-form aliases, JSON output — that apply to every command you just ran.

Related guides

• Welcome to CodeHerder — what CodeHerder is and the core idea
• Core concepts — the object model behind everything
• Using the ch CLI — command conventions that apply everywhere