RepoCanon

RepoCanon

Verified AGENTS.md and project memory for AI coding agents. One small .ai/ folder tells Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf and Cline how your project works, and git checks that it is still true.

Sponsored by [Framimo](https://framimo.com) — turn any clip into GIF, WebP, AVIF or MP4, right in your browser.

In 30 seconds

• What it is: a small, local project-memory layer (AGENTS.md + .ai/) that every AI coding agent reads: the rules, decisions and gotchas your code can't show.
• What it does: one command sets it up for all your tools, delivers each module's rules to the agent while it works, and checks every rule against the code with git, so stale ones are flagged, not trusted.
• How it helps: agents follow your project's rules instead of guessing (8% → 100% of tasks passed once the rules were written down), and they keep the docs correct as they work. It runs locally, calls no LLM and has zero dependencies.

Why

• Agents re-learn your repo on every task. They scan files, burn tokens, and still miss the rules code doesn't show: state machines, money and permission invariants, why a choice was made.
• Hand-written `CLAUDE.md` and rules files rot silently. Nobody notices when they stop matching the code.
• Every tool wants its own file. CLAUDE.md, .cursor/rules, Copilot instructions, GEMINI.md, .windsurfrules, .clinerules…

RepoCanon keeps one knowledge layer (AGENTS.md + .ai/), points every tool you use at it, and uses git to tell you which docs went stale after a code change. It runs locally, calls no LLM and has zero dependencies.

Quick start

Requires Node.js 18+ and a git repository.

cd your-project

npx repocanon init # pick your AI tools (↑/↓, space, enter)

What you'll see

◆ repocanon init · shop

Stack Node.js, Express Tools Claude Code, Cursor

Files

• .repocanon.json created
• .ai/.gitignore created
• .ai/INDEX.md created
• .ai/PROJECT.md created
• .ai/DOMAIN.md created
• .ai/CONVENTIONS.md created
• .ai/DECISIONS.md created
• .ai/STATE.md created
• .ai/prompts/update.md created
• .ai/modules/_TEMPLATE.md created
• AGENTS.md created
• CLAUDE.md created
• .cursor/rules/project.mdc created

Generated ✓ Module map 2 module(s) → .ai/INDEX.md · Scoped rules up to date ✓ Skills 3 file(s) updated: .ai/skills/rc-verify-change/SKILL.md, .claude/skills/rc-verify-change/SKILL.md, .agents/skills/rc-verify-change/SKILL.md

✓ Knowledge layer created

Next npx repocanon setup connect the MCP server to your tools npx repocanon prompt fill brief for your agent to fill the docs (or ask it over MCP) npx repocanon doctor check the result

Then let your agent fill the docs. Either:

• With MCP (npx repocanon setup, details): tell your agent *"Fill the RepoCanon docs"*. It calls rc_prepare_fill and writes .ai/*.md itself.
• Without MCP: run npx repocanon prompt fill and paste the output into your agent.

Finally, check the result and commit:

npx repocanon doctor        # lint: size caps, TODOs, broken paths, token budget, content agents can infer

git add -A && git commit -m "Add RepoCanon knowledge layer" npx repocanon stamp --all # mark the docs verified at that commit git commit -am "Verify RepoCanon docs"

What doctor shows

◆ repocanon doctor · shop

Warnings (1) ! scoped rule files are out of date (2: .cursor/rules/rc-billing.mdc, AGENTS.md) — run: npx repocanon rules

Info (1) i 27 TODO placeholder(s) remain in .ai/ — run: repocanon prompt fill

Token budget Entry context (AGENTS + PROJECT + INDEX) ~662 tokens Whole repo source ~820 tokens Entry share of the repo 80.73% → estimates: word-aware for docs, bytes/4 for code

Freshness █████████░ 91/100

! 1 warning · 1 note(s)

Next npx repocanon prompt fill npx repocanon rules npx repocanon doctor run again after fixing

Reading the output

Every command prints the same shape: a header, rows, a one-line verdict, then Next: the exact commands to run. Symbols always come with a word, so the output also works without colour (NO_COLOR=1, --no-color, CI logs, screen readers).

Every command has --help with options and examples: npx repocanon status --help. --json and --format=github give machine-readable output for scripts and CI.

Already have CLAUDE.md, Cursor rules or a Cline memory bank?

npx repocanon adopt --dry-run   # preview: what goes where, what gets removed

npx repocanon adopt # import into .ai/ (creates it if needed) git add -A && git commit -m "Adopt RepoCanon" npx repocanon adopt --move # originals become pointers, so tools stop reading two copies

adopt reads CLAUDE.md, GEMINI.md, .windsurfrules, .clinerules, .github/copilot-instructions.md, .cursorrules, always-on .cursor/rules/*.mdc, repo-wide Copilot instructions and Cline's memory-bank/. It routes each section to the right doc (glossary → DOMAIN, decisions → DECISIONS, progress → STATE, overview → PROJECT, the rest → CONVENTIONS), drops directory trees, dependency lists, pasted code and secrets, and tells you how many tokens that saved. Rules that are already scoped to certain files stay where they are. Re-running skips what was already imported; --move never touches a file with uncommitted changes.

What you get

AGENTS.md                 entry point every agent reads: commands, a digest of your rules and decisions, Definition of Done

.ai/ PROJECT.md purpose, stack, boundaries INDEX.md path → module map (auto block refreshed by analyze) DOMAIN.md business rules, states, invariants, glossary CONVENTIONS.md coding style and patterns DECISIONS.md why things are built this way STATE.md current focus and recent changes modules/ .md one doc per module: purpose, invariants, flow, code map, gotchas .repocanon.json config (presets, modules, excludes, chosen tools) CLAUDE.md, .cursor/… small pointer files, only for the tools you pick

Docs are a semantic index, never a copy of the code. When docs and code disagree, code wins and the doc gets fixed.

Choosing tools

init opens a picker for the AI tools that should read the knowledge layer. AGENTS.md is always written; each tool you pick gets a small pointer file:

• Re-run any time. init reopens the picker with your saved choice and marks each tool set up or detected. If nothing changed it prints Up to date.
• Untick a tool and init offers to remove its RepoCanon block. Only that block goes: your own text stays, and a file is deleted only if nothing else is in it.
• Scripts and CI (no terminal): --targets=claude,cursor, --targets=all or --targets=none; --yes keeps the saved choice; --prune removes blocks of tools you no longer select.

Scoped rules: module knowledge exactly where the agent is editing

npx repocanon rules turns each filled module doc into rule files that a tool loads only while the agent edits that module's files — no tool call, no extra tokens anywhere else:

• .ai/modules/ .md stays the single source. Generated files say so in their header; edit the doc, then run rules again.
• Files are written only for the tools you selected in init. Nested AGENTS.md pointers are off by default; turn them on with "nestedAgents": true in .repocanon.json.
• Modules whose doc is still the empty template get nothing. Removed docs and deselected tools have their generated files cleaned up; your own rule files are never touched.
• init runs rules for you, doctor warns when the files are out of date, and rules --check fails CI until they're regenerated.

Skills: the repo's own checks, loaded only when needed

npx repocanon skills (also run by init) writes an Agent Skill that tells agents how to verify a change in *this* repo: .ai/skills/rc-verify-change/SKILL.md. Only its one-line description sits in the agent's context; the body loads when the agent is about to say "done".

• Commands come from the repo itself: package.json / composer.json scripts (run with your package manager), Makefile, justfile, Taskfile.yml, and the run: steps of .github/workflows/*.yml or .gitlab-ci.yml. Each one says where it was found, duplicates are merged, and steps run in order: format → lint → typecheck → test (an aggregate make check comes first).
• Installs, deploys, publishes, lines using CI secrets, and watch or dev servers are never included.
• .ai/skills/ is the one place to edit. Change the generated skill and RepoCanon stops regenerating it; add your own .ai/skills/ /SKILL.md and it is copied out too.

Copies are written only for the tools you chose, carry a "Generated by RepoCanon" header, and are removed when you deselect the tool. A skill of the same name that RepoCanon didn't write is never overwritten. Skills with an invalid name (lowercase, hyphens, must match the folder), a missing description or a secret are not copied, a