Quickstart
Go from a new account to your first agent-built pull request. Install the CLI, connect a repo and a device, and file a story.
This guide takes you from a fresh account to a pull request opened by an AI agent, and shows you how it moves on to review and merge. 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 https://app.codeherder.com/cli/install.sh | sh
The script needs openssl to check the release signature. It downloads with curl, or with wget if curl is missing. It detects your platform, verifies the signed release and its checksum, and installs ch to ~/.local/bin/ch. If ~/.local/bin isn’t on your PATH, the script prints an export PATH=... line. Add it to your shell profile. To download and verify a binary by hand instead, see the Install CLI page in the side rail (under Help).
Once ch is installed, sign in:
ch login
This opens your browser and caches your credentials — subsequent ch commands authenticate automatically. The first ch login on a machine also asks you to approve the CLI installation in the browser. You only do this once per machine (see Credentials and profiles). 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 → 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 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 seeded agents can run on Claude Code, Codex, Pi, Cursor, OpenCode or mini-swe-agent, with Claude preferred. A workspace created before mini-swe-agent was added has no mini-swe-agent config on its agents. The device needs at least one of them installed and signed in to an AI provider. See Harnesses for how to sign in to each one.
A coding CLI that is installed but signed out fails its Harness auth check. That blocks only work that needs that CLI on that device. Either sign it in on the device itself (for example, claude login for Claude Code), or exclude it with ch device-server --harness-exclude <name>. Checks re-run about every five minutes, or immediately if you restart ch device-server. See 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 that meets the agent’s device requirements 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 renders as a tickable checkbox on the task page. Every item has a proof stage, and review is the default. An unticked item holds the task at its proof stage, so by default the story can’t merge until every box is ticked. To pick a different stage, group items under headings such as ## review or ## verify. See Set the stage that proves an item, and Writing tasks an agent can build for more. 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 a git credential for the repository, and a stage that runs directly on the device needs the host CLI signed in; see Git credentials on a device and 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 and 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
- Ship an idea without writing code — the web-app path for a reader who does not code
- 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
Last updated