CodeHerderSearch⌘KRequest access →

A repository's project folder

The .codeherder folder holds a repo's workflows, stages, check commands, skills, and knowledge, and it shapes the tasks you run locally.

A .codeherder folder at the root of a repository holds a project’s own CodeHerder files. Commit it, and everyone who clones the repo gets them too.

The folder does two jobs:

  • It carries a team’s documents. Workflow and stage documents live next to the code they govern.
  • It is the home of local tasks. When you run a task on your own machine, the task reads its workflow, check commands, skills, and knowledge from this folder.

It’s not the same thing as .codeherder.env. See It’s not .codeherder.env below if that’s what you’re after.

Creating or adopting it

Run this from anywhere inside your checkout:

ch project init

The folder step is offline: no sign-in and no server request. ch project init looks at .codeherder in your repository root and does exactly one of these things:

  • Nothing there yet: it creates the folder and tells you to git add it.
  • A real folder already there: it leaves it untouched and reports what it found.
  • A leftover link from a torn-down session: CodeHerder sometimes leaves a symlink at this path after a sandbox is cleaned up. ch project init recognizes its own link, removes it, and creates a real folder in its place.
  • Anything else: a file, or a symlink to something CodeHerder didn’t create. It refuses and changes nothing, so you can sort out what’s there yourself.

ch project init never stages or commits your files in an existing repository. Stage and commit the folder yourself once it’s created:

git add .codeherder
git commit -m "Add project folder"

If the folder has no Git repository

In a folder without Git, ch project init first offers to set one up. It shows the files it found, asks you to confirm, and then creates a local repository with one initial snapshot. It adds no remote and uploads nothing. The offer works the same way as the one in ch task start. See If the folder isn’t a Git repository yet.

Without a terminal, ch project init can’t ask. It changes nothing and tells you to run ch start in a terminal to review and approve setup.

Check commands

After the folder step, ch project init looks for the commands your project already uses to test, lint, and typecheck. It reads these files and runs none of your code:

File Detected commands
Makefile make test, make lint and make typecheck, for each target the file defines
package.json npm run test, npm run lint and npm run typecheck, for each script the file defines
go.mod go test ./... for tests and go vet ./... for lint

For each kind of check, the first match in that order wins. CodeHerder lists what it found and asks you to confirm. If you agree, it saves the commands as an override of the code stage in .codeherder/stages/code.json:

Detected check commands for the code stage:
  code/test: make test
  code/lint: make lint
Wrote code stage override (version 1)

Two flags skip the question:

  • --checks saves the detected commands without asking.
  • --no-checks skips detection. CodeHerder prints “Check detection skipped.”

The two flags don’t combine. When there’s no terminal, or you pass --json, ch project init saves nothing. It lists what it found and asks you to pass one of the two flags.

Detection only fills in a missing command. It never replaces a command you already set, and it never makes a check required. When every detected command is already on the stage, it says “Detected check commands are already declared on the code stage.” When it finds nothing, it says “No check commands detected (Makefile, package.json, go.mod).”

Saving commands works on the local backend only. When you’re connected to a workspace, detection is skipped, and --checks is refused because it would change the code stage for every repository in the workspace. Use ch stage edit code there instead.

What goes in it

Your project’s files live in subdirectories of .codeherder. Make the ones you need:

Folder What it holds
workflows/ Workflow documents, one per task type.
stages/ Stage documents your workflows can reference. ch project init writes code.json here when you save detected checks.
skills/ One folder per skill, named for its slug, each with a SKILL.md file.
knowledge/ Wiki pages you write for the project. Agents in your local sessions can read them.
state/ CodeHerder’s own record of your local tasks.

A rubrics/ folder left by an older version is ignored. You can delete it.

Notes on three of these:

  • Skills. A skill you add starts off disabled. Run ch skill enable <slug> to turn it on. Enabling and disabling never edit the files in skills/. See Skills.
  • Knowledge. A page here is read-only to agents. If you save a page with the same slug through ch wiki write, your saved page wins. If you archive that page, the file in knowledge/ comes back. See Workspace wiki for how the wiki works.
  • State. CodeHerder creates state/ the first time a local command needs it, and it tells Git to ignore everything inside. Don’t commit it and don’t edit it by hand.

Document format

Each file is one JSON document. The preview rejects a file that does not match this format.

{
  "schema_version": 1,
  "kind": "stage",
  "key": "code",
  "label": "Code",
  "content_hash": "<64 hex characters>",
  "body": { "StageKey": "code", "Label": "Code", "Spec": { "prompt": "..." }, "Fields": [] }
}

Envelope fields

Field Required Meaning
schema_version yes Must be 1.
kind yes stage, workflow or wiki.
key yes Lowercase letters, digits and _. It starts with a letter and has at most 64 characters.
label yes The display name. It must match the label inside the body.
archived_at no A timestamp that marks the document archived. Leave it out.
requires no The documents this one needs. Each entry is {"kind": ..., "key": ...}.
content_hash yes The hash of the document. See below.
body yes The content. Its shape depends on kind. Unknown keys fail.

Body shape per kind

  • stage — StageKey, Label, Spec and Fields. These keys use Go case. StageKey and Label must match the envelope. Keys inside Spec use snake case, such as prompt and writable. This is not the {label, spec, fields} document that ch stage create --stage-file takes.
  • workflow — a composition: key, label, instances, fields and the other keys that ch workspace workflow composition prints. key and label must match the envelope.
  • wiki — {"file": "<OKF file text>"}.

The requires list

A workflow lists each stage that its instances use. A workflow that uses a stage from your workspace library needs that stage document in the folder too.

How content_hash is computed

  1. Copy the document and set content_hash to an empty string.
  2. Rewrite body with its object keys sorted. Keep array order and number text.
  3. Convert archived_at, if present, to UTC.
  4. Write the envelope as compact JSON. Keep the field order of the table above.
  5. Escape strings as Go json.Marshal does:
    • Write <, > and & as \u003c, \u003e and \u0026.
    • Write U+2028 and U+2029 as \u2028 and \u2029.
    • Keep all other non-ASCII characters as UTF-8.
    • Use no other escapes than the ones JSON requires.
  6. Take the SHA-256 of those bytes and write it as lowercase hex.

Get a valid file

Do not write the hash by hand. Export a document from the server:

ch stage show code --as-project-doc > .codeherder/stages/code.json
ch workspace workflow composition story --as-project-doc > .codeherder/workflows/story.json

Both commands print the document with no {data} wrapper. A local edit to the body changes the hash. After a local edit, recompute the hash with the steps above. Or edit the stage or workflow on the server, then export again. The --as-project-doc flag cannot combine with --json. A disabled stage still exports, with no archived_at.

Where these documents take effect

On your own machine, they shape every local task. A task created on the local backend uses CodeHerder’s built-in workflow for its type. CodeHerder then layers your workflows/ and stages/ documents on top, with your project’s version winning wherever the two overlap. This covers ch task start and ch task create when you aren’t signed in. It also covers either command with --local.

A task keeps the workflow it was created with. If you change a document later, create a new task to use the change.

Edit documents with ch

On the local backend, these commands read and write the files in the folder and keep a version history:

ch stage edit code --stage '{"spec":{"verifications":[{"id":"test","kind":"test","command":"make test","required":true},{"id":"lint","kind":"lint"},{"id":"typecheck","kind":"typecheck"}]}}'
ch stage versions code
ch stage revert code 1

The first command makes the test check required, with make test as its command. The verifications list replaces the stage’s whole list, so repeat every check you want to keep. See Required checks. A hand edit to a file shows up as a new version the next time CodeHerder reads it.

Preview a workflow offline

To see what a type composes to, run:

ch workflow show --offline --type story

Name whichever task type you want to look at, such as story, bug, or auto. If you name one that doesn’t exist, the error lists the ones you can choose from.

That command composes the workflow entirely on your machine, no sign-in required. It reads your working tree, so a document you’ve just saved is already picked up. You don’t need to commit it first. Committing is how you share it with your teammates.

To preview documents kept somewhere else, name the directory that holds them with --project-dir:

ch workflow show --offline --type story --project-dir ~/workflow-drafts

CodeHerder then reads only that directory, and ignores your checkout’s .codeherder folder. It picks up every .json file underneath, at any depth, and each one has to be a workflow or stage document. One stray .json file stops the command.

So name a directory that holds only those documents. Point the flag at one subdirectory, such as .codeherder/workflows, and it reads only that one. Your stage documents stay out of the preview. Don’t point it at the whole .codeherder folder: state/ holds .json files that aren’t documents, so the command stops.

On a connected workspace

Committing a project document does not change the pipeline a task runs on a connected workspace. The workspace keeps its own workflows and stages. To change what those tasks run, use Customising a task’s workflow or Customising workflows instead.

A parent folder of repos

A folder that is inside no git work tree, with git checkouts as immediate children, is a parent folder. See Start from a parent folder of repos. Its parts live here:

Part Location
Definitions <parent>/.codeherder/. A child checkout with no .codeherder of its own finds the parent’s one by the upward walk.
Runtime state ~/.codeherder/projects/<hash>/state, outside every repo.
Project file <parent>/.codeherder.env, beside <parent>/.codeherder/.

Runtime state is never in a repo, so CodeHerder writes no state ref, in any mode.

It’s not .codeherder.env

.codeherder (this folder) and .codeherder.env (a single file) share a name and both live at your repository root, but they do unrelated things. .codeherder.env sets your default server, workspace, and local-or-cloud setup for the ch CLI — see Project defaults for the CLI.

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