CodeHerderSearch⌘KRequest access →

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.

Say your workspace inherits the code stage from a parent group, and you want its agents to follow one extra rule. You could copy the stage into your workspace and edit the copy. Then you own that copy, and you stop getting changes to the original.

A stage overlay avoids that. It is a small set of additions that your workspace puts on top of a stage it inherits. The stage itself stays shared and keeps updating. Your additions ride along.

An overlay can add four things:

  • Additional instructions. Text added to the end of the stage’s prompt.
  • A model tier. haiku, sonnet or opus, for the agents that work this stage.
  • Extra skills. Skills the stage’s sessions get on top of its own list.
  • Extra verifications. Checks the stage runs, with a kind of test, lint, typecheck or goal-gate.

An overlay only adds. It has no setting for whether the stage can commit code, its image, isolation, environment or network access. Those stay as the stage defines them, so an overlay can’t loosen a stage.

Each workspace has at most one overlay per stage. The overlay applies to every workflow that uses that stage.

Overlay or configuration overlay?

The stage library page also mentions a configuration overlay. That one is different. It switches one verification on or off for one workflow. A stage overlay adds to a stage for your whole workspace. See Changing a stage’s verifications for one workflow for the other kind.

How layers stack

Overlays can exist at every level of your hierarchy. A group can have an overlay on a stage, and so can each workspace below it. CodeHerder applies them from the top group down to your workspace:

  • Instructions from every layer appear one after another. Each layer’s text sits under a heading that names the workspace it came from, such as “Additional instructions — Platform team”.
  • The model tier comes from the layer closest to your workspace that sets one. Layers that leave it as inherited don’t count.
  • Skills and verifications add up across layers. If two layers add a verification with the same ID, CodeHerder keeps the first and drops the later one.

Two cases where an addition has no effect:

  • An extra skill does nothing when the stage doesn’t narrow its skills. Such a stage already uses every skill your workspace has switched on. See Which skills a stage gets.
  • If your workspace owns its own copy of the stage, overlays set in the groups above it don’t apply. Your copy is the base. Your workspace’s own overlay still does.

A model tier sets what the stage needs from an agent, so an agent whose launch config covers that tier has to be available to work it. See Which model your agents run. CodeHerder can still move a stage to a stronger model after rework. See How work flows.

A change applies when CodeHerder starts the next session in that stage. It doesn’t reach a session already running.

Edit an overlay in the web app

Open Settings → Stages and click a stage. Its page has a Stage overlay section with these fields:

  • Additional instructions. Free text, up to 16 KiB.
  • Model tier. Choose a tier, or leave it on Inherited.
  • Extra skills. One skill slug per line, up to 64. Each must be a skill your workspace can see.
  • Extra verifications. A JSON array, up to 16 items. Each item has an id, a kind, a required flag and, for every kind except goal-gate, an optional command. A goal-gate check runs no command.
[
  { "id": "unit", "kind": "test", "required": true, "command": "make test" }
]

Choose Save changes to save. CodeHerder refuses the save if a skill is unknown, if an ID matches a verification the stage or an inherited overlay already has, or if a field is over its limit. The error names the field.

Delete removes the overlay, and the stage goes back to what it inherits. The overlay’s version history stays, so you can bring an earlier version back with the CLI (below).

An overlay written by an outside tool shows a managed by badge. The badge is a notice. You can still edit the overlay.

See the result

The same stage page has a Compiled prompt section. It lists the base prompt and each overlay in the order they apply, then what the stage ends up with: the model tier, the skills, the verifications, anything dropped, and the final prompt text. Check it after a change, and whenever a parent group’s overlay surprises you.

From the CLI:

ch stage compiled-prompt code

Manage overlays with the CLI

List every overlay your workspace has, or show one:

ch stage overlay show
ch stage overlay show code

Create or change an overlay with set. Pass the instructions in a file, not inline:

ch stage overlay set code --prompt-file extra.md --model-tier sonnet
ch stage overlay set code --skill go-style --skill sql-style
ch stage overlay set code --verifications-file extra-checks.json

set changes only what its flags name. The other parts of the overlay keep their value. So --model-tier haiku leaves your instructions alone. A few details:

  • --skill replaces the whole skill list. Repeat it for each skill. --clear-skills removes them all.
  • --verifications-file replaces the whole verification list, and an empty array [] clears it. --verifications takes the JSON directly, or - to read it from standard input.
  • --model-tier none goes back to inheriting the tier.
  • --change-note records a short note against the version.
  • --expected-version <n> makes the save fail if someone else changed the overlay since you read it. Without it, set still refuses a change that raced with another edit.

Every save is a new version. To see the history, or roll back:

ch stage overlay versions code
ch stage overlay revert code 2
ch stage overlay delete code

revert writes version 2’s content as a new version, so nothing is lost. It also brings back an overlay you deleted. You can’t revert to a version that records a delete. delete keeps the history too. revert runs the same checks as set. If version 2 names a skill that is gone, or a verification id that is now taken, the revert is refused with the reason, and nothing is written.

Who can do what

Any member of the workspace can read overlays and the compiled prompt. Changing an overlay (set, delete, revert, or Save changes in the web app) needs a workspace owner or admin. A credential tied to a running session is refused, even when its owner holds an admin role. A member without that role sees the overlay section read-only.

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