Skip to content

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.

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.

OrderSourceWhat it is
1$KIT_CONFIGAn explicit path in the environment. Always wins.
2cckit.config.jsonThe project config at (or above) the repo root.
3.claude/kit.config.jsonThe config a kit-scaffolded project keeps under .claude/.
4cckit’s own configThe 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.

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

cckit detects the project it is pointed at from the filesystem, not from baked-in knowledge. Run it yourself to see what cckit sees:

Terminal window
cckit scan --llm

It 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.

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.

KeyDefaultWhat it doesEnv override
floorstrueRefuse 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
requireChecksfalseTreat 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

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:

VerdictActionWhat actually happened
CHECKS_FAILINGfixSomething ran and went red.
CHECKS_PENDINGwaitSomething is still running — come back.
CHECKS_MISSINGverifyNothing 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 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:

VariableWhat
CCKIT_REVIEW_PROFILEthe resolved profile name
CCKIT_REVIEW_KINDits kind (the agent executable)
CCKIT_REVIEW_ARGSits args, one per line
CCKIT_REVIEW_PR / CCKIT_REVIEW_ISSUE / CCKIT_REVIEW_REPOwhat 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.

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.

A review profile must not touch the branch it is reviewing. Three things hold that:

  • write defaults to false on every profile, and a profile with write: true is refused at the review stage rather than trusted to behave.
  • orchestrate leases 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.

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.

VerdictActionWhat happened
REVIEW_FAILINGfixThe reviewer ran and said gate: fail.
REVIEW_MISSINGverifyNo 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.

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.

The install step decides from your project, in this precedence — the first rule that applies wins, and the ones below it are never consulted:

  1. worktree.installPaths is set → install in exactly those directories, and only those. The root and workspace checks below are skipped entirely; [] means install nothing.

  2. Otherwise, the worktree root — but only when its package.json declares at least one dependency (in dependencies, devDependencies, optionalDependencies or peerDependencies), or it is a workspace root with at least one member (pnpm-workspace.yaml whose packages: lists a pattern, or — in package.json — a non-empty workspaces array or a non-empty workspaces.packages array). A workspace root holds its members’ deps, so the install there is real work. A workspaces object whose packages list is empty counts as memberless, however many other keys it carries.

  3. 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.

When your Node project lives in a subdirectory, name the directories under worktree.installPaths in the config file resolved above:

{
"worktree": {
"installPaths": ["docs-site"]
}
}
KeyDefaultWhat it doesEnv 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.devPortStride10Distance between one worktree’s port block and the next. Every app’s base must sit inside one stride-wide window.—
—install onSkip the dependency install entirely for one invocation.KIT_WT_INSTALL=0
—10Seconds cckit start waits for the port-slot ledger lock before allocating unserialized._WT_LOCK_WAIT

cckit pr follows the repo’s PR convention, set under pr in the config file:

{
"pr": {
"titleStyle": "issue-title",
"orchestratorSection": true
}
}
KeyDefaultWhat it does
pr.titleStyleconventionalconventional: 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.orchestratorSectionfalsetrue opens the PR body with a two-line ## For the orchestrator section: the issue number and what to review.

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
}
}
KeyDefaultWhat it doesEnv override
effort.wipLimit2How 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 onStart anyway, past the limit. Flag or env — either alone is enough.--force, or KIT_FORCE=1
—origin queriedSkip 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.

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>"]
}
}
}
}
KeyDefaultWhat it does
agents.defaultthe cheapest profileProfile 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.stagesbuild review design docsThe stage vocabulary a profile’s stages are checked against. Env override: CCKIT_AGENT_STAGES.
kindrequiredThe agent CLI to run (claude, codex, …). The Herdr runtime validates it before any worktree exists.
tierlowWhat 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.
writefalseWhether 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.

Resolution walks four levels, highest first, and stops at the first that supplies a name:

#LevelWhere it comes from
1Command overridethe flag on this invocation
2Issue labelagent:<profile> on the issue itself
3Parent effort labelagent:<profile> on the parent effort
4Project defaultagents.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:review label on a build stage 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.

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:

PartCut?What it is
Headless framingneverthere is no human here; work only on this issue; do not read the board
Brief metadataneverworktree, branch, seed freshness, and the gate command — where to work and what must pass
Brief sectionsyes## Files this issue owns, ## Helpers you already have, ## Standing gotchas, ## Durable prose
Receipt contractneveroutcome · 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.

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:

Terminal window
cckit receipt 321 --stage build <<'RECEIPT'
outcome: pr-open
url: https://github.com/jeiemgi/cckit/pull/999
gate: pass
blocker: none
next stage: review
RECEIPT

One 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.

Terminal window
cckit receipt list 321 # 321 build 1 blocked
# 321 build 2 pr-open
# 321 review 1 merged
cckit receipt show 321 build # the latest attempt's JSON

Every 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.

Terminal window
cckit receipt 321 --stage build --no-remote <<'RECEIPT' # write the file, post nothing

The 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 happenedRefuseRecord + flag
Agent crashedno receiptno receipt
Agent finished, wrote outcome: shippedno receiptoutcome: 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.

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