RepoKernel is a CLI tool that makes AI coding agent work scoped, ordered, reviewed, and resumable. Every task runs in its own Git worktree, locked to declared paths, sequenced by dependencies, and gated by review before anything touchesDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/xantorres/repokernel/llms.txt
Use this file to discover all available pages before exploring further.
main. It ships no daemon, no database, and no cloud service — your repository is the source of truth, and git push is the deployment.
The problem it solves
Running one AI coding agent is easy. Running three in parallel against the same repository is where things fall apart. State conflicts. Two agents updateregistry.json on different branches. git merge produces conflict markers that block until a human fixes them by hand.
No visibility. You open four terminal tabs and grep log files to figure out which agent is on which task and what it last touched.
Double-dispatch. Both dispatch loops pick up the same sprint. One succeeds; the other discards hours of work — or worse, produces inconsistent output that silently merges.
Scope creep. An agent touches files outside its task boundary. You don’t notice until the PR review finds unintended changes mixed in with the real work.
RepoKernel fixes each of these at the filesystem layer:
| Problem | What RepoKernel does |
|---|---|
| State conflicts | A Git merge driver unions agent state by id instead of leaving conflict markers — order-independent, so no human untangles JSON |
| No visibility | rk team status gives a one-snapshot view of runs, sprints, registry health, and current bottlenecks |
| Double-dispatch | Atomic per-sprint claims — two dispatch loops cannot both pick up the same sprint |
| Scope creep | allowed_paths in sprint frontmatter, flagged at review time before merge |
RepoKernel has no daemon, no cloud service, and no mandatory tracker. Your repo is the source of truth. If you can
git clone, you can run RepoKernel.The core model
RepoKernel has one small vocabulary. You meet it in this order:- Task — one unit of agent work, run in its own Git worktree. Fastpath tasks get an alias like
T-001. - Sprint — a task with declared scope (
allowed_paths) and dependencies (depends_on). - Epic — a set of sprints aimed at one goal, optionally run in parallel waves.
- Queue / Lane — the ordered backlog
rk nextwalks, split into named tracks with their own concurrency caps. - Review — a recorded verdict; nothing merges without one.
- Gate — your
checksCmd, scope, and validation checks: all green or no merge.
Four ways to use RepoKernel
Fastpath
One task, one worktree, done. The fastest on-ramp:
rk run -m "..." synthesizes a task, opens an isolated worktree, runs your agent, and pauses for review. No planning required.Agent-operated
Your agent drives
rk via the bundled skill. Install the skill into Claude Code, Cursor, Windsurf, or any supported IDE with rk install-skill. The agent learns seven purpose-built verbs and stops guessing lifecycle from prose.Advanced
Epics, sprints, dependency graphs, parallel waves. For multi-task projects: declare your epics, wire
depends_on, set allowed_paths, then rk run E-001 --mode autonomous fans out across all eligible sprints in order.Multi-agent
Team status, merge-safe state, tracker and PR bridges. Scale to a small fleet of 3+ agents in parallel.
rk team status answers “what is each agent doing?” in one command; the registry merge driver keeps shared state conflict-free.How it differs from agent-native workflows
Coding agents are growing their own orchestration — Claude Code runs parallel subagents, Codex chains tool calls. RepoKernel does not compete with that. It sits one layer down, around any agent, enforcing the Git lifecycle regardless of which agent you use.| The agent decides | RepoKernel enforces |
|---|---|
| What to change, how to plan it, when to spawn subagents | Each run lands in an isolated worktree — never your working tree |
| Which files to touch | allowed_paths scope, checked before merge |
| When the task is “done” | Review gates + your checksCmd must pass before anything reaches main |
| — | Deterministic registry merges; atomic claims so two runs never collide |
| — | State recovery — a crashed or runaway agent leaves a resumable run, not a corrupted repo |
When not to use RepoKernel
RepoKernel is deliberate infrastructure. It is overkill for:- One-off shell scripts or single-file tweaks you will never revisit
- Throwaway prototypes you never plan to merge into a real codebase
- Non-Git workflows (no worktree support without Git)
- Teams that already gate entirely via CI + branch protection and just want raw agent output piped to a PR