AgentGrid

An orchestrator that launches agents, hands them tasks, and supervises results was the other option. I built a layer that sits beside git and answers questions about what is happening, and left process management to whatever runs the agents.

The design principle. AgentGrid embeds no prompts, no planner, and no model logic, and it does not launch agents or manage worktrees. Anything that reasons about code changes quickly; the rules about who may touch which files do not. Keeping them separate means the policy layer survives changes in the agent tooling underneath it.

The rules themselves live in a pure package that does no I/O, covered by table-driven tests (71 subtests).

It shells out to git instead of reimplementing it, and only to read: rev-parse, merge-base, rev-list and diff. State is a few tables in one SQLite file (agents, claims, stale marks, diff-risk snapshots), so the current state can be inspected with sqlite3 alone.

An agent registers what it intends to touch before it starts. A claim is a literal path or a glob, and each carries an intent, read or edit. Overlap is then a deterministic computation.

The rule is asymmetric: two agents reading the same files are allowed through without a warning, while any pairing involving edit is a conflict and is refused. Registration is atomic: if any of a new agent's claims conflicts, nothing is written. claim check runs the same test as a dry run. An agent's own overlapping claims never conflict with each other. Blocking at claim time is what keeps both agents from doing work that has to be thrown away.

$ agentgrid claim add b 'glob:src/auth/**:edit'
--- stdout: (empty)
--- stderr
error: claim glob:src/auth/**:edit conflicts with existing claims:
  a holds: path src/auth/session.ts edit
--- exit: 3

$ agentgrid claim list --agent b
--- stdout
no claims registered.
--- stderr: (empty)
--- exit: 0

An agent reads a module, forms a plan, and starts working. Something else lands on the base branch touching those same files. The agent is now working from a picture of the repository that no longer exists, and nothing about its own branch looks wrong.

So refresh takes the files that changed on the base branch since the agent's current merge-base and checks them against the agent's claims, read and edit alike. Files the agent changed without claiming are not part of this check. Because the merge-base is recomputed each time, rebasing past the change clears the stale mark on the next refresh.

A bare "you are stale" warning would be close to useless, so the verdict carries a recommendation, decided by the intent of the claims that matched: an overlap only on edit claims says rebase, an overlap only on read claims says review, and an overlap on both says re-plan.

var rec core.Recommendation
switch {
case hasEdit && hasRead:
	rec = core.RecommendReplan
case hasEdit:
	rec = core.RecommendRebase
case hasRead:
	rec = core.RecommendReview
default:
	// Reachable only if a claim has an unknown intent; treat as re-plan
	// rather than silently dropping the conflict.
	rec = core.RecommendReplan
}

The third mechanism scores how risky a branch's committed changes have become: files and lines changed against three configured tiers each, whether it touched a forbidden path such as migrations/, whether it touched binary files, and whether it modified files outside its claims or changed anything with no claims registered. Thresholds and forbidden paths come from a config file that is validated on every command, and each score is saved as a snapshot that diff-risk --no-refresh reads back without touching git.

Severity is the maximum across firing reasons, never a sum. Summing small signals produces a score with no single explanation behind it, while the maximum always points at one specific reason a branch is rated high. Every reason is emitted as a structured code, so the output is scriptable.

Every command that reads state takes --json, and the exit codes are a contract: 0 for success, 1 for an error, 3 for a policy refusal. stale and diff-risk report rather than block, so they exit 0 whatever they find, and a hook reads the JSON. status puts every agent on one table: ahead/behind, latest risk level, stale flag, and whether the branch has merged.

It never merges, force-pushes, or rewrites history, and it does not auto-resolve anything. The only thing it blocks is a conflicting claim; the merge stays with the person running it, because a tool that takes irreversible git actions on its own could destroy the work it exists to protect.