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 addit. - 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 initrecognizes 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:
--checkssaves the detected commands without asking.--no-checksskips 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 inskills/. 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 inknowledge/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,SpecandFields. These keys use Go case.StageKeyandLabelmust match the envelope. Keys insideSpecuse snake case, such aspromptandwritable. This is not the{label, spec, fields}document thatch stage create --stage-filetakes. - workflow — a composition:
key,label,instances,fieldsand the other keys thatch workspace workflow compositionprints.keyandlabelmust 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
- Copy the document and set
content_hashto an empty string. - Rewrite
bodywith its object keys sorted. Keep array order and number text. - Convert
archived_at, if present, to UTC. - Write the envelope as compact JSON. Keep the field order of the table above.
- Escape strings as Go
json.Marshaldoes:- Write
<,>and&as\u003c,\u003eand\u0026. - Write U+2028 and U+2029 as
\u2028and\u2029. - Keep all other non-ASCII characters as UTF-8.
- Use no other escapes than the ones JSON requires.
- Write
- 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.
Related guides
- Run a task on your own machine — local tasks, which read this folder
- Skills — write and enable the skills in
skills/ - Workspace wiki — the wiki that
knowledge/pages join - Project defaults for the CLI — the
.codeherder.envfile, not this folder - Customising a task’s workflow — the way to actually change the pipeline a task runs
- Customising workflows — change a whole type’s default workflow
- The stage library — browse and author the shared stages your workflows are built from
Last updated