claude-code-loop
A Claude Code plugin that works an issue backlog like a small dev team, one gated issue at a time
Overview
claude-code-loop is a Claude Code plugin, dev-loop, that works through a GitHub issue backlog the way a small, disciplined dev team would. Each invocation takes exactly one issue end to end: scope it, plan it, have the plan design-reviewed, implement it on a branch, open the PR, run code review and (where the change calls for it) security review, have an agent that didn’t write the code check it against the acceptance criteria, and merge. By default it stops for your approval on every plan before any code is written and on every merge.
Everything the loop does is written to a ledger on disk rather than kept in the model’s context. That’s what lets the next invocation pick up where the last one stopped, whether the session ended with a /clear, a compaction, or a crash.
The engine was first built and hardened inside AgentFluent, where it ran the v0.10.x and v0.11.0 releases, and was then extracted into its own repo so any project can use it. It now drives six repos, including itself: this repo works its own backlog with the loop it develops.
A Dev Team, in a Loop
The pipeline is modeled on the roles of a human team. Each role is a binding in a per-project config file, and the plugin ships no agent definitions of its own: the scope and design roles point at subagents you already have.
| Team role | What it does in the loop |
|---|---|
| Product manager | answers scope, priority and requirements questions, and splits an issue too large for one pass |
| Architect | reviews the plan before any code is written, read-only, when a trigger fires or the loop is unsure |
| Developer | the orchestrator itself: plans, implements, runs your lint, type and test commands, opens the PR |
| Code reviewers | parallel read-only reviewers over the diff, each handed the issue’s acceptance criteria |
| Security reviewer | runs where the route and the touched files call for it |
| QA | a fresh agent that checks every acceptance criterion and whether the tests would catch a regression |
| Owner | you: approve plans, approve merges, and settle anything the agents disagree on |
How It Works
Routed by risk
Each issue is routed by its labels and the path rules in your config. A code change gets the full pipeline and every gate. research gets a lighter plan, docs skips the architect and security passes, and stub-defer is journaled and left in the backlog.
Two human gates
The plan gate and the merge gate are set separately, so loosening how much planning you review never loosens what merges without you. Auto-merge exists only for routes you have explicitly graduated, and never for a feature, a breaking change, or anything touching a security surface.
A ledger, not a context window
Each run keeps a work queue, an append-only journal of every gate decision, and a plan per issue under .claude/loop/. On resume, the loop checks each unfinished row against live git and PR state before starting anything new.
Tests that would notice
On a change that alters behavior, the acceptance gate breaks the guarded code on purpose in a throwaway copy of your tree, runs your suite, and reports any test that stayed green. A test that can't fail is protection you think you have and don't.
What Sets It Apart
- One issue per invocation, end to end. It’s a single supervised orchestrator handling one routed issue at a time, not a graph of agents running in parallel. Re-invoke it for the next issue, or let Claude Code’s
/loopdrive it. - A gate that didn’t run never counts as passed. No verdict means not passed. A gate’s pass covers only the commit it ran on, and expires if the PR changes afterward. A blank binding in the config falls back to a built-in equivalent or stops and asks; it never quietly turns the gate off.
- A fix is never checked by whoever wrote it. When the loop fixes a review or acceptance finding, a freshly spawned agent decides whether the fix worked. If that one re-check comes back dirty, the loop stops and asks you instead of iterating on itself.
- When the architect rewrites the plan, you see the plan. If design review materially changes the approach, the loop stops and shows you what changed before any code is written. No mode setting reaches that stop.
- One engine, one config per project. Your build commands, branch format, commit convention, merge method and PR template live in one
loop.config.mdthat/init-loopinfers from the repo. The engine itself is never edited per project.
Measuring What a Run Costs
The repo keeps a research notebook on why an iteration costs what it does and what would make it cheaper without making it worse. It reads Claude Code session transcripts and the ledger’s per-iteration budget lines, prices them against a shared cost specification, and is set up as causal inference rather than trend-reading: issue difficulty is an unmeasured confounder, so config levers are estimated as total effects. Releases reach the consuming repos on different dates, and two repos are deliberately held back on an older engine as an untreated control.
Technology Stack
- Engine: Markdown instructions that the orchestrating agent executes, split into a core read on every invocation and phase units read when needed
- Platform: Claude Code plugin, installed from its own marketplace
- Integrations: git and the GitHub CLI (
gh) for issues, pull requests and CI checks - Guard hook and mutation harness: Python 3.9+, standard library only
- Testing: stdlib
unittest, run on Python 3.9 through 3.13 in CI, pinning the couplings between files (every parameter the engine reads exists in the onboarding skeleton, the pipeline’s step order agrees wherever it’s restated)
Status
At v0.3.1 the plugin is not yet stable. Six repos drive it, and the loop had carried 111 issues to done across five of them by the v0.3.0 release. That’s enough to show the plugin and config split holds under real use, but not enough to call it stable. Findings from real runs are collected in issue #1, and reports from repos unlike the current six are welcome.
Install
/plugin marketplace add frederick-douglas-pearce/claude-code-loop
/plugin install dev-loop@claude-code-loop
/init-loop
Before the first run, read the README’s section on what the loop can do to your repo: it creates branches, commits, opens pull requests and merges on your behalf. Then review the generated .claude/loop.config.md and ask Claude to “run the dev loop”.
The Blog Series — A Cross-Functional Team of One
A coding agent really is cross-functional: it plans, designs, implements and tests. When the same mind that did the work also checks it, it tends to confirm its own thinking. The series goes gate by gate through how each role in the loop works, the real runs where one nearly let something through, and what changed in the loop afterward. It also covers setting up the loop for your own projects and the cost experiments aimed at making it cheaper without making it weaker.
Post 1 — A Loop to Remember All posts in the series