CodeHerder documentation

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

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

Describe work in a git repository with one command and watch an agent build it — no account and no workspace setup required.

The object model — accounts, workspaces, tasks, members, agents, sandboxes, repos, and devices, and how they fit together.

The conventions every ch command follows, so the CLI reads the same everywhere.

Run ch with no command to get a session sidebar and terminal tabs — open a session, switch workspaces, and start a new one without leaving the terminal.

Task types, workflow stages, stage gates, the merge agent stage, and how to move a task yourself from the web app or the CLI.

Tailor a workspace's workflows — their stages, gates, fields, and parent rules — from Settings → Workflows or the ch CLI.

How to inspect a task's effective workflow, and override it for one task or its whole type.

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.

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.

How to write a task an agent can actually build, with fields it can act on.

Set which branch a task's sandbox is cut from and where its merge request lands — at creation, afterwards, for schedules, and when you don't set one.

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.

How a single task works across a set of repositories — up to ten — with its own checkout, base branch, and merge request per repo.

How to edit a task's fields, complete it early, or cancel, archive, and reopen it.

What carries a version history, what each history row shows, and whether you can go back to an earlier one.

How CodeHerder assigns and staffs work, and how to unstick a stalled task.

A diagnostic guide for a task that looks stuck, and how to unstick it.

What a blocker is, how a task gets one, which ones clear themselves, and how to file, view, and resolve one.

How a session asks for a blocked network destination, who can answer, what each answer allows, and how to revoke it.

Read the Placement report to see which devices could run a task or agent right now, and exactly why the others can't.

See which agents and devices can staff each workflow stage, spot coverage gaps, and find out why one exists.

Approval gates, the pending-advance state, approving and rejecting, separation of duties, finding what's waiting on you, and comment gates.

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.

How long work waits for review, how long review takes, how often it loops back to the build stage, and what review costs.

Read the size and spread of a task's change at a glance, and optionally require it to stay under a limit before a stage advance.

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.

See what a completed task actually cost, how often it was right first time, and what the window spent regardless of outcome.

Measure whether your judge's verdicts are trustworthy enough to route work on, and see what changes once they are.

Measure a proposed stage prompt against 6 to 12 real tasks before you promote it, read the guardrails, and roll it back.

Turn on evidence capture and analysis, read what a retrospective found, and judge a proposed change before you touch anything.

Put two setups side by side on the same stages and see which one actually held up.

Turn on independent scoring of finished stage attempts, see what gets judged, read the results, and know when a verdict can send work back.

See how well each workflow stage's gate calls it, including which attempts are accepted, reworked, or never resolved, and how accurate the gate is.

Go from a stage's acceptance rate down to the individual attempts behind it, and learn what every column of the attempt table means.

Replay a set of finished tasks under a different setup to measure it, safely, before you switch to it.

How to find and track the tasks that matter to you across CodeHerder.

Your personal queue — blockers, network access requests, approvals, tasks you created or watch, and the apps and machines connected to your account.

Watch an agent session live, send input, and review its finished timeline.

Find, watch, and steer an agent session with ch session — plus what a finished run left behind and who can do what.

Turn the git checkout you're already sitting in into a CodeHerder session, in the same terminal, with nothing cloned or moved.

Start a session on a device for work that isn't tied to a task, as yourself or as an agent.

How an agent asks for your input, and where you can see and answer its questions and notes.

Add, narrow, or mute the workspace events an agent session receives, from a task or session page or with ch task subscriptions and ch session subscriptions.

Subscribe to a task, pick what each DM mode delivers or choose exact events, and see every other source that lands in your inbox.

Where to see what actually happened — a task's Activity timeline, the workspace Activity panel, and the four `ch activity` scopes from the CLI.

Find the commits and merge requests one task made, from the task page's panels or from `ch task commits` and `ch task merge-requests`.

Read the commits and merge requests CodeHerder has made against a repo, and see how that compares to everything else landing there.

How CodeHerder records who filed a task, how to read its Origin row and Lineage section, and the CLI reads for both.

How to send messages and manage your inbox, from the CLI or the web app.

See how a workspace's or a single repo's production and test line counts trend over time, in the web app or from the CLI.

Task comments and hand-off notes, editing a comment, @-mentions, team messages, the workspace wiki, blockers, and task dependencies.

What makes two live sessions neighbours, the Working nearby panel, ch sandbox neighbors, and what agents are told automatically.

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.

How the workspace wiki stores durable pages, how to find one by text, path, or tag, and how to check wiki health, so learnings survive session resets.

How the Workflow proposals page shows pending schema changes agents or members propose, and how an owner or admin applies, rejects, or reads them from the CLI.

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.

How to attach files and images to a task, from the web app or the CLI.

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.

How to create, edit, nest, and manage a CodeHerder workspace.

What member, admin, and owner actually control, how roles inherit across groups, how to invite and remove people, and how to organise members into teams.

Connect your identity provider so people sign in to CodeHerder through your own SAML setup, on the Enterprise plan.

Let your identity provider create, update, and deactivate CodeHerder accounts automatically, on the Enterprise plan.

Replace the CodeHerder name, colours, and login screen your people see, on the Enterprise plan.

How to sign in with your browser or configure an API key, verify your connection, and save named credential profiles.

Commit a .codeherder folder to a repo to keep a team's own workflow, stage, and rubric documents in the codebase.

Connect CodeHerder to claude.ai or ChatGPT to manage tasks from either app.

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 a claude.ai or ChatGPT connector to CodeHerder can read and write on your behalf, what it can't touch, and what to do if something goes wrong.

How to register and manage a git repository in your workspace.

Two ways to connect a machine to CodeHerder — install the ch CLI on a machine you have, or launch a device on AWS.

Launch a CodeHerder device on AWS in one click from the Devices page.

Let CodeHerder launch its own short-lived AWS devices automatically when your workspace's queue outruns your fleet.

Run a throwaway device server that registers itself, does its work, and archives itself once idle — no operator required.

How to manage your devices — names, load, concurrency, and usage limits.

Give a device more than one Claude credential, cap how much of one it may use, and see how a session picks between them.

Give one device several scoped GitHub or GitLab tokens, and see exactly which one a repository gets.

Change six device settings from the web app, see when each one takes effect, and learn why a device can show a different value.

How to run ch device-server as a persistent background service with systemd (Linux), launchd (macOS), or Docker so it survives terminal logout and reboot.

What a device token is, and how to rotate it or revoke an extra one from the CLI.

What an agent running on your device can reach, and the shipped ways to tighten it.

What a compromised server or a workspace admin can run on a linked device, what is recorded, and how to limit it.

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.

How to create, configure, and deploy an agent — and how agents act in sandboxes and sessions, how cost is tracked, and how to install and use the ch CLI.

The five coding-agent CLIs CodeHerder can launch, what stays the same across all of them, and the four things that actually change when you switch.

What the persona and system prompt fields on an agent's launch config do, how to set and update them, and how to write ones that are effective.

See what your fleet of agents is doing and whether it is healthy — the Agents page, workload snapshots, and per-agent event feeds.

How CodeHerder picks the AI model for a stage — the tier a stage asks for, a model named outright on a launch config, and cost-aware routing on top.

Store encrypted credentials at the workspace level and hand one to an agent through a Credential ref, without ever putting a plaintext value in a launch config.

Reference a credential that lives only on a device's own secret store, and get the device owner's acknowledgement it needs before an agent can run.

Set environment variables and sealed secrets at group, workspace, device, or agent scope, and see which one an agent's session actually gets.

How to connect, test, disable, and remove your workspace's external integrations.

What a skill is, how to write, enable, and check one reached a session, and how to read its version history.

How a workflow stage narrows the skills its own sessions get.

Update ch manually, plan a self-hosted server upgrade and its maintenance window, see how ch and the device server stay current, and fix a stuck update.

Download, verify, run, and upgrade a self-hosted CodeHerder server on your own PostgreSQL database, and confirm which build is live, on the Enterprise plan.

The production settings, systemd unit, drop-ins and reverse-proxy config to run a self-hosted CodeHerder server hardened, with a way to check the result.

Find each log a self-hosted server writes, its format, the headers and URL parameters to redact, and a tested Vector example to ship them.

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.

Stop agent work, end one person's access, and know when to stop the server instead. Use these steps when you suspect a compromise on a self-hosted server.

Poll one endpoint to catch a stuck or always-failing background worker on a self-hosted server, and page when workers are overdue.

Finish a stopped self-hosted CodeHerder upgrade when downloads, server startup, webapp files, or device versions are out of step.

Install the pre-token Lambda, grant the server its Cognito permissions, check them, alert on a denied revoke and turn on threat protection.

Where self-hosted data lives, every flow that leaves your AWS account, the vendor endpoints the install still calls, and the outbound channels.

Record the infrastructure you run beside a self-hosted server, list every outbound destination the server can reach, and grant its AWS roles least privilege.

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.

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.

Produce a support bundle of setting names, versions, health checks and counters with one command, see every field it holds, and send it by email or ticket.

Who runs a self-host incident, what device owners do, severity levels, a notice-time template, the post-incident review, and tests for paging and key leaks.

Run one command on a schedule to prove sign-in, mail, secrets, devices and updates work on your self-hosted server.

Watch audit and execution trace export on a self-hosted server. Learn how long an undelivered event survives and set alarms.

Prove with real AWS KMS calls that your self-hosted server can seal secrets, that a wrong context fails, and that an unauthorised principal is denied.

Isolate a suspect self-hosted server, preserve evidence and its chain of custody, build a clean replacement, rotate credentials, and plan emergency host access.

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.

Keep the four at-rest keys outside the host, reuse them on a new host, set the production key rules, and protect and recover the KMS key.

Set retention and reader permissions for each self-hosted log class, audit receiver, device log and host-administration session record.

Escrow the four at-rest keys, back up and copy the database and attachments, watch the recoverable point, rehearse a restore, and promote it safely.

Encrypt the PostgreSQL database with your own KMS key, then require verified TLS on every connection, and check both with commands.

The launch workload for a first self-hosted customer, in one table with growth columns and a named source for each number, for load tests and sizing.

How long each class of data is kept, the setting that changes it, and how to answer a data subject request, with backup residue.

Start-up sizes for the app host, PostgreSQL, and device fleet of a self-hosted server, where each number comes from, and the signals that tell you to grow.

Set SES mail alarms, budget and anomaly alarms for spend outside AI accounting, and map common security detections to event types for your SIEM.

Measure device disk use, see which directories grow and which setting bounds each, set a disk alert, and clean the stores that have no bound.

CodeHerder staff have no access to your install. See what the operator may do, who approves changes, how to record them, and the joiner, mover and leaver steps.

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.

Rotate any of the four at-rest keys or the KMS key on a running self-hosted server, reseal every stored secret, and drop the old key safely.

Who owns, operates and is told about credentials, devices, identity, backups and contacts on your install, plus the launch acceptance record to sign.

Measure each customer journey and feed on a self-hosted server, see the operating ranges CodeHerder states, and set your own targets from them.

Run eleven checks on your own Cognito user pool before live work starts. Each check has a command and an expected result.

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.

What every workspace member can read, what a group passes to child workspaces, and what each execution mode trusts. Your administrator signs it.

What a cloud GitHub or GitLab outage looks like on a self-hosted server, why no stage completes falsely, and what to do during and after it.

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.

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.

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.

Export every workspace, check the export against your database, and keep a readable copy of the database and the attachments bucket.

Retire a self-hosted install in order. Each step names a command or route and its expected result. A blank rehearsal record follows.

How your server warns before the licence expires, what stops after it lapses, what stays enforced, and how to renew without losing administrator access.

What each execution mode isolates, how to isolate a shared device, and what workspaces on one device share.

What your plan covers, with resource limits, usage meters, unlocked features, history retention, and how the Plan page and over-limit prompts work.

How CodeHerder tracks model spend and how to view costs by window, agent, model, or task — from the CLI or the web app's Cost breakdown page.

The full Observability report — summary, rates, trend, attribution coverage, time split, six breakdowns, and the slowest calls, in the app and the CLI.

See where a task's elapsed time goes between arrival and completion, and why ready work isn't running.

Watch a metric on a rolling window, open an incident when it breaches, and route the alert to your activity feed or a webhook.

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.

Cap what CodeHerder's own quality-improvement work — retrospectives and prompt trials — may spend, read the envelope, and clear an unknown-cost hold.

What the AI limits meters show, which ones pause a device, and how CodeHerder recovers automatically.

Search across your tasks, wiki pages, messages, comments, workspaces, and support docs — from the web app, the command line, or a connected assistant.

How CodeHerder keeps a page's filters and layout in its web address, so any view you're looking at is a link you can bookmark, reload, or send to a teammate.

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.

How the web app keeps what you type in a form when you reload or navigate away, what the "Draft restored" notice means, and what a draft never includes.

What a capability label is, and the places it controls routing and requirements.

Recurring task creation — a schedule fires on a cron cadence and spawns an ordinary task, with a repo set and base branch, into the workflow engine.

Receive a signed JSON payload whenever chosen events happen in your workspace.

Let an external system trigger an action on your tasks by sending a signed payload to a URL you control, matched against rules you define.

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.

Report a security flaw in CodeHerder privately, with no account. What to include, the encrypted option, and response times.