CodeHerder documentation
Every guide that ships inside the app, readable here without an account.
188 guides, no login required.
You'll write the briefs, not the code:
You want the CLI and the wiring:
Getting started
What CodeHerder is, the object model, and your first merged pull request.
- Welcome to CodeHerder
Describe software work in plain words and AI agents build it. A person stays in control and you see the cost. Start here.
- Ship an idea without writing code
No code needed. Describe the result, answer the agent's questions, approve the work and watch what it costs.
- 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.
- Run a task on your own machine
Describe work in a git repository and run one command. An agent builds it. You need no account and no workspace.
- Move a local repo to the cloud
Sign in from a repo you used without an account. Keep it local, move it to a cloud workspace, or keep it in sync. Move a synced repo back to local.
- Core concepts
Learn the object model. See what accounts, workspaces, tasks, members, agents, sandboxes, repos and devices are, and how they fit together.
- Using the ch CLI
The conventions every ch command follows, so the CLI reads the same everywhere.
- Your sessions in the terminal
Run ch with no command to get a session sidebar, a Needs you sidebar and tabs. Open sessions and act on requests in the terminal.
- Customize the terminal console
Change the console theme, sidebar, indicators and keys from the settings screen or an env file. See which setting wins in a conflict.
Managing work
Filing, tracking, reviewing and steering tasks once the herd is running.
- How work flows
Task types, workflow stages, stage gates, the merge agent stage, and how to move a task yourself from the web app or the CLI.
- Customising workflows
Tailor a workspace's workflows. Change stages, gates, fields and parent rules in Settings → Workflows or with the ch CLI.
- Customising a task's workflow
How to inspect a task's effective workflow, and override it for one task or its whole type.
- 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.
- Stage overlays
Add instructions, a model tier, skills or verifications to a stage you inherit without copying it. Edit it in Settings → Stages or with the CLI.
- Writing tasks an agent can build
How to write a task an agent can actually build, with fields it can act on.
- Choosing a task's base branch
Set the branch a task starts from and where its merge request lands. See what CodeHerder picks when you set none.
- 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
How a single task works across a set of repositories with its own checkout, base branch, and merge request per repo.
- Editing and cancelling tasks
How to edit a task's fields, complete it early, or cancel, archive, and reopen it.
- Field limits
The length limits on the fields you type into, and what the counter shows.
- Version history and going back
What carries a version history, what each history row shows, and whether you can go back to an earlier one.
- Assigning and claiming work
How CodeHerder assigns and staffs work, and how to unstick a stalled task.
- Who acts next
Read who must act next on a task, where the web app shows it, and what to do for each kind of wait.
- Why isn't my task moving?
A diagnostic guide for a task that looks stuck, and how to unstick it.
- Blockers and blocked tasks
What a blocker is, how a task gets one, which ones clear themselves, how to answer one that asks you to choose, and how to file, view, and resolve one.
- Task dependencies
Make one task wait for another, choose when the wait ends, stack a dependent on its upstream's open merge request, and manage dependencies in the app.
- Approving your organization's Claude settings
What to do when a task waits for approval of the Claude settings your organization serves. Who can decide, what each choice does and how to undo it.
- 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
Read the Placement report to see which devices could run a task or agent right now, and exactly why the others can't.
- Staffing coverage
See which agents and devices can staff each workflow stage, spot coverage gaps, and find out why one exists.
- Approvals and staying in control
Approval gates, the pending-advance state, approving and rejecting, separation of duties, finding what's waiting on you, and comment gates.
- Reviewing an agent's work
Check an agent's work at the review, merge and verify stages. Read hand-off comments, open the merge request, or send work back for rework.
- Review debt
How long work waits for review, how long review takes, how often it loops back to the build stage, and what review costs.
- Waiting for a person to merge
Add a stage where a task waits for a person to merge its pull request. See how it starts and ends, what its states mean, and how to find it.
- Change shape
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.
- Converge a merge request before merge
Wake a waiting task on CI results and comments, and send it back to a stage when its pull request fails CI, conflicts or needs work.
- 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.
- Evaluations
Run a controlled A/B test of two or more setups on the same finished tasks, and read a paired report before you switch.
- Retrospectives
Turn on evidence capture and analysis, read what a retrospective found, and judge a proposed change before you touch anything.
- Setup comparison
Put two setups side by side on the same stages and see which one actually held up.
- Stage signals
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.
- Stage-attempt detail
Go from a stage's acceptance rate down to the individual attempts behind it, and learn what every column of the attempt table means.
- Finding and tracking your work
How to find and track the tasks that matter to you across CodeHerder.
- The improvement policy
Set how often CodeHerder samples finished work, how big a sample is, and how Evaluations of a proposed change run.
- My work
Your personal queue: decisions that wait on you, work you filed or watch, approvals, connected apps, CLI sign-ins.
- Following a live agent session
Watch an agent session live, tell a stuck one from a busy one, send input, and review what a finished one did.
- Sessions from the command line
Find, watch, and steer an agent session with ch session, stop one without losing work, and see what a finished run left behind.
- Start a session in your own checkout
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
Start a session on a device for work that isn't tied to a task, as yourself or as an agent.
- Stored session transcripts
Turn on stored session transcripts for a workspace, read them in the web app or from the command line, and learn who can read them and how long they stay.
- When an agent needs your input
How an agent asks for your input, and where you can see and answer its questions and notes.
- Choosing what reaches an agent session
Add, narrow or mute the workspace events an agent session receives. Use a task or session page, or the ch CLI.
- Watching tasks and notifications
Subscribe to a task, pick what each DM mode delivers or choose exact events, and see every other source that lands in your inbox.
- Activity feeds
See what happened on a task, in the workspace and from the CLI. Read the task timeline, the Activity panel and four `ch activity` scopes.
- The commits and merge requests a task produced
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`.
- What CodeHerder built in this repo
Read the commits and merge requests CodeHerder made against a repo, and compare them with everything else landing there, per repo or workspace-wide.
- Where a task came from
How CodeHerder records who filed a task, how to read its Origin row and Lineage section, and the CLI reads for both.
- Messages and your inbox
How to send messages, read your inbox, and follow conversations, from the CLI or the web app.
- Tracking codebase size
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.
- Collaborating
Task comments and hand-off notes, editing a comment, @-mentions, record links, team messages, the workspace wiki, 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 fails
Classify every failed CI job first. Then retry, wait, fix or ask, as the class says. Also covers a pipeline that never started.
- Workspace wiki
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.
- Workflow proposals
See the workflow changes that agents or members propose. An owner or admin reviews them in the app and applies or rejects each one.
- 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
How to attach files and images to a task, from the web app or the CLI.
- 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.
- Asking a human
How an agent writes a block that a person can act on, and how the person's choice runs.
Platform setup
Workspaces, repos, devices, agents, secrets, and who can do what.
- Managing workspaces
How to create, edit, nest, and manage a CodeHerder workspace.
- Members, teams, and roles
What member, admin and owner control and how roles inherit across groups. Invite and remove people, and set up teams.
- Single sign-on (SAML and OIDC)
Connect your identity provider so people sign in to CodeHerder through your own SAML or OIDC setup, such as an Amazon Cognito user pool, 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
Replace the CodeHerder name, colours, and login screen your people see, on the Enterprise plan.
- Your email addresses
Add verified secondary email addresses to your account, make one primary, and remove one. Use the web app or ch me emails.
- Credentials and profiles
How to sign in with your browser or configure an API key, verify your connection, and save named credential profiles.
- A repository's project folder
The .codeherder folder holds a repo's workflows, stages, check commands, skills, and knowledge, and it shapes the tasks you run locally.
- Connect CodeHerder to claude.ai or ChatGPT
Connect CodeHerder to claude.ai or ChatGPT to manage tasks from either app.
- Project defaults for the CLI
Commit a .codeherder.env file so everyone who checks out a repo gets the same server, workspace, and local or cloud setup without exporting anything.
- What Claude and ChatGPT can do with CodeHerder
What a claude.ai or ChatGPT connected app to CodeHerder can read and write on your behalf, what it can't touch, and what to do if something goes wrong.
- Connecting repositories
How to register and manage a git repository in your workspace.
- How do I add a device?
Connect a machine to CodeHerder. Install the ch CLI on a machine you have, or launch a device on AWS.
- Launch a device on AWS
Launch a CodeHerder device on AWS in one click from the Devices page.
- MicroVM runners
Let CodeHerder launch its own short-lived AWS devices automatically when your workspace's queue outruns your fleet.
- Devices that clean up after themselves
Run a throwaway device server. It registers itself, does its work and archives itself when idle. No operator needed.
- Managing your devices
Manage your devices. Set a name and concurrency, check load, and read the usage limits that apply.
- 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 credentials on a device
See how an agent gets git access on a device, from a server-minted token, a device key or the git-token pool, and set up each one.
- Changing a device's settings
Change 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
Run ch device-server as a background service with systemd or launchd, so it survives logout and reboot.
- Device tokens
What a device token is, and how to rotate it or revoke an extra one from the CLI.
- How agent environments work
How a stage's container is built, mounted and fenced in, from the base image up to the agent, and where your code lives.
- Isolating agent runs on a device
What an agent running on your device can reach, and the shipped ways to tighten it.
- When a task says "Repo config not trusted"
Why a device refuses a repo that commits hooks, plugins or helper commands, and how to trust one repo, one plugin marketplace or the whole device.
- Who can run code on your device
What a compromised server or a workspace admin can run on a linked device, what is recorded, and how to limit it.
- Giving stages the tools they need
Declare the tools, system packages and setup script your stages run with, preview changes before you save, and fix a stage waiting on a build.
- Package and browser downloads in containers
How the device download cache speeds up container-stage installs. See which keys it refuses and how to use a private registry.
- PHP and Composer in container stages
Run PHP 8.5, Composer, mago, MySQL-compatible MariaDB and Redis in a container stage. Private GitLab and Packagist packages install.
- 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 an agent. See how agents run in sandboxes and sessions, how cost is tracked and how to use the ch CLI.
- Choosing the coding-agent CLI your agents run
The six coding-agent CLIs CodeHerder can launch. See what stays the same and what changes when you switch, and how to sign each one in.
- Agent personas and system prompts
How an agent's persona shapes its sessions, when the system prompt reaches a session, and where to put standing rules.
- Monitoring your agents
See what your fleet of agents is doing and whether it is healthy. Use the Agents page, workload snapshots and per-agent event feeds.
- Which model your agents run
Learn how CodeHerder picks the AI model for a stage. Set a tier, name a model on a launch config, or route by cost.
- Secrets
Store a secret at the workspace or group level and bind it to an agent's launch config under an environment variable name you choose, using a Credential ref.
- Secrets on a device
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.
- Variables
Set environment variables and sealed secrets at group, workspace, device, or agent scope, and see which one an agent's session actually gets.
- Integrations
How to connect, test, disable, and disconnect your workspace's external integrations. Also agent access and personal accounts.
- Connecting the GitHub App
Install the CodeHerder Cloud GitHub App on your organization, or create your own App when you self-host.
- GitLab webhooks
How CodeHerder registers a GitLab project webhook for a repo, how to set one up by hand, and how to rotate, remove and troubleshoot it.
- Guardrails
Ship an enforced check to every stage session on any harness. Learn what to upload, which events exist and how to read the evidence.
- Plugin integration requests
Let a Claude Code plugin ask for agent access to an integration with integrations.yaml, and see how an admin decides, what the sync refuses and the tool names.
- Plugin sources
Sync a team's Claude Code plugin skills, agents and commands into the workspace catalog at one pinned commit, and see what the sync imports and refuses.
- Plugins
Install a plugin that adds actions to your account, approve what it may call, connect its service, and see how agents, schedules and hooks use it.
- Posting task events to Slack
Connect Slack, add routes that post each task as a card with a thread, get your own task threads as DMs, and approve, answer or unblock from Slack.
- Setting up Jira
Connect a Jira Cloud site, register the webhook, add intake rules, and map stages. Read the activity list and fix a connection that turns off.
- Setting up the Slack app
Create your own Slack app from the shipped manifest, set three environment variables, then connect Slack.
- Skills
What a skill is, how to write, enable, and check one reached a session, and how to read its version history.
- Task status on pull requests
The optional status badge shows a task's stage on its pull request. CodeHerder no longer posts a status check. Remove it from required checks.
- Which skills a stage gets
How a workflow stage narrows the skills its own sessions get.
- Read-only stage posts
What a plan or review stage may post on a pull request, merge request or issue, and the safeguards that limit it.
- Release actions
Let a stage that runs after the merge dispatch repo workflows and push a release tag. It is off by default and never pushes a branch.
- Updating the CLI and the server
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.
- Self-hosted deployment
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.
- Hardening a self-hosted server
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.
- Self-hosted logs
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.
- 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
Stop agent work, end one person's access, and know when to stop the server. Use these steps when you suspect a compromise.
- 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 self-hosted CodeHerder upgrade when downloads, server startup, webapp files, or device versions are out of step.
- Self-hosted Cognito sign-in
Install the pre-token Lambda, grant Cognito permissions, alert on a denied revoke, and turn on threat protection, passkeys and factor self-service.
- 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 the server can reach, and grant its AWS roles least privilege.
- Self-hosted KMS keys and attachments bucket
Create the KMS key and an encrypted attachments bucket in your AWS account. Then 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
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.
- Self-hosted support and incident response
Who runs a self-host incident and what device owners do. Covers severity levels, a notice template, the review, and paging and key-leak tests.
- 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 seal secrets, that a wrong context fails, and that an unauthorised principal is denied.
- Replacing a compromised self-hosted server
Isolate a suspect server and keep the evidence and its chain of custody. Build a clean replacement, rotate credentials and plan emergency 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 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.
- Self-hosted log retention and access
Set retention and reader permissions for each self-hosted 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 restore, and promote it safely.
- Self-hosted database encryption and TLS
Encrypt the PostgreSQL database with your own KMS key, then require verified TLS on every connection, and check both with commands.
- Self-hosted launch workload
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.
- Self-hosted retention and data subject requests
How long each class of data is kept, the setting that changes it, and how to answer a data subject request, with backup residue.
- Sizing a self-hosted deployment
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.
- 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, and clean the stores that have no bound.
- Self-hosted operator access and changes
CodeHerder staff have no access to your install. See what the operator may do, who approves changes, 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 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.
- Self-host responsibilities and acceptance
Who owns, runs and is told about credentials, devices, identity, backups and contacts on your install. Includes the launch record to sign.
- Self-hosted service objectives
Measure each customer journey and feed on a self-hosted server, see the operating ranges CodeHerder states, and set your own targets from them.
- Verify Cognito before go-live
Run eleven 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 operator and team run one journey from the first account to a finished task at each isolation level. Then fill in the record.
- Administrator briefing: visibility and trust
What every workspace member can read, what a group passes to child workspaces, and what each isolation level trusts. Your administrator signs it.
- When GitHub or GitLab is down
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.
- Diagnose device tunnel failures
Find why a device keeps going offline with only ch, the device logs and the support bundle. Then hand off without a credential.
- Git host request budget
See how many requests your server and devices send to GitLab, why work pauses on a 429, and which server settings tune the pacing.
- Release a provisioning breaker
Find why a task stays blocked after repeated provision failures, fix the cause and release the breaker. Then hand off 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, hands off and fills in the records.
- Self-hosted exit and data preservation
Export every workspace, check the export against your database, and keep a readable copy of the database and the attachments bucket.
- Self-hosted departure checklist
Retire a self-hosted install in order. Each step names a command or route and its expected result. A blank rehearsal record follows.
- Self-hosted licence expiry and renewal
How your server warns before the licence expires, what stops after it lapses, what stays enforced, and how to renew without losing administrator access.
- Self-hosted device isolation
What each isolation level isolates, how to narrow an unisolated host, and what workspaces on one device share.
Reference
Plans, spend limits, capabilities, scheduled tasks, webhooks and search.
- Plans and limits
What your plan covers, with resource limits, usage meters, unlocked features, history retention, and how the Plan page and over-limit prompts work.
- Understanding costs
See how CodeHerder tracks model spend. View costs by window, agent, model or task, from the CLI or the Costs page.
- Reading the Observability report
The Observability report in the app and the CLI: summary, rates, trend, time split, breakdowns, slowest calls and drill-downs.
- 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 on 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, a parent task's subtasks or a workspace can spend per day, month or life, and see what happens at each cap and what warns you.
- The optimization budget
Cap what CodeHerder's analyst sessions may spend. Read the budget and clear an unknown-cost hold.
- AI usage limits
What the AI limits meters show, which ones pause a device, and how CodeHerder recovers automatically.
- Global search
Search your tasks, wiki pages, messages, comments, workspaces and support docs. Use the web app, the command line or a connected assistant.
- Keyboard shortcuts
Every keyboard shortcut in the web app, which ones need single-key shortcuts turned on, and where each one works.
- Sharing a view with a link
A page keeps its filters and layout in its web address. Bookmark, reload or send any view as a link.
- Sorting a list by column
How column sorting works, which pages and columns sort, the shared ordering rules, and what a sort covers on a list that is still loading rows.
- Unsaved changes and drafts
How the web app keeps what you type in a form when you reload or navigate away, what the "Draft restored" notice and Cancel do, and what a draft never includes.
- Capabilities
What a capability label is, which things have capabilities, which things need them, and where each one is set.
- Scheduled tasks
Create a recurring task that runs on a cron schedule. Each run makes an ordinary task with a repo and a base branch.
- Webhooks
Receive a signed JSON payload whenever chosen events happen in your workspace.
- Inbound webhooks
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 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
Report a security flaw in CodeHerder privately, with no account. What to include, the encrypted option, and response times.
These are the same guides your team reads inside the app. New to a term like "capability" or "sandbox"? The glossary defines the whole vocabulary in plain English first. Want to know what shipped recently? Read the changelog.
Try it on one repository for two weeks.
File a task. An agent builds it. A person reads every request. You see the cost of each task.