Built the state layer that stops coding agents from losing repo state and double-claiming work.

What changed

Pulled worktree isolation, atomic sprint claims, and a merge-safe state registry into one CLI that gates every merge on a recorded review and a passing check command.

Why it matters

This is the piece of my AI work that isn't a slide. It's a real state machine (task, sprint, epic; queue, lane; review, gate), a Git merge driver that resolves concurrent state edits deterministically instead of leaving conflict markers, and atomic per-sprint claims that stop two dispatch loops from grabbing the same work. I run my own multi-agent sprints through it daily, which is a different bar than a demo repo.

Measured outcomes

current release, published on npm

v1.33.x

isolation by construction, main stays clean

Worktree per task

the tool I run my own agent work through

Daily use

Highlights

• Defined a small vocabulary (task to sprint to epic, queue to lane, review to gate) and a seven-verb lifecycle so an agent reads and writes state through the CLI instead of inferring it from markdown tables. A bundled hook intercepts any tool call that targets state files directly and denies it, routing the agent back through the CLI verbs.
• Every task runs in its own Git worktree, locked to the file paths declared in its sprint. Parallel agents never collide on files, branches, or commits, and main stays clean until something actually merges.
• Wrote a custom Git merge driver that unions the state registry by id instead of leaving JSON conflict markers: merging a then b produces the same result as merging b then a, and the more-progressed status wins. The guarantee only holds for merges run locally on a clone with the driver installed; GitHub's and GitLab's web merge buttons don't execute it, so I still run validation in CI to catch anything a hosted merge might let drift.
• Gated concurrent dispatch with an atomic per-sprint claim, a lock file per sprint id, so two dispatch loops can never both pick up the same sprint. That, plus the merge driver, are the two fixes for the failure modes I actually hit running agents in parallel.
• Nothing reaches main without a recorded human review verdict and a passing check command. A failed check leaves the sprint active, not merged, so I retry it or discard it on purpose instead of it landing half-done.
• Modeled stopped runs as a structured halt reason instead of a stack trace, so resuming a crashed or paused run means reading a specific, well-known state rather than guessing from logs.
• Added tracker and PR bridges (Linear, Jira, GitHub Issues, GitHub PRs) as explicit, adapter-gated writes, not silent auto-sync: pulling a ticket into an epic never writes back, and every comment or transition is a command I run on purpose.
• Built a local, user-owned trust file so a repo's own config can declare it wants to run a check command or an agent, but nothing executes on my machine until I grant it there myself. Default is closed.

Outcomes

• Open source under MIT, published on npm as repokernel, currently at v1.33.x. Not a concept: a package I install and run.
• The state model holds up under real parallel dispatch: worktrees, atomic claims, and a merge-safe registry that survives concurrent branches without me hand-editing JSON.
• It's deliberately narrow. For a one-off script, a throwaway prototype, a non-Git workflow, or a team that already gates on CI and branch protection, RepoKernel is overhead you don't need, and the README says so.
• Schema and CLI are still evolving between releases, so anyone embedding it in CI should pin a version instead of tracking latest.

Stack

• TypeScript
• Node.js
• Git worktrees
• Commander.js
• Zod
• execa
• pnpm workspaces
• GitHub Actions
• Vitest
• npm