CodeHerderSearch⌘KRequest access →

Capabilities

What a capability label is, which things have capabilities, which things need them, and where each one is set.

Capability labels show up in several places in CodeHerder. One rule sits under all of them: a thing that supplies capabilities HAS them, and a thing that needs capabilities lists them as required. Launch configs and devices have capabilities. Tasks, schedules, workflow stages, Evaluations and agents (through their device requirements) need them. This page tells you which rule applies where.

What a capability is

A capability is a short, free-form label. You pick labels that match your own habits. Common examples are go, frontend and op.review. One convention is built in: model:<tier>, where the tier is haiku, sonnet or opus, in rising order of capability and cost. Use model:<tier> labels to say which AI model a launch config runs. For the rest of the model story, see Which model your agents run.

Devices use a second kind of label. A device reports tokens such as bin:claude or auth:github. These say what the machine can do. They are covered under What a device advertises.

Two kinds of capability

Agent work and device placement use two separate sets of labels. Don’t mix them up:

  • Agent capabilities say what a launch config can run. Tasks, schedules and stages ask for them with --cap.
  • Device capabilities say what a machine can do. Tasks, schedules and agents ask for them with --device-cap or --device-requirement.

Agents have no capability labels of their own. An agent gets its capabilities from its launch configs.

Launch-config capabilities

Set with ch agent config edit <agent-id> --cap <label>, or ch agent config create for an additional config. --cap replaces the config’s whole capability list, so include every capability you want to keep. config edit changes only the flags you pass, so the rest of the config stays as it was. It edits the agent’s first launch config. Use config create and config reorder to manage more than one.

ch agent config edit <agent-id> --cap model:opus --cap model:sonnet

Passing --harness also resets the config’s command to that harness’s default.

You can set the list when you create the agent, in the same call, with --config-cap:

ch agent create --display-name "Builder" --harness claude --config-cap model:opus --config-cap model:sonnet

See Creating a runnable agent in one call for the full flag set.

Launch-config capabilities do two jobs:

  • A hard gate. CodeHerder runs a workflow stage only on a launch config whose capabilities cover everything the stage requires. A config counts only when it is enabled, its agent is enabled and not archived, and a device in your fleet has the CLI its harness needs. Claude needs no special CLI. Agents in a parent group count too. If no config qualifies, that stage is unstaffable. See Staffing coverage for what happens to tasks that reach it.
  • A soft ranking. When CodeHerder staffs an unassigned task, it ranks agents by how much the capabilities of their enabled launch configs overlap with the task’s required capabilities. More overlap ranks higher. Zero overlap never blocks a task. It still runs on the best available agent.

Covering a whole workflow. Different stages need different capabilities. The built-in feature, story and bug types need both the model:opus and model:sonnet tiers across their stages. One launch config can carry both tiers. You can also split them across configs, one per tier. CodeHerder uses whichever enabled config covers a given stage. See Agents and the CLI for the setup walkthrough.

Stage required capabilities

A stage’s required capabilities are the list a launch config must cover before CodeHerder runs that stage on it. They are the other side of the launch-config gate. For a composed workflow, which every built-in type is, the stage lives in the shared stage library. The workflow editor shows the list read-only, with a link to edit it at the library stage. A hand-written workflow keeps the list in its own definition, edited through the CLI. See Customising workflows.

Task and schedule required capabilities

Set with ch task create --cap <label> or ch schedule create --cap <label>. Repeat the flag for more than one. These describe what the task, or the tasks a schedule creates, needs.

ch task create --title "Write Go migration" --type story --cap go --cap model:opus

This is a hard gate. Only a launch config that covers every one of these capabilities can run the task. CodeHerder combines the set with each stage’s own capabilities as the task moves through the workflow. See Writing tasks an agent can build for the rest of task creation.

To change the set later:

ch task edit <taskId> --cap <label>...
ch task edit <taskId> --clear-caps

--cap replaces the task’s whole set. --clear-caps empties it. You can’t use both on one call. A schedule works the same way with ch schedule edit.

The create-time check

When you create a task, with or without --cap, CodeHerder checks every stage the workflow can hand to an agent. When you edit a task, the check runs only if you pass --cap or --clear-caps. For each stage, the stage’s capabilities plus your set must be covered by one enabled launch config. If a stage isn’t covered, the request is refused and names the stage. The check runs once your workspace has at least one launch config.

What a device advertises

A device advertises a set of capability tokens. The set is the union of two sources:

  • Detected automatically. The device checks itself and reports what it finds. Examples are bin:<name> for a tool on its PATH (the coding-agent CLIs, git, gh, glab, node, docker and others), auth:github or auth:gitlab when gh or glab is signed in or the device holds a write token for that host, auth:github:read or auth:gitlab:read when the device holds a read token for it, and stage-docker when its container check passes. A device can carry both the write and the read token for one host. See Git tokens on a device. A device re-checks about every five minutes, and at once when you restart ch device-server. ch device show also lists other detected tokens, such as auth:<harness>, tool: and env: tokens.
  • Labels you add. Operator labels are free-form. Use them for things CodeHerder can’t detect, such as gpu or region:eu. A reconnect never clears them.

Set operator labels with ch device edit. --cap replaces the whole set and --clear-caps empties it. A device holds up to 20 operator labels. Detected tokens don’t count toward that limit. You can also edit the labels on the device page.

ch device edit <device> --cap gpu --cap region:eu
ch device edit <device> --clear-caps

To see both sets, run ch device show <device>. The operator capabilities row appears when you have set labels. The probe capabilities row shows what the device detected. On the web, the device page has an Operator capabilities section and a Probe-derived capabilities section. See Managing your devices for the rest of device setup.

Task and schedule device capabilities

Set with ch task create --device-cap <token> or ch schedule create --device-cap <token>. Repeat for more than one. A task with device capabilities starts only on a device that advertises every token.

ch task create --title "Train the model" --type story --device-cap gpu
ch task edit <taskId> --device-cap gpu --device-cap region:eu
ch task edit <taskId> --clear-device-caps

This is a hard placement gate. It doesn’t depend on your plan. CodeHerder doesn’t check at create time that any device advertises the token. A typo is accepted, and the task then has no device to run on. Use ch task placement to see why no device fits. In the web app, the New task form has an Agent capabilities field and a Device capabilities field. The task page shows both read-only.

Agent device requirements — hard

Set with ch agent edit <agent> --device-requirement <token>, repeated for more than one. Use --clear-device-requirements to remove them all. This answers a different question from the launch-config gate: which machine may this agent run on at all. You set it on an existing agent. ch agent create doesn’t take it. Changing it needs a workspace admin or owner who is a person. An agent session can’t change it. It has no web editor, so use the CLI. ch agent show prints the current requirements. A change re-checks waiting work at once.

ch agent edit "Builder" --device-requirement bin:claude

CodeHerder places a session for this agent only on a device that reports every required token. A device missing one is skipped for that agent’s work. CodeHerder also adds the tokens the agent’s harness needs, such as bin:codex for Codex, and the git host’s auth: token for a stage that writes to the host. See Editing an agent for the full agent edit flag set.

Soft vs. hard, at a glance

Where it’s set Command Effect
Launch config ch agent config edit <agent-id> --cap <label> Hard: a stage runs only on a config whose capabilities cover it. Soft: the same capabilities rank agents for unassigned tasks.
Workflow stage Library stage, or the workflow definition for a hand-written type Hard: the requirement side of the launch-config gate
Task / schedule ch task create --cap <label> Hard: a launch config must cover every label, together with the stage’s own
Task / schedule device ch task create --device-cap <token> Hard: the task starts only on a device that advertises every token
Device ch device edit <device> --cap <label> Supplies labels, on top of what the device detects
Evaluation requiredDeviceCapabilities in the definition, see Pin it to devices Hard: an attempt runs only on a device that advertises every token
Agent device requirement ch agent edit <agent> --device-requirement <token> Hard: restricts which devices the agent’s sessions use

Launch-config capabilities and task or schedule --cap need the Starter plan. Device capabilities and device requirements don’t. See Plans and limits.

When capabilities stall a task

A task that waits with no agent picking it up has one of these causes:

  • A stage’s capabilities aren’t covered by any enabled launch config. The web app’s Capability gap callout on Set up → Agents lists up to five uncovered stages and what each needs. The Staffing panel below it shows the rest.
  • The task’s own capabilities aren’t covered. The create-time check catches this when you create or edit the task. A stall can still happen later. Typical reasons are that someone edited, disabled or archived a launch config after the task passed, or that you created the task before any launch config existed.
  • No device fits. The task’s device capabilities, the agent’s device requirements or the stage’s needs rule out every device. Run ch task placement <taskId> to see why.

How you see it. A task whose required capabilities no launch config can satisfy shows a Start refused badge next to its title, on the task list and on the task page. The task page also has a Start refused row with the reason, the attempt count, and when it started and last failed. ch task show <taskId> prints the same row, and --json carries it as startRefusal.

To fix it, add the missing capability to a launch config (see Agents and the CLI). Or repair the task with ch task edit <taskId> --cap <label>... or --clear-caps.

For the full diagnostic walkthrough, see Why isn’t my task moving?. For the Capability gap callout, see Monitoring your agents. To see which tokens your fleet advertises and which stages they cover, see Staffing coverage.

Last updated

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