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.
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-serverIn 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:
- The agent with the most capability overlap with the task.
- The agent with the cheaper model tier.
- The agent with more headroom on its AI provider quota.
- 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.
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.
- 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,lintandtypecheckchecks 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.
# 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.mdPosted comment 019f3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6dThis 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.