Overview

The gap between admiring a codebase and knowing which three things to steal from it is a day of reading. Ask a model and you get an exhaustive, agreeable inventory of everything the reference has and you don't, ranked by nothing, with no idea what your project is for — and if you then hand an agent write access, one enormous commit that touches forty files and nobody can review. repogap is built to fix both: a report that skips more than it recommends, and an apply flow that is one item, one commit.

Tech Stack

Challenges

• Stopping the model from producing an agreeable, unranked inventory instead of a real recommendation.
• Guaranteeing the analysis phase can't modify the repo it's reading — not "is asked not to," but cannot.
• Respecting the reference repo's licence before porting any of its code.
• Keeping the model from inventing verifiable facts like dates and licences.

Solution

Every finding is scored against a --goal and anything that doesn't clear the bar gets a Skip with a one-line reason; findings cite the reference file and often the lines, so you can go read them yourself. Read-only isn't a prompt — it's a canUseTool interceptor: every Write/Edit whose path isn't GAP_ANALYSIS.md is denied before it executes, Bash is narrowed to a read-only allowlist, and chained commands are checked per segment so "ls && rm -rf src" is refused on the second segment. Licences are read first and derive a policy (MIT/Apache/BSD permits porting with attribution; GPL/AGPL or no licence flips to patterns-only) baked into the system prompt. Verifiable facts — the report's licence and date lines — are rewritten in code after generation, because the first run stamped a date from the model's training prior.

Outcome

repogap analyze produces a goal-scored, source-cited gap report; repogap apply plans, waits for your go, implements a single item, runs your existing tests, and commits as gap(G-03): … — with git push, git reset --hard and npm publish blocked in every phase. A full six-category analysis of a small repo runs ~50 turns, ~4.5 minutes, ~$0.57, and every run prints its own turn count, duration and cost. Six tests cover the permission guards, including the chained-command bypass and the write-outside-repo escape.

What I'd do differently

The most interesting file in the project is the one that stops the agent. Coming from real-time control code for jet engines — where a millisecond of lag is a flameout — the instinct to make the guardrail a hard, testable boundary rather than a polite instruction is exactly what makes an agent with write access trustworthy.