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 from the Install CLI page in your workspace sidebar (under Set up). That page has the download link and platform-specific instructions.

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>

Your workspace ID appears on the Install CLI page. Add it to your shell profile so it persists across sessions.

Verify the connection:

ch whoami

You should see your display name and workspace. 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

Agents branch from main by default. 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

The repository appears under Set up → Repos 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 CH_WORKSPACE_ID set (from step 1), the device server self-registers: it derives the hostname, mints a device token, writes it to ~/.codeherder/device.token, and links the new device to your workspace — which step 4 requires, since an agent can only be assigned to a device already linked to its workspace. Every run after that just reads the existing token file and connects.

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. Create an agent

An agent is a reusable worker template that pairs a persona with a launch configuration. Create one:

ch agent create --display-name "Builder" --mint-key --cap model:opus --cap model:sonnet

--mint-key prints a one-time API key for the agent — copy it now, as it is only shown once. --cap declares the model tiers this agent uses. Note the agent ID printed in the output.

Next, choose a harness — the coding CLI the device launches for each task. You can refer to the agent by the display name you just gave it instead of copying its ID:

ch agent config set Builder --harness claude --cap model:opus --cap model:sonnet

--harness claude tells the device to run the claude CLI and derives the launch command automatically — no path to figure out. Other harnesses are available (codex, cursor, opencode, pi); see Agents and the CLI for the full list and configuration options.

A story’s built-in workflow runs its planning and review stages on the opus tier and its build and merge stages on the sonnet tier, so a single agent needs both tiers to carry a story from start to finish — leave either one off and the task stalls at the first stage that needs it. This is the built-in default; a workspace owner or admin can change which capabilities a stage requires from Settings → Task types. See Capabilities for the full rule.

The device that runs this agent needs the chosen 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: until at least one installed coding CLI is signed in, the device shows a red unhealthy badge with a grey not staffable chip, and the engine withholds work from it. Sign in on the device itself — for example, claude login — and 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.

Then assign the agent to your device and approve the assignment — both commands take the agent’s display name and the device’s name (its hostname, unless you’ve given it a friendlier one — see Naming a device):

ch agent assign Builder <device-name>
ch agent approve Builder <device-name>

Find the device’s name (or its ID, if you’d rather use that) under Set up → Devices. The approval reaches the device as soon as you make it, so if ch device-server is still running from step 3 there’s nothing to restart (the command prints a restart reminder — you can ignore it). See Agents and the CLI for full details on agent configuration and required capabilities.

5. File your first story

A story is the right task type for a concrete, buildable unit of work. Stories are auto-staffed — once you file one, the engine assigns an available agent automatically.

Create the story:

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

Copy the task ID from the output. The story is created at todo — waiting to be picked up — and the engine auto-staffs it into the plan stage. Set the acceptance criteria the agent will build toward — this is what the planning stage checks before moving to the code stage:

ch task field <task-id> acceptance --from-file acceptance.md

Your acceptance.md might look like:

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

Each - [ ] line renders as a tickable checkbox on the task page, and every item must be ticked before the task can reach merge or done — see Writing tasks an agent can build for how ticking and the checklist gate work. 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.

6. Follow the work

Check the task at any time:

ch task show <task-id>

This prints the current stage, status, any hand-off comments, and a cost summary. 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 repo’s default branch), 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 task type’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