Config & permissions
How cckit finds its config, reads what kind of project it is pointed at, and asks before it changes anything — all without a single hardcoded org, repo, or path.
Config resolution (nearest wins)
Section titled “Config resolution (nearest wins)”cckit runs in the directory you invoke it from. It finds the config for that project by walking upward from the current folder and taking the first match.
| Order | Source | What it is |
|---|---|---|
| 1 | $KIT_CONFIG | An explicit path in the environment. Always wins. |
| 2 | cckit.config.json | The project config at (or above) the repo root. |
| 3 | .claude/kit.config.json | The config a kit-scaffolded project keeps under .claude/. |
| 4 | cckit’s own config | The fallback when you run outside any project. |
No org, repo, or path is hardcoded — every value comes from this file. A repo with no config is invited to run cckit init.
Where these live on disk
Section titled “Where these live on disk”Sources 2–4 are files; source 1 ($KIT_CONFIG) is an environment variable, so it isn’t in the
tree. Everything cckit writes about you — consent, identity — lands in .cckit/, which is
gitignored, so it never leaves your machine.
Directoryyour-repo/
- cckit.config.json source 2 · repo, owner, base branch — nothing hardcoded
Directory.claude/
- kit.config.json source 3 · a kit-scaffolded project’s config
- … agents, hooks, rules, skills
Directory.cckit/ gitignored — cckit’s local state, never committed
- consent your recorded yes to mutate this repo
- identity your name, asked once on first run
- privacy-denylist extra paths the secret guard must block
- … your existing files, untouched
Project scanning
Section titled “Project scanning”cckit detects the project it is pointed at from the filesystem, not from baked-in knowledge. Run it yourself to see what cckit sees:
cckit scan --llmIt reads three things:
- The repo root —
git rev-parse --show-toplevel. - Stack hints —
package.json,pyproject.toml,go.mod,Cargo.toml. - Kit state —
cckit.config.json,.claude/,.cckit/.
The permission gate (ask before operating)
Section titled “The permission gate (ask before operating)”cckit asks before it changes anything in a repo it has not worked in before.
- Read-only by default in an unknown repo. Before the first mutating operation, cckit records your consent in
.cckit/consent(gitignored). - The secret and privacy guard always runs before anything is committed or published. It is not optional and consent does not bypass it — see Security.
- Destructive or irreversible operations (force-push, repo create, history rewrite) always require a separate, explicit confirmation.
Captain merge policy
Section titled “Captain merge policy”cckit watch --merge is the one place cckit lands code without a human in the loop, so its policy is
config, not code. Everything below lives under captain.mergePolicy in the config file resolved
above, and every key has an environment override that always wins — so you can opt in or out for
a single invocation without editing the file.
| Key | Default | What it does | Env override |
|---|---|---|---|
floors | true | Refuse to auto-merge a PR that touches .github/workflows/**, a lockfile or dependency-graph file, or a security-sensitive path — and always honour a hold label. Verdict becomes HELD. | KIT_CAPTAIN_FLOORS=0 |
protectedGlobs | [] | Extra path globs added to the floors above. | KIT_CAPTAIN_EXTRA_GLOBS |
requireChecks | false | Treat a PR with no checks at all as unverified rather than green. Verdict becomes CHECKS_MISSING, action verify. | KIT_CAPTAIN_REQUIRE_CHECKS=1 |
requireReview | (implied) | Treat a PR with no agent review recorded as unverified. Verdict becomes REVIEW_MISSING, action verify. Defaults to on when review.command is set and off when it is not — set it explicitly to break that link either way. | KIT_CAPTAIN_REQUIRE_REVIEW=1 |
Why requireChecks exists
Section titled “Why requireChecks exists”The captain decides from three things GitHub reports about a PR: whether it merges cleanly, its merge state, and its check rollup. When that rollup is empty there is nothing to read — and an empty rollup is not a pass, it is the absence of evidence. Read as green, it means a repo with no CI is auto-mergeable by construction: “the gates are green” was never observed, only assumed.
Turn requireChecks on and that case gets its own verdict, distinct from the two that already exist:
| Verdict | Action | What actually happened |
|---|---|---|
CHECKS_FAILING | fix | Something ran and went red. |
CHECKS_PENDING | wait | Something is still running — come back. |
CHECKS_MISSING | verify | Nothing ran. There is no evidence to wait for. |
It also closes a smaller race: a PR gated in the seconds before CI registers has an empty rollup too,
so with requireChecks on the captain waits for the checks to appear instead of merging into the gap.
The agent review stage
Section titled “The agent review stage”The captain can run an agent over a pull request before it merges, and refuse to merge on what that agent finds. It is off until you name the command that runs a reviewer:
{ "review": { "command": "claude -p", "timeoutSeconds": 900 } }cckit pipes a brief to that command’s stdin and reads the reviewer’s report off its stdout.
That report becomes a stage receipt at stage review, written locally and
mirrored onto the issue.
The command also receives the resolved profile in its environment, so it can dispatch the agent the
issue’s agent: label actually asked for rather than a fixed one:
| Variable | What |
|---|---|
CCKIT_REVIEW_PROFILE | the resolved profile name |
CCKIT_REVIEW_KIND | its kind (the agent executable) |
CCKIT_REVIEW_ARGS | its args, one per line |
CCKIT_REVIEW_PR / CCKIT_REVIEW_ISSUE / CCKIT_REVIEW_REPO | what is being reviewed |
A command that ignores all of them still works.
timeoutSeconds (default 900) bounds the run. The captain is unattended and single-threaded, so a
reviewer that never returns blocks the whole pass — every other PR in it included — with nobody
watching. On expiry the process is killed and no receipt is written: a killed reviewer is not a
verdict. A non-numeric or zero value falls back to the default rather than disabling the bound.
What gets reviewed, and when
Section titled “What gets reviewed, and when”A PR is dispatched to a reviewer only when the captain would otherwise merge it. One that conflicts, fails a check or is still a draft is going to change before anyone should read it, and a PR already stopped by a policy floor belongs to a human who does not need a second opinion first.
After a dispatch the PR reads verify for the rest of that pass — whether or not the reviewer
succeeded. The verdict is gated on the next pass, once it is recorded. A review that is still
running is not a review that passed.
The reviewer never writes
Section titled “The reviewer never writes”A review profile must not touch the branch it is reviewing. Three things hold that:
writedefaults tofalseon every profile, and a profile withwrite: trueis refused at the review stage rather than trusted to behave.orchestrateleases each branch to one writer, so a second writer is refused anyway.- The brief says READ ONLY in as many words.
The first is the one that matters — the other two are downstream of a profile you already declared able to write.
A verdict belongs to one commit
Section titled “A verdict belongs to one commit”Each review receipt records the PR head it was produced from, and the gate compares it against the
current head. Push a new commit and the previous verdict reads as absent, not as a pass — the
reviewer read code that is no longer there. That applies to a fail too: a stale finding is not a
finding against the new revision.
That is also what makes the loop terminate. A PR with a REVIEW_FAILING verdict is not re-reviewed
on its own; the author acts on the finding and pushes, which moves the head, which makes the verdict
stale, which earns the next review.
The two verdicts
Section titled “The two verdicts”| Verdict | Action | What happened |
|---|---|---|
REVIEW_FAILING | fix | The reviewer ran and said gate: fail. |
REVIEW_MISSING | verify | No review recorded. |
REVIEW_FAILING always blocks. A recorded failure is evidence, so no configuration switch
turns it off — if you disagree with a verdict, record a new one.
REVIEW_MISSING is the same shape as CHECKS_MISSING: the absence of evidence, which is the
state of every repository that has not run a reviewer yet. Requiring it unconditionally would stop
every captain everywhere the moment you upgraded, so it blocks only when review is required.
Worktree bootstrap
Section titled “Worktree bootstrap”cckit start <issue> and cckit effort start <N> make a fresh worktree runnable before you touch it:
they copy the gitignored .env.local* files and project ids a new checkout can’t inherit, assign a
per-worktree dev PORT per app, and install dependencies — node_modules is per-worktree, never
shared. Every step is best-effort: a hiccup prints and moves on, it never fails the start.
Where the install runs
Section titled “Where the install runs”The install step decides from your project, in this precedence — the first rule that applies wins, and the ones below it are never consulted:
-
worktree.installPathsis set → install in exactly those directories, and only those. The root and workspace checks below are skipped entirely;[]means install nothing. -
Otherwise, the worktree root — but only when its
package.jsondeclares at least one dependency (independencies,devDependencies,optionalDependenciesorpeerDependencies), or it is a workspace root with at least one member (pnpm-workspace.yamlwhosepackages:lists a pattern, or — inpackage.json— a non-emptyworkspacesarray or a non-emptyworkspaces.packagesarray). A workspace root holds its members’ deps, so the install there is real work. Aworkspacesobject whosepackageslist is empty counts as memberless, however many other keys it carries. -
Otherwise nothing — the start prints
no dependencies declared — skipping pnpm install.
Rule 3 is the point. A root manifest with no dependencies has nothing to resolve, but pnpm would
still write an empty pnpm-lock.yaml (importers: { .: {} }) — a file that then trips the
captain’s own lockfile policy floor and holds the PR for human review. cckit
itself is exactly this shape: a published bash CLI with zero dependencies whose only Node project is
docs-site/.
The “at least one member” clause in rule 2 matters for the same reason: packages: [],
"workspaces": [] and "workspaces": {"packages": []} all look like workspace roots but declare
nothing, so installing at them lands right back on the empty lockfile.
Installing somewhere other than the root
Section titled “Installing somewhere other than the root”When your Node project lives in a subdirectory, name the directories under worktree.installPaths in
the config file resolved above:
{ "worktree": { "installPaths": ["docs-site"] }}| Key | Default | What it does | Env override |
|---|---|---|---|
worktree.installPaths | (unset — fall through to rule 2) | Worktree-relative directories to run pnpm install in. Wins over rules 2–3; [] installs nothing. | — |
worktree.devPorts | [] | {path, base} per app: the per-worktree dev PORT written into that app’s .env.local. | — |
worktree.devPortStride | 10 | Distance between one worktree’s port block and the next. Every app’s base must sit inside one stride-wide window. | — |
| — | install on | Skip the dependency install entirely for one invocation. | KIT_WT_INSTALL=0 |
| — | 10 | Seconds cckit start waits for the port-slot ledger lock before allocating unserialized. | _WT_LOCK_WAIT |
PR conventions
Section titled “PR conventions”cckit pr follows the repo’s PR convention, set under pr in the config file:
{ "pr": { "titleStyle": "issue-title", "orchestratorSection": true }}| Key | Default | What it does |
|---|---|---|
pr.titleStyle | conventional | conventional: a Conventional Commits title derived from the issue’s kind label, which release-please and a commitlint gate read. issue-title: the issue title, verbatim. |
pr.orchestratorSection | false | true opens the PR body with a two-line ## For the orchestrator section: the issue number and what to review. |
Effort WIP limit
Section titled “Effort WIP limit”cckit effort start refuses to start a new effort once too many are already in progress. The
counted set is the efforts whose effort/<N>-<slug> branch exists — a local head or a branch
origin has right now, read with git ls-remote rather than the cached refs/remotes. Set the
ceiling in the config file resolved above:
{ "effort": { "wipLimit": 3 }}| Key | Default | What it does | Env override |
|---|---|---|---|
effort.wipLimit | 2 | How many efforts may be in progress before cckit effort start refuses a new one. At the limit refuses; only strictly under it starts. 0 refuses every ordinary start — a forced one still runs. A value that is not a non-negative integer is ignored with a warning and the default 2 is used. | EFFORT_WIP_LIMIT |
| — | gate on | Start anyway, past the limit. Flag or env — either alone is enough. | --force, or KIT_FORCE=1 |
| — | origin queried | Skip the git ls-remote origin query; count local heads + cached refs/remotes instead. An unreachable origin falls back to the same cached refs, warns once on stderr, and the start proceeds. | EFFORT_WIP_REMOTE=0 |
Resolution order, first non-empty wins: EFFORT_WIP_LIMIT in the environment →
KIT_EFFORT_WIP_LIMIT (what load_kit_config exports from effort.wipLimit) → effort.wipLimit
read straight from the config file → the built-in default 2.
The check runs before the base-branch fetch, the branch, the worktree and the bootstrap, so a
refusal leaves no branch, no worktree and no board change. It is not read-free: the gate queries
origin, and a <slug> argument was resolved before it, which can run gh issue list. Re-running
cckit effort start on an effort that is already in progress is never gated — it adds no WIP.
cckit start <issue> (a plain task worktree) has no WIP limit. Full behaviour:
Only so many efforts at once.
Agent profiles
Section titled “Agent profiles”A profile is a named agent configuration: which CLI to run, roughly what it costs, under which permissions, and at which stages.
cckit never names a model. A kit that suggests an expensive model in its own config schema
pushes every user toward spending more, which is the opposite of the point. You spell your own
flags in args; the only cost signal cckit reads is tier, and the cheapest profile is what runs
when nothing else is chosen.
{ "agents": { "stages": ["build", "review", "design", "docs"], "profiles": { "cheap": { "kind": "claude", "tier": "low", "stages": ["build", "review"], "write": true }, "deep": { "kind": "claude", "tier": "high", "permissions": "acceptEdits", "stages": ["build"], "write": true, "contextBudget": 8000, "args": ["--model", "<whatever your CLI calls it>"] } } }}| Key | Default | What it does |
|---|---|---|
agents.default | the cheapest profile | Profile used when nothing more specific resolves. Leave it unset — the lowest-tier profile then wins, so the inexpensive path is the default by construction. Naming a profile that is not declared is a validation error, not a silent fallback. |
agents.stages | build review design docs | The stage vocabulary a profile’s stages are checked against. Env override: CCKIT_AGENT_STAGES. |
kind | required | The agent CLI to run (claude, codex, …). The Herdr runtime validates it before any worktree exists. |
tier | low | What this profile is expected to cost relative to the others: low, mid, high. Unstated means low — assuming the cheap end is the safe direction to be wrong in. |
args | [] | Extra CLI arguments as an argv array, never a shell string, so an argument containing spaces is not re-split. Your model selection goes here, spelled the way your CLI spells it. Passed through on both runtimes — Herdr receives the array after its --, tmux gets it quoted onto the pane’s command line. |
permissions | (unset) | Permission/sandbox policy, forwarded to the CLI that implements it and recorded in the stage receipt. |
stages | (none) | Stages this profile may run at. A profile with no stages is allowed nowhere — an unstated permission is not a granted one. |
write | false | Whether the profile may write to a branch. One writer owns a branch at a time; review profiles stay read-only until ownership is transferred. |
contextBudget | (unset) | Upper bound in bytes on the whole prompt the worker receives. See Bounding a worker’s prompt. Unset, 0, or non-numeric means unbounded. |
Validation runs before a worktree or pane is created, and refuses on: an undeclared profile, a
profile with no kind, a stages entry outside the vocabulary, a profile selected for a stage it
does not list, and an agents.default that names nothing declared. Each refusal names the profile
and prints what was declared, so the fix does not require reading the source.
Which profile runs a given issue
Section titled “Which profile runs a given issue”Resolution walks four levels, highest first, and stops at the first that supplies a name:
| # | Level | Where it comes from |
|---|---|---|
| 1 | Command override | the flag on this invocation |
| 2 | Issue label | agent:<profile> on the issue itself |
| 3 | Parent effort label | agent:<profile> on the parent effort |
| 4 | Project default | agents.default, or the cheapest profile when that is unset |
scripts/setup-labels.sh provisions one agent:<profile> label per profile the config declares, so
the family stays bounded by the config rather than growing one label per issue.
Two refusals are deliberate, because both would otherwise run an agent nobody chose:
- Two different
agent:labels on one issue is ambiguous and refuses. It does not pick one. - The resolved name is validated against the stage before it is returned. An explicit
agent:reviewlabel on abuildstage is refused, not honoured — so a rc-0 result is always launchable and a caller never re-checks.
When nothing resolves at all — no override, no label, no agents.default — that is its own distinct
failure, separate from “a profile was named and rejected”, so the message can tell you which of the
two happened.
Bounding a worker’s prompt
Section titled “Bounding a worker’s prompt”A headless worker gets one prompt and no chance to ask for more. contextBudget caps that prompt in
bytes, so a large brief cannot spend the worker’s window before it has read a line of code.
The prompt is assembled in four parts, and only one of them competes for the budget:
| Part | Cut? | What it is |
|---|---|---|
| Headless framing | never | there is no human here; work only on this issue; do not read the board |
| Brief metadata | never | worktree, branch, seed freshness, and the gate command — where to work and what must pass |
| Brief sections | yes | ## Files this issue owns, ## Helpers you already have, ## Standing gotchas, ## Durable prose |
| Receipt contract | never | outcome · url · gate · blocker · next stage |
Sections are dropped whole, from the end, and the prompt then says which ones went and how to read them:
_2 section(s) omitted to fit this profile's contextBudget: Standing gotchas, Durable prose.Read them with `cckit brief`._Dropping whole sections rather than truncating mid-sentence, and naming the cut rather than making it silently, are the same decision: a partial brief has to read as partial. A worker handed a brief that looks complete acts as though it is.
The order is not arbitrary — the sections the worker cannot reconstruct come first. What the issue owns is unrecoverable from anywhere else; the standing gotchas are a rule file the worker can open on its own.
A budget too small to hold the four uncuttable parts emits them anyway and warns on stderr. A worker that overran a number is recoverable; one with no receipt contract reports in a shape nothing can parse, and the receipt is the only durable record of the run.
The board and prior conversations are never included, at any budget — including unbounded.
Stage receipts
Section titled “Stage receipts”A worker’s pane is not a record. It dies with the pane, it does not survive a Herdr server restart, and nothing can query it — and pane history, which might preserve it, is off by default and can hold secrets, so cckit must never depend on it.
So the worker records its own receipt, through a verb:
cckit receipt 321 --stage build <<'RECEIPT'outcome: pr-openurl: https://github.com/jeiemgi/cckit/pull/999gate: passblocker: nonenext stage: reviewRECEIPTOne JSON file per attempt, under .cckit/receipts/, keyed <issue>-<stage>-<attempt>. The
directory resolves from the repo’s shared git dir, so a receipt a worker writes inside its own
isolation worktree is readable by a captain standing anywhere else.
cckit receipt list 321 # 321 build 1 blocked # 321 build 2 pr-open # 321 review 1 mergedcckit receipt show 321 build # the latest attempt's JSONEvery receipt is also posted as a comment on its issue. .cckit/ is gitignored and
per-machine, so a receipt that lived only there dies with the clone — and effort-model.md opens
with “GitHub is the single source of truth”. The local file stays: it is what lets receipt list
and receipt show answer offline, with no network round trip per read. The comment is the second
copy, not a relocation.
The comment carries an invisible marker keyed to the same <issue>-<stage>-<attempt>, so a re-run
edits that attempt’s comment rather than appending a second one — the same guarantee the local
file gives. A new attempt gets its own comment.
cckit receipt 321 --stage build --no-remote <<'RECEIPT' # write the file, post nothingThe mirror is best-effort, and the local write has already succeeded before it runs: a failure
warns on stderr and the command still exits 0. --no-remote, or CCKIT_RECEIPT_REMOTE=0, skips it
outright. One case deliberately does nothing rather than degrade — if the comment lookup itself
fails, cckit does not post, because a blind post is exactly how a duplicate record appears.
Alongside the five reported fields, each receipt records the resolved profile, its tier, where
it was resolved from, and its permissions — so a run’s effective agent and policy are auditable
after the fact.
Re-running the verb with the same five values rewrites its own attempt instead of recording a second one, which is what makes it safe to retry after an unknown result. A re-run that says something different is a real second try and takes the next number, so neither record is lost.
A value outside its vocabulary is recorded and flagged, not refused. Refusing would make two states look identical:
| What happened | Refuse | Record + flag |
|---|---|---|
| Agent crashed | no receipt | no receipt |
Agent finished, wrote outcome: shipped | no receipt | outcome: shipped · invalid: ["outcome"] |
The first needs the stage re-run; the second has a PR sitting there and just used a word outside
the list. Keeping the value preserves the difference, and receipt list shows the flag so a wave
scan cannot miss it. The one hard refusal is a report with no outcome: line at all — that is
not an odd receipt, it is no receipt.
Nothing is verified against GitHub. The receipt says what the worker reported; the captain already reads PR state before it merges anything, so checking here would ask GitHub the same question twice and would break an offline run.
Identity
Section titled “Identity”cckit asks your name on first run and stores it in .cckit/identity (gitignored). Nothing personal is hardcoded; commits use your local git identity.
Independent, educational project — not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic PBC.Disclaimer & trademarks ·
From Mexico withloveby josegtz