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, connect a device, create an agent, and file your first story.

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

The conventions that apply to every ch command — discoverable help, the universal ls/get/rm short forms, JSON output and exit codes for scripting, the three ways to supply text, and how to refer to a task, workspace, repo, or other record.

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 task types — their stages, gates, fields, and parent rules — from Settings → Task types or the ch CLI.

Inspect any task's effective pipeline, and either give one task a different workflow than its type's default (owner/admin) or propose a change to the whole type for review (any member).

How to choose the right task type, fill required fields, write acceptance criteria, set priority, and attach tasks to parent work so the engine routes them correctly.

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 to update a task's title, priority, description, due date, and per-task fields; complete a task early; cancel or archive a task; and what reopening a terminal task actually does.

How work is routed to agents and people, how to pin a specific assignee in the web app, and how to keep a stalled task moving.

A diagnostic guide for tasks that appear stuck — covering approvals, blockers, spend caps, stalled sessions, staffing gaps, host-CLI auth failures, task types, container tasks, and reopened tasks that never restart.

What a blocker is, which ones also flip a task to the blocked status and which don't, which clear themselves — including one you can set to release on its own at a future time — and how to file, view, and resolve one from the web app or CLI.

Approval gates, the pending-advance state, approving and rejecting, 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 reviews take, how often work bounces back to the build stage, and what review costs — the review-side counterpart to first-pass rate.

How to find the tasks that matter to you — the dashboard, task list filters, task detail, hierarchy navigation, your activity feed, watched tasks, and pending approvals.

Your personal queue — blockers waiting on you, approvals to give, active tasks you created, and tasks you're watching.

Watch what your agents are doing in real time, drop into a live terminal, send auditable input, review a finished run's timeline, and manage capacity — queued and leftover sessions — from the Sessions view.

Spin up an interactive worktree on a device for exploratory work that isn't tied to a task — create, find, drop in, resume, and retire a dev session from the web app or the CLI.

The two ways an agent asks for your input — structured questions and free-text heads-up notes — and the four places you can see and answer them, the Dashboard, an agent's page, a session's page, and the task itself, which keeps a permanent record of every question and its answer.

How to subscribe to a task, choose your DM notification mode, and manage your watched list.

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

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.

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

How workspace memory stores durable learnings that survive session resets — entry anatomy, scopes, kinds, the review gate, what an agent actually recalls and how a confirmed change reaches agents already at work, the store's size limit, reading and writing entries from the web app and CLI, and backing up or migrating your workspace memory.

How the Feedback inbox collects agent suggestions and CLI submissions, and how to triage items with Archive, Convert to task, and Workflow proposals.

How to attach files to a task in the web app, drop or paste any file — images or documents — directly into task text, and use the CLI to upload, list, and download attachments.

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.

Invite people to your workspace via email, accept workspace invitations, mint API keys for CLI access, manage workspace roles, and organise members into teams.

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

Add CodeHerder as a remote connector in claude.ai or chatgpt.com so you can list tasks, read activity, read workspace memory, create tasks, and post comments right from inside those apps.

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 a git repository with your workspace, list and inspect repos, edit a repo's name or Git URL, set which repo a workspace's tasks build in, and archive or restore one.

Two ways to connect a machine to CodeHerder — install the ch CLI and run ch device-server on a machine you already have, or launch one in your own AWS account. No separate register step either way.

One click from the Devices page opens AWS CloudFormation with a CodeHerder device pre-configured — what you need first, what to fill in, and how to attach the new device to your workspace.

How to keep devices Online, give one a friendlier name than its hostname, inspect load, adjust concurrency, monitor AI subscription usage limits, pause (drain) a device, retire a device, force a stuck device to release worktree slots, and troubleshoot a device that isn't picking up work.

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, why only one connection per device is allowed, the alert you get when a second connection displaces the first, and how to rotate a token you suspect is compromised.

What an agent running on your device can reach, and the three shipped ways to tighten it — a dedicated agent OS user, per-stage containers, or running the whole device server in a container.

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.

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

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

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.

Connect your workspace to external services — what each connection is used for today, how it inherits from a group, and how to connect, test, disable, and remove one.

A skill is a reusable instruction bundle you can write yourself or switch on from the built-in catalog, per workspace — how to find it, turn it on, author your own, and check that it reached a session.

How to update the ch CLI manually, how the device server keeps itself up to date automatically, and how to diagnose a device that's stuck on an old version.

What your account's plan covers — resource limits, usage meters, the features it unlocks, 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.

Set per-agent daily and per-task total spend caps to control model cost, and understand how the caps behave when reached.

What happens when a device's Claude subscription plan hits its usage window, how CodeHerder recovers automatically, and how to keep work moving before the reset.

How to use the search box to find tasks, workspace memory, messages, comments, workspaces, and support documentation across everything you have access to.

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

What a capability label is, and the different rules that apply at each of the places capabilities appear — agent skills, launch-config gates, and task or schedule requirements.

Recurring task creation — a schedule fires on a cron cadence and spawns an ordinary task that flows through the normal workflow engine.

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