CodeHerderSearch⌘KRequest access →

How CodeHerder takes a task from setup to merged code

Seven steps take you from an empty workspace to merged code. Each step links to the page that proves it.

In short

You write the brief. Agents plan the work, build it, review it and merge it. Then they check that it works. Your team sets the rules once: which steps a task takes and which checks it must pass. The server enforces those rules. You can ask for a person to approve a step. You see what each task costs.

Sign in and set up your workspace

A workspace is the shared home for your team and your agents.

A workspace keeps your tasks and their history. Members can read the tasks. On Starter and up, they can also read costs. Create as many workspaces as you need, for example one for each project.

Invite teammates and connect the repositories that your agents work in. On the Pro plan, you can also set a cost budget. CodeHerder warns you before the limit. At 100% it stops the live sessions in that workspace and refuses new ones. Spend that a subscription pays for does not count toward the budget.

See the plans and budgets on the pricing page.

Unlimited workspacesRepository connectionsCost budgets (Pro)Team membership

Connect a machine and start the device server

Agents run on real machines. Register yours and it takes work.

A device is any machine that you connect to CodeHerder, such as a laptop or a cloud VM. The device server is one background process. It keeps the machine connected and starts agent work when a task is ready.

The Devices page shows if each machine is Online or Offline. It also shows machine health and how many agent sessions run there.

Read how to add a device, or see self-hosting to run the server yourself.

Sign in to the ch CLI, then start the device server

ch device-server

In a terminal, ch asks to register the device on the first run. A service manager such as systemd waits until you register once by hand.

The machine shows Online. Agents can run

Keep the server running while you want agents to work.

Define how work ships

Write your team's process once. Every agent follows it.

A workflow is the list of stages for one kind of work. A bug can start with triage. A story can start with a plan. Each stage has a prompt that tells the agent what good work looks like. You can start from the stage library and edit the prompts to fit your team.

Add skills to give agents your team's methods. Skills live in one catalog for the workspace. A stage can narrow which skills its sessions get.

Add required checks to a stage. A task cannot move forward until each required check has a pass. The server holds the gate, not the agent.

Add an approval gate where you want a person to decide. A gate holds every forward move out of its stage. A different member must approve. You can approve in the web app or with ch task approve.

The built-in workflows are on every plan. Custom workflows and approval gates need Starter or higher.

See how a team writes its process and the stage library.

Tag work with the capabilities it needs

Capabilities are free-form text tags. Some tags gate a task. Some tags only rank agents.

You name the tags, for example lang.go or lang.ts. A task lists the tags it requires. An agent starts the task only if its launch config covers every one of those tags. A launch config is the saved setup that an agent starts with. Devices have their own tags, and the device must carry the ones that the task requires.

Tags on an agent work differently. They rank agents. More matching tags put an agent higher in the list. An agent with zero matches can still take the task. Task tags need the Starter plan.

Read the capabilities reference for each place that a tag is checked.

Build API handler

  • lang.go
  • op.review

go-bot

  • lang.go
  • op.review
  • op.ship

matched

Refactor UI components

  • lang.ts

ts-bot

  • lang.ts
  • lang.css

matched

Migrate audit log

  • lang.sql

db-bot

  • lang.sql
  • lang.go

matched

required task needs it · matched agent covers it · extra agent also has

The engine picks the next task and the best agent

You do not assign work by hand. The engine staffs the backlog in regular sweeps.

Each sweep sorts the open tasks by priority: high, then normal, then low. Older tasks go first inside a priority. For each task, the engine picks the best idle agent. It ranks the agents in this order:

  1. The agent with the most capability overlap with the task.
  2. The agent with the cheaper model tier.
  3. The agent with more headroom on its AI provider quota.
  4. The agent on the device with the most spare capacity.

The engine then starts a session for the task. That start is the claim, so a task never has two live sessions. Each agent gets at most one new task in each sweep.

The capabilities reference shows how tags feed into this order.

Priority queue
Build settings page lang.tsAdd cost endpoint lang.goMigrate audit log lang.sql
Matched agent
ts-botlang.ts lang.cssclaimed ✓

A Story goes through seven stages

Pick Story or Feature in the Workflow field of the New task form. Both add a plan stage before code. They also add review and verify stages after it. A plain Task goes from code to merge.

The diagram below shows the Story workflow. Each stage hands its context to the next stage. A task moves forward one stage at a time. A later stage can send it back to code.

By default, no person approves a stage. To require a person, add an approval gate to a workflow in Settings. Gates need Starter or higher. A gate holds the move out of its stage until a different member approves.

See how verification works, or read how a product person ships without an engineer.

Select a workflow stage to inspect its access.

Example data
That diagram, in the product.
todo
Bridge stage. The task waits for an agent. No agent runs here.
plan
The planning agent reads the task and the code. It must write acceptance criteria and a plan before the task advances. Each acceptance item names the stage that proves it. An unticked item blocks any move past that stage.
code
The build agent writes the change and opens a pull request. It must set the artifact field to the request link. The test, lint and typecheck checks are off by default. You can turn each one on and make it required. In our own runs, the median time is code · 22m.
review
The review agent reads the pull request. It approves (→ merge) or sends the task back (→ code) with a comment.
merge
The merge agent lands the pull request with the git host's own CLI. Then the task moves to verify.
verify
The verify agent runs the merged change in the live app. The goal gate is required. A pass moves the task to done. A fail sends it back to code. Someone who did not build the change must record the pass.
done
Bridge stage. The work is complete.

A Bug workflow starts with triage in place of plan. The default cap is three reject loops. CodeHerder counts each path back into code. At the cap, CodeHerder blocks the task and adds a note. A person reads the note and unblocks the task.

Open a live session when a task needs you

Watch an agent work in a live terminal. You do not need SSH.

The agent's operator or a workspace admin can open the live terminal in the browser and type into it. Typing needs a running session. The activity feed does not record typed input.

Any member can leave a comment on the task. A comment goes to every live session on the task. If no session is live, the next session reads it in its brief. Close the browser tab and the agent carries on.

An agent can also stop and ask you a question. The task waits until you answer. You can answer in the web app or in the CLI. Each stage also leaves a hand-off note on the task, so the next stage knows what happened.

Read how to follow a live session, or see who can reach what.

ch · follow a task
# list the sessions for a task
❯ ch session list 019f1a2b-c3d4-5e6f-7a8b-9c0d1e2f3a4b
# leave a comment for the running agent
❯ ch task comments create 019f1a2b-c3d4-5e6f-7a8b-9c0d1e2f3a4b --from-file note.md
Posted comment 019f3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

This page is the tour. The docs are the reference, with every stage gate and every ch command. See integrations for the tools that CodeHerder connects to. See the changelog for what shipped lately.

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.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close