REPO.md

Coding agents arrive at your repository blind. AGENTS.md and CLAUDE.md tell them how to work — build commands, conventions, test suites — but say nothing about where anything is. So every session begins the same way: dozens of tool calls listing directories, opening files, and re-learning the same tree your team already knows. That exploration costs tokens, minutes, and context that should be spent on the actual task. REPO.md is the missing sibling: a single, strictly-conventional file that maps the repository itself — structure, per-folder tech stacks, entry points, and where each concern lives — written in a token-conscious style (terse paths, purpose tags, no prose) so it costs almost nothing to keep in context, while saving the dozens of exploratory calls it eliminates. The workflow: 1. Index — npx repo-md init walks your repo, respects .gitignore and .bobignore, applies depth and size caps, detects stacks via heuristics, and writes REPO.md. 2. Inject — the CLI adds a marker-delimited pointer into AGENTS.md and CLAUDE.md (idempotent, never duplicates, creates them if missing), so every agent reads REPO.md on session start. 3. Enrich — repo-md agent sends a one-shot headless command to your agent of choice — IBM Bob Shell, Claude Code, OpenCode, Codex, Antigravity — which deepens the index beyond the mechanical scan, following a strict convention and touching nothing else. 4. Maintain — an agent skill (installable via skills.sh, or pipeable one-off with npx repo-md skill) lets the agent update REPO.md as the code evolves; repo-md update does the same manually, diffing against git state so only what changed gets rewritten. No daemon, no install, no lock-in: it's one markdown file in your repo, generated in seconds, readable by every agent on the SKILL.md standard — and measurable: run the same task with and without REPO.md and compare your agent's tool-call and token consumption. P.S. I'm aware the demo video is quite limited in what it showcases, however, I've done my best to cover the main USP of the project and upon reading further about the project, you'll find the various other features that help in maintaining a REPO.md file, along with the direct coding agent integrations and agent skills.