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.
CodeHerder lets you describe software work in plain words. AI agents then build it. A person stays in charge, and you can see what each task costs.
The core idea
An AI coding agent works well on a clear job. It can also go off track or repeat work. CodeHerder gives each job a fixed path, so the result is predictable:
- Tasks are the unit of work. Every task has a type, a status and a path through a workflow. It moves one stage at a time. Work goes back for rework if it does not hold up. CodeHerder records every move.
- Stages are checkpoints. A story plans, builds, gets reviewed, merges and gets verified before it closes. The lightweight type goes from build straight to merge. Initiatives and epics build nothing. They track their children until done. See Core concepts for the pipeline of each type.
- Sandboxes give each task its own checkout and its own branch. Agents work in their own copy, so parallel tasks do not collide.
- Humans stay in control. By default the engine carries work through review, merge and verify. You can add approval gates. An approval gate needs a person to confirm a move before it happens. Comment gates guard actions such as cancellation.
What’s in a workspace
A workspace is a shared space for a team or project. It holds tasks, agents, connected repositories and a shared wiki. Agents are AI workers with a set configuration. The wiki keeps what the team learns.
Where to start
Pick the path that fits you. Each one links to the docs you need first.
I have an idea but I do not code.
- Ship an idea without writing code uses only the web app.
- Writing tasks an agent can build shows how to ask for what you want.
I lead a team and sign off on cost and risk.
- Approvals and staying in control shows where a person confirms work.
- Understanding costs and Spend limits show what work costs and how to cap it.
- Plans and limits lists what your plan covers.
- Who can run code on your device states what the platform can run on your machines.
I write code.
- Quickstart takes you from a new account to your first merge request.
- Run a task on your own machine needs no account.
- Core concepts names the main objects.
- How work flows explains how a task moves from plan to verify.
Guides
Getting started
- Ship an idea without writing code — Describe the result, answer agent questions, approve the work and check cost.
- Quickstart — Go from a new account to your first merged pull request.
- Run a task on your own machine — Run one command in a git repo. No account needed.
- Move a local repo to the cloud — Sign in, then keep the repo local or move it.
- Core concepts — Learn the main objects and how they relate.
- Using the ch CLI — Learn the rules every
chcommand follows, from help to JSON output. - Your sessions in the terminal — Run
chwith no command for a session sidebar and terminal tabs. - Customize the terminal console — Change the console theme, sidebar and keys.
Platform setup
- Managing workspaces — Create, nest, edit and archive workspaces, and switch the active one.
- Members, teams, and roles — Invite people, mint API keys, set roles and build teams.
- Single sign-on — Let people sign in through your SAML or OIDC provider. Enterprise plan.
- Automatic user provisioning (SCIM) — Let your identity provider manage CodeHerder accounts. Enterprise plan.
- Custom branding — Set your own name, colours and login screen. Enterprise plan.
- Your email addresses — Add verified secondary addresses, make one primary, and remove one.
- Credentials and profiles — Sign in, check your connection and save named credential profiles.
- A repository’s project folder — Learn what the
.codeherderfolder holds and how to create one. - Connect CodeHerder to claude.ai or ChatGPT — Add CodeHerder as a remote MCP server with your normal login.
- Project defaults for the CLI — Commit a
.codeherder.envfile so everyone gets the same defaults. - What Claude and ChatGPT can do with CodeHerder — See what an app can read and write for you.
- Connecting repositories — Register a git repo, edit its settings and choose where tasks build.
- How do I add a device? — Connect a machine you already own with
ch device-server. - Launch a device on AWS — Launch a device in your own AWS account with one click.
- MicroVM runners — Let CodeHerder launch short-lived AWS devices when your queue grows.
- Devices that clean up after themselves — Run a throwaway device that archives itself when idle.
- Managing your devices — Keep devices online, check load and fix a device that takes no work.
- AI credentials on a device — Give a device several Claude credentials and cap each one.
- Git credentials on a device — See how an agent gets git access on a device.
- Changing a device’s settings — Change device settings and see when each one takes effect.
- Running the device server as a service — Run
ch device-serveras a systemd or launchd service. - Device tokens — Learn what a device token is and how to rotate one.
- How agent environments work — See how a stage’s layers, mounts and relays fit together.
- Isolating agent runs on a device — See what an agent can reach and how to limit it.
- When a task says “Repo config not trusted” — Trust a repo a device refuses.
- Who can run code on your device — See what an admin can run on a linked device.
- Giving stages the tools they need — Declare the tools, packages and setup script a stage needs.
- Package and browser downloads in container stages — Use the download cache and a private registry.
- PHP and Composer in container stages — Run PHP, Composer, MariaDB and Redis in a container stage.
- Running a stage in your own container image — Give a stage its own container image and setup script.
- Agents and the CLI — Create and deploy agents, and learn how they run in sandboxes.
- Choosing the coding-agent CLI your agents run — Learn which coding-agent CLIs CodeHerder launches and what changes between them.
- Agent personas and system prompts — Give an agent a persona and learn where standing rules belong.
- Monitoring your agents — See what your agents do and whether they are healthy.
- Which model your agents run — Learn how CodeHerder picks a model for a stage.
- Secrets — Store a secret and bind it to an agent’s launch config.
- Secrets on a device — Keep a credential only on a device’s own secret store.
- Variables — Set environment variables and sealed secrets at any scope.
- Integrations — Connect GitHub, GitLab, Jira and Slack to your workspace. Give agents Jira or Datadog, and connect your own account.
- Connecting the GitHub App — Install the CodeHerder GitHub App, or create your own when you self-host.
- GitLab webhooks — Register a GitLab project webhook, or set one up by hand.
- Guardrails — Ship an enforced check to every stage session.
- Plugin integration requests — Let a plugin ask for an integration and see how an admin decides.
- Plugin sources — Sync a team’s Claude Code plugins into the catalog at a pinned commit.
- Plugins — Install a plugin, approve what it may call, connect its service and see how agents use it.
- Posting task events to Slack — Connect Slack and post task events to a channel.
- Setting up Jira — Connect Jira Cloud, register the webhook, add intake rules and map stages.
- Setting up the Slack app — Create your own Slack app from the shipped manifest.
- Skills — Turn on a built-in skill or write your own.
- Task status on pull requests — See a task’s stage on its pull or merge request.
- Which skills a stage gets — Limit a stage’s sessions to a chosen list of skills.
- Read-only stage posts — See what a plan or review stage may post, and what it never does.
- Release actions — Let a stage after the merge run a workflow and push a tag.
- Updating the CLI — Update the
chbinary by hand, or let it update itself. - Self-hosted deployment — Download a release, run it on your own PostgreSQL and keep it current. Enterprise plan.
- Hardening a self-hosted server — Set each production security value and copy a sandboxed systemd unit.
- Self-hosted logs — Find each log, read its format and ship the logs off the host.
- Verify a self-hosted host — Check a server host against the reference, with a pass or fail script.
- Contain an incident on a self-hosted server — Pause agent work, revoke one person’s credentials, or stop the server.
- Monitor background workers — Poll one endpoint to catch a stuck background worker.
- Recover from a half-applied self-host upgrade — Finish a stopped download, startup, webapp deployment or device update.
- Self-hosted Cognito sign-in — Grant Cognito permissions, check them and turn on threat protection.
- Self-hosted data residency — See where data lives and every flow that leaves your AWS account.
- Self-hosted infrastructure — Record your infrastructure, list outbound destinations and limit AWS roles.
- Self-hosted KMS keys and attachments bucket — Create the KMS key and an encrypted attachments bucket.
- Self-hosted outbound firewall — Limit outbound traffic to the documented destinations.
- Self-hosted support bundle — Build a support bundle, see every field in it and send it.
- Self-hosted support and incident response — See who runs an incident, severity levels and notice times.
- Self-hosted synthetic checks — Run one scheduled command to prove sign-in, mail and updates work.
- Alarm on trace export failures — Watch trace export and set alarms for failures.
- Check your KMS permissions — Prove with real KMS calls that encrypt and decrypt work.
- Replacing a compromised self-hosted server — Isolate a suspect server, keep evidence and build a clean replacement.
- Verify the audit export — Check that your audit export is complete and unaltered.
- Self-hosted key custody — Keep a copy of the four at-rest keys outside the host.
- Self-hosted log retention and access — Set retention and reader permissions for each log class.
- Self-hosted backup and recovery — Escrow keys, back up data and rehearse a full restore.
- Self-hosted database encryption and TLS — Encrypt the database with your KMS key and require TLS.
- Self-hosted launch workload — See the launch workload in one table, with growth steps.
- Self-hosted retention and data subject requests — Find the retention schedule and a data subject request procedure.
- Sizing a self-hosted deployment — Pick starting sizes for the app host, database and devices.
- Mail, spend and security detections — Set mail, spend and security alarms for your SIEM.
- Self-hosted device disk growth — Measure device disk use and set alerts at 70 and 85 percent.
- Self-hosted operator access and changes — See what the operator may do and who approves changes.
- AI provider outages — See what a rate limit or outage looks like and what to do.
- Rotating self-hosted at-rest keys — Rotate an at-rest key or the KMS key on a running server.
- Self-hosted responsibilities and launch acceptance — See who owns what on your install and sign the launch record.
- Self-hosted service objectives — Measure each customer journey and set your own targets.
- Verify Cognito before go-live — Run ten checks on your Cognito user pool before go-live.
- Self-hosted acceptance journey — Run one journey from first account to a finished task.
- Administrator briefing: visibility and trust — See what members can read and what each isolation level trusts.
- When GitHub or GitLab is down — See what a git-host outage looks like and what to do.
- Diagnose device tunnel failures — Find why a device keeps going offline.
- Git host request budget — Read GitLab request counts and tune the pacing that pauses work on a 429.
- Release a provisioning breaker — Find why a task stays blocked and release the breaker.
- Self-hosted diagnosis exercise — Stage a tunnel fault and a breaker fault on a test device.
- Self-hosted exit and data preservation — Export every workspace and keep a readable copy of your data.
- Self-hosted departure checklist — Retire an install across identity, devices, integrations and backups.
- Self-hosted licence expiry and renewal — See the expiry warning, what a lapse stops and how to renew.
- Self-hosted device isolation — See what each isolation level isolates on a shared device.
Managing work
- How work flows — Learn task types, stages, gates and the merge stage.
- Customising workflows — Tailor a workspace’s stages, gates, fields and lifecycle rules.
- Customising a task’s workflow — Inspect a task’s pipeline and give one task a different workflow.
- The stage library — Browse the shared stages and build a workflow from them.
- Auto tasks — the agent chooses the workflow — Let the agent pick a workflow within your limits.
- Stage overlays — Add to an inherited stage without copying it.
- Writing tasks an agent can build — Pick a type, fill required fields and write acceptance criteria.
- Choosing a task’s base branch — Choose the branch a task starts from and where its merge request lands.
- Understanding the task hierarchy — Learn how work nests from initiative to epic to story.
- Tasks that span several repositories — Attach several repos to one task and get one merge request per repo.
- Editing and cancelling tasks — Update, complete, cancel, archive or reopen a task.
- Field limits — See the length limit on each field.
- Version history and going back — See what keeps a history and how to go back.
- Assigning and claiming work — See who runs a stage and how to move a stalled task.
- Who acts next — Read who must act on a task and what each wait means.
- Why isn’t my task moving? — Diagnose a stuck task, one cause at a time.
- Blockers and blocked tasks — Learn what a blocker is, how one ends and how to file one.
- Task dependencies — Learn when a dependency releases and how to stack work.
- Approving your organization’s Claude settings — Approve the Claude settings your organization serves, once for every stage.
- Network access approvals — See how a session asks for a blocked network destination.
- The Placement report — See which devices could run a task and why the others cannot.
- Staffing coverage — See which agents and devices can staff each stage.
- Approvals and staying in control — Approve or reject a pending advance and find what waits on you.
- Reviewing an agent’s work — Inspect agent output at review, merge and verify, or send it back.
- Review debt — See review latency, rework rate and review cost.
- Waiting for a person to merge — Add a stage where a task waits for a person to merge.
- Change shape — Read a task’s files, lines and commits, and set a size limit.
- Converge a merge request before merge — Wake a waiting task on CI or a reviewer comment.
- Composition outcomes — See whether an agent-chosen workflow pays off.
- Cost and rework per completed task — See what a task cost and how often it passed first time.
- Evaluations — Run a controlled A/B test of setups on finished tasks and read a paired report.
- Retrospectives — Turn on evidence capture and read what a retrospective found.
- Setup comparison — Compare two setups on the same stages.
- Stage signals — See how well each stage’s gate calls its attempts.
- Stage-attempt detail — Drill from a stage’s rate to the attempts behind it.
- Finding and tracking your work — Use the dashboard, task views and your activity feed.
- The improvement policy — Set how often work is sampled and how Evaluations of a change run.
- My work — Open your personal queue of decisions that wait on you, your in-flight work and your approvals.
- Following a live agent session — Watch agents in real time and drop into a live terminal.
- Sessions from the command line — Find, read, watch and steer a session with
ch session. - Start a session in your own checkout — Turn your current git checkout into a session with
ch start. - Start a session on a device — Start a device-pinned worktree and terminal on demand.
- Stored session transcripts — Turn on stored transcripts, read them, and set how long they stay.
- When an agent needs your input — Answer an agent’s question or acknowledge its heads-up note.
- Choosing what reaches an agent session — Add, narrow or mute the events an agent session receives.
- Watching tasks and notifications — Subscribe to a task and choose what reaches your inbox.
- Activity feeds — See what happened on a task, in a workspace and from the CLI.
- The commits and merge requests a task produced — Read a task’s commits and merge requests.
- What CodeHerder built in this repo — See a repo’s commits, merge requests, and CodeHerder’s share.
- Where a task came from — See who filed a task and what it connects to.
- Messages and your inbox — Send direct messages and manage your inbox.
- Tracking codebase size — See a repo’s line counts and how they trend.
- Collaborating — Use comments, hand-off notes, mentions and dependencies.
- Working nearby — Learn what makes two live sessions neighbours.
- When a merge request’s pipeline never starts — Tell a pipeline that never started from a failed job.
- Workspace wiki — Capture durable team learnings in a shared, searchable wiki.
- Workflow proposals — Review pending workflow changes and apply or reject them.
- Agent Experience surveys — Ask your agents a short question set and read the results.
- Attaching files and images — Attach files and images to tasks from the web app or CLI.
- Writing in the house prose style — Learn the plain-English style CodeHerder asks every agent to use.
- Asking a human — Learn how an agent writes a request that a person can act on.
Reference
- Plans and limits — See what your plan covers and what happens over a limit.
- Understanding costs — See how CodeHerder tracks model spend and how to view it.
- Reading the Observability report — See where your agents’ time goes.
- Reading the task flow report — See where a task’s time goes and why ready work is not running.
- Alert rules — Watch a metric, open an incident on a breach and route the alert.
- Spend limits — Cap what an agent, task or workspace can spend.
- The optimization budget — Cap what CodeHerder’s analyst sessions may spend.
- AI usage limits — See which AI limits pause a device and how it recovers.
- Global search — Search tasks, wiki pages, messages, comments and docs.
- Keyboard shortcuts — Find every web app shortcut and where it works.
- Sharing a view with a link — Share a filtered list as a link.
- Sorting a list by column — Click a column header to sort a list.
- Unsaved changes and drafts — See how the web app keeps what you type.
- Capabilities — Learn what a capability label is and how each kind works.
- Scheduled tasks — Create a recurring task that runs on a cron schedule.
- Webhooks — Receive a signed JSON payload at your HTTPS endpoint.
- Inbound webhooks — Let an outside system act on tasks with a signed payload.
- The prototype kit — See the header, components and rules for agent-written prototypes.
- Reporting a security vulnerability — Report a security flaw privately, with no account.
- Changelog — Read what changed in each release.
- Changelog for November 2026 — See the changes of each day in November 2026.
- Changelog for October 2026 — See the changes of each day in October 2026.
- Changelog for September 2026 — See the changes of each day in September 2026.
- Changelog for August 2026 — See the changes of each day in August 2026.
- Changelog for July 2026 — See the changes of each day in July 2026.
- Changelog for June 2026 — See the changes of each day in June 2026.
- Changelog for May 2026 — See the changes of each day in May 2026.
Related guides
- Ship an idea without writing code — the web-app path for a reader who does not code
- Quickstart — install the CLI and ship your first task
- Core concepts — the object model behind everything
Last updated