Welcome to CodeHerder

What CodeHerder is and the core idea behind it — herding AI coding agents through staged, reviewable work.

CodeHerder is a task-based orchestration platform for AI coding agents. The name is literal: you describe work as tasks, and CodeHerder herds the agents through that work in a controlled, reviewable way — from the first rough idea through to a merged pull request.

The core idea

On its own, an AI coding agent is a capable but unguided tool. It will attempt the work it’s given, but nothing stops it from going off-track, duplicating effort, or merging half-baked code. CodeHerder adds the scaffolding that turns individual sessions into a predictable engineering process:

Tasks are the unit of work. Every task has a type, a status, and a defined path through a workflow. A task moves through that workflow one stage at a time, work can be sent back for rework when it doesn’t hold up, and every move is recorded — so work stays traceable.
Stages are checkpoints. A story plans, builds, gets reviewed, merges, and gets verified before it closes. The lightweight type skips straight from build to merge. Initiatives and epics don’t build anything themselves — they just track their children through to done. See Core concepts for the full pipeline each type follows.
Sandboxes give each task its own isolated checkout — a git worktree per repository it works in, up to ten — and its own branch. Agents work in their own copy, so parallel tasks never collide.
Humans stay in control. By default the engine carries work autonomously through review, merge, and verify to done. You retain control through configurable approval gates — which require a human to confirm a transition before it proceeds — and comment gates, which guard actions like cancellation. Add an approval gate to any stage where you want a human in the loop before the work moves forward.

What’s in a workspace

Everything in CodeHerder lives in a workspace — a shared space for a team or project. Inside a workspace you will find tasks, agents (configured AI workers), connected repositories, and a shared wiki for accumulated learnings.

Where to start

If you’re new here, begin with Quickstart: it walks you from a fresh account through installing the CLI, connecting a repository, registering a device, and watching an agent open your first pull request. Then read Core concepts for the full object model — workspaces, tasks, agents, sandboxes, and how they fit together. Once you’re building, How work flows explains the stage machine: how tasks move through plan, code, review, merge, and verify.

Guides

Getting started

Quickstart — Step-by-step path from a fresh account to your first merged pull request: install the CLI, connect a repo and device, confirm you’re ready, and file your first story.
Run a task on your own machine — Skip the account entirely: try a disposable example, or describe a task in a git repository with one command and watch an agent build it.
Core concepts — The full object model: accounts, workspaces, tasks, members, agents, sandboxes, repositories, and devices, and how they relate to each other.
Using the ch CLI — The conventions that apply to every command: discoverable help, the universal ls/get/rm short forms, JSON output and exit codes, scoping a list to yourself, an agent, a device, a task, or a workspace, the three ways to supply text, and how to refer to a task, workspace, repo, or other record.
Your sessions in the terminal — Run ch with no command to get a session sidebar and terminal tabs: open a live session, switch workspaces, and start a new one without leaving the terminal.

Platform setup

Managing workspaces — Create and nest workspaces, understand accounts and the account switcher, edit a workspace’s name, description, and URL, understand membership scope, select the active workspace in the CLI and web app, and archive or permanently delete a workspace.
Members, teams, and roles — Invite people to your workspace, accept invitations, mint API keys for CLI access, manage workspace roles, and organise members into teams.
Single sign-on (SAML) — Connect your identity provider so people sign in to CodeHerder through your own SAML setup, on the Enterprise plan.
Automatic user provisioning (SCIM) — Let your identity provider create, update, and deactivate CodeHerder accounts automatically, on the Enterprise plan.
Custom branding — Set your own product name, wordmark, colours, and login screen across a self-hosted deployment, or your own name and sender on a workspace’s transactional email, on the Enterprise plan.
Credentials and profiles — Sign in with your browser or configure an API key, verify your connection, and save named credential profiles to switch between workspaces or identities.
A repository’s project folder — Commit a .codeherder folder to a repo to keep a team’s own workflow, stage, and rubric documents in the codebase, and adopt or create one with ch project init.
Connect CodeHerder to claude.ai or ChatGPT — Add CodeHerder as a remote connector in claude.ai or ChatGPT, signed in with your normal login.
Project defaults for the CLI — Commit a .codeherder.env file to a repo so everyone who checks it out gets the same server and workspace, without exporting anything themselves.
What Claude and ChatGPT can do with CodeHerder — What that connector can read and write on your behalf, and what it can’t touch.
Connecting repositories — Register a git repository with your workspace, list and inspect repos, edit a repo’s name, Git URL, or default branch, mark a repo read only, set a repo’s commit identity, set which repo a workspace’s tasks build in, and archive or restore one.
How do I add a device? — Connect a machine you already have: install the CLI and run ch device-server, which self-registers on first run. There is no separate register step.
Launch a device on AWS — No spare machine? Launch one in your own AWS account with a single click from the Devices page.
MicroVM runners — Let CodeHerder launch its own short-lived AWS devices automatically whenever your workspace’s queue outruns your fleet.
Devices that clean up after themselves — Run a throwaway device server that registers itself, does its work, and archives itself once idle, on a machine you launch and dispose of yourself.
Managing your devices — Keep devices Online, inspect load, adjust concurrency, monitor AI usage limits, and troubleshoot a device that isn’t picking up work.
AI credentials on a device — Give a device more than one Claude credential, cap how much of one it may use, and see how a session picks between them.
Git tokens on a device — Give a device several scoped GitHub or GitLab tokens instead of a single sign-in, and see exactly which one a repository gets.
Changing a device’s settings — Change six device settings from the web app, see when each one takes effect, and learn why a device can show a different value.
Running the device server as a service — Configure ch device-server as a systemd (Linux) or launchd (macOS) background service so it starts automatically at login, restarts on crash, and persists across reboots.
Device tokens — What a device token is, the alert you get when a second connection displaces the first, and how to rotate a token you suspect is compromised.
Isolating agent runs on a device — What an agent running on your device can reach by default, and the three shipped ways to tighten it: a dedicated agent OS user, a fresh container per stage, or running the whole device server in a container.
Who can run code on your device — What a compromised server or a workspace admin can run on a linked device, what CodeHerder records, and how to limit it.
Running a stage in your own container image — Give a workflow stage its own container image and a setup script to prepare it, for projects that need a toolchain the default image doesn’t have.
Agents and the CLI — Create, configure, and deploy agents; understand how agents run in isolated sandboxes and sessions; and use the ch command-line tool.
Choosing the coding-agent CLI your agents run — The five coding-agent CLIs CodeHerder can launch, what’s identical across all of them, and the four things that change when you switch — placement, whether spend is tracked, conversation continuity on rework, and model choice.
Agent personas and system prompts — Set the persona and system prompt fields on an agent’s launch config to control the agent’s identity and standing rules across every task it runs.
Monitoring your agents — See what your fleet of agents is doing and whether it is healthy: the Agents page, workload snapshots, per-agent event feeds, and quality metrics.
Which model your agents run — How CodeHerder picks a model for a stage: the tier a stage asks for, naming a model outright, and cost-aware routing with an Allowed models list.
Secrets — Store encrypted credentials at the workspace level and give an agent access to one through a Credential ref, without ever putting a plaintext value in a launch config.
Secrets on a device — Reference a credential that lives only on a device’s own secret store instead of in CodeHerder, and get the device owner’s acknowledgement it needs before an agent can run.
Variables — Set an environment variable or a sealed secret at group, workspace, device, or agent scope, from Settings → Variables or ch variable, and see which scope wins when more than one sets the same key.
Integrations — Connect your workspace to GitHub, GitLab, Slack, and PagerDuty: what each connection is used for, how a group’s connection inherits down to its workspaces, and how to connect, test, and remove one.
Skills — Turn on a skill from the built-in catalog, write your own, and see how either kind reaches an agent’s session.
Which skills a stage gets — Narrow a workflow stage’s sessions to a specific list of skills instead of the workspace’s whole enabled set, and read the result on a session’s Skills panel.
Updating the CLI — Update the ch binary manually, or let it and the device server keep themselves current automatically.
Self-hosted deployment — Download a CodeHerder server release, verify and run it against your own PostgreSQL database, connect your CLI and devices to it, upgrade it later, and confirm which build is live, on the Enterprise plan.
Hardening a self-hosted server — Set the required production value of each security setting, and copy a sandboxed systemd unit, drop-ins and a reverse-proxy config.
Self-hosted logs — Find each log a self-hosted server writes, read its format, see which headers and URL parameters to redact, and ship the logs off the host with a tested Vector example.
Verify a self-hosted host — Check a self-hosted server host against the reference. Each check has an expected value and a command, plus one script that prints pass or fail.
Contain an incident on a self-hosted server — Pause or freeze agent work, revoke one person’s credentials, and decide when to stop the server instead.
Monitor background workers — Poll one endpoint to catch a stuck or always-failing background worker on a self-hosted server, and page when workers are overdue.
Recover from a half-applied self-host upgrade — finish a stopped download, startup, webapp deployment, or device update.
Self-hosted Cognito sign-in — Grant the server its Cognito lifecycle permissions, check them, alert on a denied revoke, and turn on Cognito threat protection.
Self-hosted data residency — Where self-hosted data lives, every flow that leaves your AWS account, the vendor endpoints the install still calls, and the outbound channels.
Self-hosted infrastructure — Record the infrastructure you run beside a self-hosted server, list every outbound destination it can reach, and grant its AWS roles least privilege.
Self-hosted KMS keys and attachments bucket — Create the secret-store KMS key and an encrypted attachments bucket in your own AWS account, and set the four settings that connect them to your server.
Self-hosted outbound firewall — Restrict the outbound traffic of a self-hosted server’s app host to the documented destinations, roll the rule out in alert mode first, and test it.
Self-hosted support bundle — Build a support bundle of setting names, versions, health checks and counters, see every field it holds, and send it by email or ticket.
Self-hosted support and incident response — Who runs an incident on a self-hosted server, device-owner duties, severity levels and notice times, the post-incident review, and tests for the paging path and a leaked API key.
Self-hosted synthetic checks — Run one command on a schedule to prove sign-in, mail, secrets, devices and updates work on your self-hosted server.
Alarm on trace export failures — Watch audit and execution trace export on a self-hosted server. Learn how long an undelivered event survives and set alarms.
Check your KMS permissions — Prove with real AWS KMS calls that your self-hosted server can encrypt and decrypt secrets, that a wrong context fails, and that an unauthorised principal is denied.
Replacing a compromised self-hosted server — Isolate a suspect self-hosted server, preserve evidence and its chain of custody, build a clean replacement, rotate credentials, and plan emergency host access.
Verify the audit export — Check that the audit webhook export you keep is complete and unaltered, even after the server pruned its own rows or a workspace was deleted.
Self-hosted key custody — Keep a copy of the four at-rest keys outside the host, reuse them on a new host, set the production key rules, and know who holds the KMS key, how to protect it from deletion, and how to recover.
Self-hosted log retention and access — Set retention and reader permissions for each log class, audit receiver, device log and host-administration session record.
Self-hosted backup and recovery — Escrow the four at-rest keys, back up and copy the database and attachments, watch the recoverable point, rehearse a full restore, and promote a restored database safely.
Self-hosted database encryption and TLS — Encrypt the database with your own KMS key, require sslmode=verify-full with the RDS CA bundle, and check both with commands.
Self-hosted launch workload — the launch workload in one table: people, sessions, devices, tasks, attachments, webhooks and cost rows, with growth steps
Self-hosted retention and data subject requests — the retention schedule per data class, a DSAR procedure, the identity provider step, and backup residue
Sizing a self-hosted deployment — Pick starting sizes for the app host, PostgreSQL, and device fleet, see where each number comes from, and learn when to grow.
Mail, spend and security detections — Set SES mail alarms, budget and anomaly alarms for spend outside AI accounting, and map common security detections to event types for your SIEM.
Self-hosted device disk growth — Measure device disk use, see which directories grow and which setting bounds each, set a disk alert at 70 and 85 percent, and clean the stores that have no bound.
Self-hosted operator access and changes — State that CodeHerder staff have no access to your install, what the operator may do, who approves changes, how to record them, and the joiner, mover and leaver steps.
AI provider outages — See what a rate limit, quota or outage at your AI provider looks like, how CodeHerder limits the retries, what it costs, and what to do on each route.
Rotating self-hosted at-rest keys — Rotate an at-rest key or the KMS key on a running server with a previous-key slot, reseal every stored secret, and drop the old key safely.
Self-hosted responsibilities and launch acceptance — Who owns, operates and is told about credentials, devices, identity, backups and contacts on your install, and the launch acceptance record to sign.
Self-hosted service objectives — Measure each customer journey and feed on a self-hosted server, and set your own targets from the ranges CodeHerder states.
Verify Cognito before go-live — Run ten checks on your own Cognito user pool before live work starts. Each check has a command and an expected result.
Self-hosted acceptance journey — Your instance operator and your team run one journey from the first account to a finished task in each execution mode, and fill in a blank evidence record.
Administrator briefing: visibility and trust — What every workspace member can read, what a group passes to child workspaces, and what each execution mode trusts. Your administrator signs it.
When GitHub or GitLab is down — What a cloud git-host outage looks like on a self-hosted server, why no stage completes falsely, and what to do during and after it.
Diagnose device tunnel failures — Find why a device keeps going offline, using only ch, the device logs and the support bundle. Then hand off to the support contact without a credential.
Release a provisioning breaker — Find why a task stays blocked after repeated provision failures, fix the cause and release the breaker. Hand off to the support contact without a credential.
Self-hosted diagnosis exercise — A facilitator stages a tunnel fault and a breaker fault on a test device. Your operator follows the runbooks and hands off. Blank evidence records follow.
Self-hosted exit and data preservation — Export every workspace, check each export against your database with a count comparison, and keep a readable copy of the database and the attachments bucket.
Self-hosted departure checklist — Retire an install across identity, devices, integrations and backups. Each step has a command and an expected result. A blank rehearsal record follows.
Self-hosted licence expiry and renewal — The expiry warning to alert on, what stays enforced and what stops after a lapse, and how to renew.
Self-hosted device isolation — What each execution mode isolates, how to isolate a shared device, and what workspaces on one device share.

Managing work

How work flows — Task types, workflow stages, stage gates, the merge stage, and how to move a task yourself from the web app or the CLI.
Customising workflows — Tailor a workspace’s workflows — their stages, gates, custom fields, and lifecycle rules — from Settings → Workflows.
Customising a task’s workflow — Inspect any task’s effective pipeline, give an individual task a different workflow than its type’s default (owner/admin), or propose a workflow change for the whole type for an owner/admin to review.
The stage library — Browse and author the shared stages your workflows are built from, and compose a workflow’s pipeline from them instead of writing one by hand.
Auto tasks — the agent chooses the workflow — File a task whose workflow the agent picks for itself from your stage library, and set the floor and ceiling that bound what it may pick.
Writing tasks an agent can build — Choose the right type, fill required fields, write acceptance criteria, set priority, and attach tasks to parent work.
Choosing a task’s base branch — Set which branch a task’s sandbox is cut from and where its merge request lands — at creation, afterwards, and how CodeHerder resolves one when you don’t.
Understanding the task hierarchy — How work nests from initiative to epic to story, the rules that govern each level, and how to navigate the tree from the CLI and web app.
Tasks that span several repositories — Attach up to ten repositories to one task, see which repos it’s working in, and how the work lands as one merge request per repo.
Editing and cancelling tasks — Update a task’s title, priority, description, due date, and per-task fields after creation; complete a task early from any active stage; cancel or archive a task; and reopen a finished task to an earlier stage with ch task reopen.
Version history and going back — What carries a saved history — a workflow, a stage, a wiki page, a task’s own fields, a task’s own definition, a stage rubric — what a history row shows, and whether and how you can go back.
Assigning and claiming work — How CodeHerder picks who runs a stage, how auto-staffing gets every built-in type moving on its own, what the Assignee pin does and doesn’t control, and how to keep a stalled task moving.
Why isn’t my task moving? — Diagnose a stuck task: read the task’s status as the primary signal, then walk each cause — approval pending, blocker filed, spend cap reached, stalled assignee, no available device or agent, a host CLI that isn’t signed in, a workspace storing an out-of-date type, a container waiting on its children, a reopened task that never restarts, or a change-shape limit.
Blockers and blocked tasks — What a blocker is, every way one ends up on a task, which flip it to the blocked status and which clear themselves — including one you set to release itself at a future time — the Blockers page in the web app, and how to file and resolve one.
Network access approvals — How a session asks for a blocked network destination, who can answer, what each answer allows, and how to revoke it.
The Placement report — See exactly which devices could run a task or agent right now, and why the others can’t: the fleet state, every requirement and where it came from, all eight refusal reasons, and the caveats that would otherwise stay invisible.
Staffing coverage — Part of the Agents page: see which agents and devices can staff each stage of every enabled workflow, spot a coverage gap before a task ever hits it, and highlight the devices a stage, an agent, or a capability actually reaches — plus a per-agent view on that agent’s own page.
Approvals & staying in control — Approval gates, the pending-advance state, how to approve or reject a pending advance, and how to find what’s waiting on you.
Reviewing an agent’s work — Inspect an agent’s output at the review, merge, and verify checkpoints — read hand-off comments, open the merge request, or send it back for rework.
Review debt — See how the review queue itself is doing: review latency, how often work bounces back for rework, and what review costs, from the Dashboard or the CLI.
Change shape — Read a task’s change shape — files, lines, spread, and commits — on the task page or from the CLI, and optionally require a stage to enforce a size limit before it advances.
Composition outcomes — See whether letting an agent choose a task’s own workflow actually pays off, compared with a hand-pinned or default workflow for the same task type.
Cost and rework per completed task — See what a completed task actually cost, how often it was right first time, and what the window spent regardless of outcome.
Judge calibration — Measure whether a judge’s verdicts agree with real outcomes often enough to trust, read the six readiness checks, and see what an armed judge changes.
Prompt trials — Measure a proposed stage prompt against 6 to 12 real finished tasks, read the guardrails a candidate must clear, and promote or roll it back.
Retrospectives — Turn on evidence capture and analysis, read what a retrospective found in the app or from the CLI, and judge a proposed change honestly before you act on it.
Setup comparison — Put two setups side by side on the same stages, from the Quality page or the CLI, and see which one is actually doing better.
Stage judging — Turn on independent scoring of finished stage attempts, see what gets judged, and read the results — none of it ever holds a task back.
Stage signals — See how well each workflow stage’s own gate is calling it: which attempts get accepted, reworked, or never resolved, and how often the gate’s own approvals and rejections turn out to be right.
Stage-attempt detail — Drop from a stage’s rate down to the attempts behind it: one row per try at a stage, with how it turned out, which setup ran it, and what it cost.
Trial runs — Replay a set of finished tasks under a different harness, model, or pinned stage versions to measure it, safely, without ever committing or moving the real task.
Finding and tracking your work — Use the dashboard, task list filters, the Tasks page’s List, Board, and Graph views, task detail, and your activity feed to stay on top of what is happening.
My work — Your personal queue: blockers, network access requests, approvals, tasks you created or watch, and the apps and machines connected to your account.
Following a live agent session — Watch what your agents are doing in real time, drop into a live terminal, send auditable input, review a finished run’s timeline, and free up capacity from queued or leftover sessions — all from the Sessions view.
Sessions from the command line — Find, read, watch, and steer a session with ch session, including what a finished run left behind and who can use each subcommand.
Start a session in your own checkout — Turn the git checkout you’re already in into a CodeHerder session with ch start, no cloning or worktree involved; run ch start --check first to see whether it will succeed.
Start a session on a device — Create a device-pinned worktree and terminal on demand, as yourself or as an agent, independent of any task, from the web app or the CLI.
When an agent needs your input — The two ways an agent reaches out: a question you answer by picking options and clicking Submit, and a heads-up note you acknowledge while the agent keeps working — answerable from the Dashboard, an agent’s page, a session’s page, or the task itself, which keeps a permanent record of every question and answer.
Choosing what reaches an agent session — Add, narrow, or mute the workspace events an agent session receives, using task and session rules from the web app or ch task subscriptions and ch session subscriptions.
Watching tasks and notifications — Subscribe to a task, choose what each DM mode delivers or pick exact events, and see every other source that lands in your inbox.
Activity feeds — Where to see what actually happened: a task’s Activity timeline, the Activity panel around the workspace, and the four ch activity scopes from the CLI.
The commits and merge requests a task produced — Read one task’s or one sandbox’s commits and merge requests from its own page panels or ch task/ch sandbox, and tell a merge ref apart from the fuller merge-request list.
What CodeHerder built in this repo — Read the commit ledger, the full merge-request list, and the CodeHerder-versus-external activity split for a repo, from the web app or ch repo.
Where a task came from — Read a task’s Origin row and Lineage section, see who filed it and what it connects to, and tell filed and worked apart on the member, agent, and session pages.
Messages and your inbox — Send direct messages to members, teams, or your whole workspace; wait for a reply from the CLI; and manage your inbox from the CLI or the web Messages page, including its own single-message view.
Tracking codebase size — See a repo’s production and test line counts, how they trend over time, and where the lines live, from the Repositories page or ch repo loc / ch workspace loc.
Collaborating — Task comments and hand-off notes, @-mentions, team messages, blockers, and task dependencies.
Working nearby — What makes two live sessions neighbours, the Working nearby panel, ch sandbox neighbors, and what agents are told automatically.
When a merge request’s pipeline never starts — Tell a pipeline that never started from a failed job at the merge stage, find the real cause, and follow the bounded wait-and-recreate policy.
Workspace wiki — The shared, persistent collection where the team captures durable learnings — page anatomy, scopes and kinds, governance, finding a page by text, path, or tag, linking pages, checking wiki health from the Wiki health page or the CLI, page history and recovery, how pages are placed and inherited across nested workspaces, what an agent actually recalls, and backing up or migrating the wiki with export and import.
Workflow proposals — Read the queue of pending workflow schema changes, filter it by status, and Apply or Reject a proposal as an owner or admin.
Agent Experience surveys — Ask your agents a short question set while they work, gate their next move on an answer, and read the results in the web app or with ch survey.
Attaching files and images — Attach files to a task in the web app, drop or paste any file — images or documents — into task text, and use the CLI to upload, list, download, and delete attachments.
Writing in the house prose style — The plain-English writing style CodeHerder asks every agent to use, why it exists, and where it shows up across the API, CLI, and MCP.

Reference

Plans and limits — What your account’s plan covers: resource limits, usage meters, the features it unlocks, history retention, and the over-limit prompts.
Understanding costs — How CodeHerder tracks model spend and how to view costs by window, agent, model, or task.
Reading the Observability report — See where your agents’ time goes: the summary, rates, daily trend, time split, six breakdowns, the slowest individual calls, and one session’s own tool calls.
Reading the task flow report — See where a task’s elapsed time goes between arrival and completion, and why ready work isn’t running.
Alert rules — Watch a metric over a rolling window, open an incident when it breaches, and route the alert to your activity feed or a webhook.
Spend limits — Cap what an agent, a task, or a whole workspace can spend, see what happens when each cap is reached, and the warnings CodeHerder sends before that happens.
The optimization budget — Cap what CodeHerder’s own retrospectives and prompt trials may spend, read the envelope, and clear an unknown-cost hold.
AI usage limits — What the AI limits meters show, which ones pause a device, how CodeHerder recovers automatically, and how to keep work moving before the reset.
Global search — Search across your tasks, wiki pages, messages, comments, workspaces, and support docs — from the web app, the command line, or a connected assistant.
Sharing a view with a link — How a list page’s filters travel in its web address, so a filtered view is a link you can bookmark, reload, or send to a teammate.
Sorting a list by column — Click a column header to sort a list by it, the shared ordering rules, which pages and columns sort, and what a sort means on a list still loading rows.
Unsaved changes and drafts — How the web app keeps what you type when you reload or navigate away, what the “Draft restored” notice means, and what a draft never includes.
Capabilities — What a capability label is, and the different rules for agent skills, launch-config gates, and task or schedule requirements.
Scheduled tasks — Create a recurring task, or make an existing task recurring, that fires on a cron schedule and flows through the normal workflow engine.
Webhooks — Subscribe to workspace events and receive a signed JSON payload at your HTTPS endpoint whenever a matching event occurs.
Inbound webhooks — Let an external system act on your tasks by sending a signed payload to a receive URL, matched against rules you define.
The prototype kit — The header a prototype loads, the ten component classes it can use, and the rules that keep every agent-written prototype looking like one product.
Reporting a security vulnerability — How to report a security flaw privately with no account, the encrypted option, what to expect, and how a self-hosted server publishes its own security contact.

Quickstart — install the CLI and ship your first task
Core concepts — the object model behind everything