claude-md-loop

Keeps a project's CLAUDE.md + .claude/rules/*.md context docs (for AI coding agents) accurate over time, instead of hand-writing them once and letting them rot.

Two AI roles do the work, each in its own session, so neither can rubber-stamp the other:

• Generator — writes or patches the docs from your real codebase.
• Reviewer — grades the docs against a task list, read-only.

A third role, task-miner, drafts that task list from your git history so you don't have to write it from memory.

Requirements

• oh-my-pi (omp) — the main supported tool.
• Bash and git, for the helper scripts.

Install

Clone this repo somewhere on your machine:

git clone https://github.com/ynsr/claude-md-loop ~/claude-md-loop

Then, from your target project's repo root:

PLUGIN_DIR=~/claude-md-loop ~/claude-md-loop/scripts/init-project.sh

This creates:

• docs/agents/ — the generator's spec, a known-unknowns list, and a scaffold review-tasks.md
• .claude/rules/ — empty, ready for the generator to fill in
• .omp/agents/ — copies of the three agent definitions, so oh-my-pi's task tool can call them by name

Add .loop/ to your project's .gitignore — it's transient orchestration state, not something to commit.

Using a different tool (Claude Code, Pi, etc.)? See docs/loop-guide.md for the alternatives.

Usage

You need a real task list before running the loop for the first time — see "First-time setup" below. Once that's done, pick one of these two ways to run it.

Option 1: Ask the skill (quick, but not recommended)

Copy the skill into oh-my-pi's skill directory:

mkdir -p .omp/skills
cp -r ~/claude-md-loop/skills/claude-md-loop .omp/skills/claude-md-loop

Then just ask, in a normal omp session:

Update this project's CLAUDE.md docs.

The skill dispatches the generator and reviewer for you. This is the fastest way to try the loop, but the session driving it sees both the generator's and the reviewer's output, which weakens the independence the two-role split is meant to give you. Use Option 2 if you want the real isolation guarantee, or for anything beyond a one-off run.

Option 2: Run the script (recommended)

./scripts/loop-runner.sh --mode guided --rounds 2

This prints the exact command to run for each round — one fresh omp -p ... process per role. Copy-paste each one, in order, and read the reviewer's output before deciding whether to continue.

Once you trust the setup, let the script drive it end-to-end instead:

./scripts/loop-runner.sh --mode auto --rounds 2

This runs the same fresh-process-per-role sequence itself, stops early if everything passes, and hard-caps at --rounds. It never merges anything — it stops and tells you to review the diff yourself:

git diff CLAUDE.md .claude/rules/

First-time setup: seeding the task list

docs/agents/review-tasks.md starts out as a placeholder — the loop won't invent a real task list for you. Seed it once, before round 1:

omp -p "Use the claude-md-task-miner agent to draft review tasks from git history."

Read the resulting docs/agents/review-tasks.draft.md, trim or fix anything that isn't a genuine recurring pattern, then run:

./scripts/promote-tasks.sh

This diffs your draft against the frozen file and asks for confirmation before writing anything. From here on, review-tasks.md only changes by hand.

Uninstall

Everything this tool adds to a project lives in a few places:

rm -rf docs/agents .omp/agents .omp/skills/claude-md-loop .loop

CLAUDE.md and .claude/rules/*.md are the generated docs themselves — plain markdown you own once written. Keep or delete them separately, depending on whether you still want the docs regardless of the loop that produced them.

To remove your local clone of this repo entirely:

rm -rf ~/claude-md-loop

More detail

• docs/loop-guide.md — full operating guide: running the loop on other tools, re-running it on a schedule, and the design principles behind it.
• docs/context-isolation.md — why the orchestration is a plain script, not another LLM.

License

MIT — see LICENSE.