Prepare repositories for AI coding agents.
RepoFrame gives a coding agent clean context before it works, an implementable plan while it works, and objective verification after it finishes. It does not replace Claude Code, Codex or Gemini CLI. It wraps them.
- src/
- cli.tsentry point
- commands/plan.tstask match
- commands/analyze.ts
- core/select.tstask match
- core/walk.ts
- ai/claude.ts
.envwithheldnode_modules/excludedpackage-lock.jsonnoise
How it works
Analyze. Plan. Verify.
Three small steps around whichever coding agent you already use. Everything that can run locally does, and evidence beats opinion.
Analyze
Reads the repository on your machine: stack, package manager, build, test and lint commands, git state, docs, CI and existing agent instructions.
Plan
Selects a small slice of the repo and asks Claude for a precise plan: steps, files to touch, constraints, acceptance criteria and validation commands.
Verify
Runs tests, lint, typecheck and build, compares the changed files with the plan, and reports PASS, PARTIAL or FAIL from exit codes and the git diff.
Install
Four commands.
Run them inside any git repository.
Requires Node.js 22.12+ and git. Not on the npm registry yet.
Built for Claude
Claude is the reasoning engine.
The plan step is where reasoning matters, so that is where Claude comes in. RepoFrame does the preparation (what to send, how to ask, what format to expect) and Claude does the thinking. Everything else stays deterministic and local.
- With the APISet
ANTHROPIC_API_KEYand runrepoframe plan. - With a subscriptionNo key needed:
--prompt-onlywrites a prompt to paste into Claude,--from-replyimports the answer. - Claude CodeA natural fit for the implementation step: hand it
plan.md, then runrepoframe verify. - Other modelsProvider-neutral by design; the manual flow works with any chat model.
Early alpha: the live Claude API call has not been exercised in this release. The manual flow, which uses the same prompts, has been used end to end. Testing against the live API is on the roadmap.
Early signal*
Same task, with and without a plan.
One controlled comparison on a real React + Capacitor app: same task, same model, same starting commit, a fresh agent for each. One got only the task; the other got the task plus a RepoFrame plan.
| Without a plan | With a plan | |
|---|---|---|
| Test, lint and build | pass | pass |
| Acceptance criteria met | 10 / 13 | 13 / 13 |
| Planned files the agent missed | 4 | 0 |
| Unit tests added | no | yes (5) |
| Repo conventions followed | no | yes |
| Cost | ~85k tokens, 0.7 min | ~84k tokens, 1.0 min |
Both agents delivered a working feature. The difference was alignment: the agent with the plan stayed inside what was asked and inside the repository's own conventions, at about the same cost.
*Preliminary and not statistically meaningful: one task, one repository, one model, one run per arm, no repeats. Both agents worked without installed dependencies, so neither could run the tests while working. "Planned files missed" is measured against the plan that only the second agent saw, so it favors that arm by construction; the independent signals are the test, lint and build tie and the code itself. Acceptance criteria were judged by Claude, not blindly. More runs across more tasks and repositories are planned. Tooling and raw data.
Privacy
Your repository stays yours.
Local first
Analyze and verify never contact an AI provider. Plan lists every file it will send, and records it.
Minimal context
A task-relevant slice, never the whole repository. Secret-looking files, build output and your .gitignore are excluded.
Redaction
Keys, tokens and private keys inside files are replaced before anything leaves your machine. A heuristic that lowers risk, not a guarantee.