Welcome to CodeHerder

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. Agents can only move a task forward one step at a time, so work stays traceable.
• Stages are checkpoints. A story goes through a planning stage (where the agent reads the spec and clarifies its approach) and then a build stage (where it writes and ships the code). High-stakes types add a review stage before the task closes.
• Sandboxes give each task an isolated git worktree and branch. Agents work in their own copy of the repository, 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 (AI worker templates), connected repositories, and a shared memory store 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 a pull request opened by an agent: install the CLI, connect a repo, connect a device, create an agent, and file your first story.
• Core concepts — The full object model: 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, the three ways to supply text, and how to refer to a task, workspace, repo, or other record.

Platform setup

• Managing workspaces — Create and nest workspaces, 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.
• 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.
• Connecting repositories — 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.
• 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.
• Managing your devices — Keep devices Online, inspect load, adjust concurrency, monitor AI subscription usage limits, and troubleshoot a device that isn’t picking up work.
• 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.
• 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, cost tracking, conversation continuity on rework, and device readiness checks.
• 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.
• Shaping how an agent works — personas and system prompts — Set the persona and system prompt fields on an agent template to control the agent’s identity and standing rules across every task it runs.
• 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.
• 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.
• Updating the CLI — Update the ch binary manually and let the device server keep itself current automatically.

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 task types and workflows — Tailor a workspace’s task types — their stages, gates, custom fields, and lifecycle rules — from Settings → Task types.
• 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.
• Writing tasks an agent can build — Choose the right task type, fill required fields, write acceptance criteria, set priority, and attach tasks to parent work.
• 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.
• Editing and cancelling tasks — Update a task’s title, priority, description, and per-task fields after creation; complete a task early from any active stage; cancel or archive a task; and what reopening a terminal task actually does.
• Assigning and claiming work — Assign a task to a specific agent or person, take a task for yourself by selecting your own name in the Assignee dropdown, and 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, stalled assignee, no available device or agent, an un-staffed task type, a container waiting on its children, or a reopened task that never restarts.
• 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.
• 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.
• Finding and tracking your work — Use the dashboard, task list filters, task detail, and your activity feed to stay on top of what is happening.
• My work — Your personal queue: blockers waiting on you, approvals to give, active tasks you created, and tasks you’re watching.
• 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.
• Interactive dev sessions — Create a device-pinned worktree and terminal on demand, 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.
• Watching tasks and notifications — Subscribe to a task, choose your DM notification mode, and manage your watched list.
• 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.
• 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.
• Collaborating — Task comments and hand-off notes, @-mentions, team messages, blockers, and task dependencies.
• Workspace memory — The shared, persistent store where the team captures durable learnings — 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 memory with export and import.
• Feedback inbox — How the Feedback inbox collects agent suggestions and CLI submissions, and how to triage items with Archive, Convert to task, and Workflow proposals.
• 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, and download attachments.

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.
• Spend limits — Cap per-agent daily and per-task total model spend, and see how the caps behave when reached.
• AI usage limits — 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.
• Global search — Find tasks, memory, messages, comments, workspaces, and support documentation across everything you have access to.
• 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.
• Capabilities — What a capability label is, and the different rules for agent skills, launch-config gates, and task or schedule requirements.
• Scheduled tasks — Create recurring tasks that fire on a cron schedule and flow 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.

Related guides

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