repo-md

<!-- REPO.MD:START -->

One file tells agents
where everything is.

repo-md walks your repository and writes REPO.md — a token-budgeted map of structure, tech stacks, and entry points. Coding agents read one file instead of exploring your tree with a dozen tool calls.

$npx @i_kabir/repo-md init
485 tokens on a sample repoworks with 5 agent CLIsMIT, zero config
zsh — your-repo
$ npx @i_kabir/repo-md init📂 Indexing /your-repo …✅ REPO.md written (485 tokens, 1938 chars)💉 Injected pointer into: AGENTS.md, CLAUDE.md$
REPO.md
# REPO.md — your-repo<!-- REPO.MD:STRUCTURE:START -->├── api/        — Node+Express, API layer│   └── index.ts   — entry point├── frontend/   — Node+Vite└── src/        — source<!-- REPO.MD:STRUCTURE:END -->## Stack · ## Entry Points · ## Updated…

<!-- REPO.MD:HOW:START -->

Three commands. That’s the whole workflow.

The structural index is generated locally in seconds. AI passes are optional and only ever touch REPO.md.

01 · init

Map the repository

Walks the file tree — respecting .gitignore, .bobignore, and nested ignores — detects per-folder stacks, and writes REPO.md under a hard token budget.

npx @i_kabir/repo-md init
02 · inject

Point agents at it

Adds a short “read REPO.md first” block into AGENTS.md and CLAUDE.md. Idempotent by design: run it daily, still exactly one block, your text untouched.

runs automatically after init
03 · keep fresh

Update only what changed

update re-indexes, diffs against the existing file, and rewrites only the sections that moved. An agent skill can do this live inside Bob IDE.

npx @i_kabir/repo-md update

<!-- REPO.MD:VS:START -->

How it relates to the files you already have.

REPO.md doesn’t replace your agent instructions — it completes them.

AGENTS.md
REPO.md
Repomix
answers
how should you behave?
where is everything?
what does every file say?
contents
conventions, commands, style rules
structure · stacks · entry points
your entire codebase, concatenated
size
hand-written, varies
hard budget: ~1,800 tokens
scales with repo size
kept fresh
by hand
by update + the agent skill
re-run the packer

<!-- REPO.MD:STATS:START -->

The token math is the point.

Every exploratory tool call an agent makes is context you pay for, twice. Real numbers from a sample repo, measured with repo-md stats:

485
tokens for the full map — structure, stacks, entry points
27%
of the default 1,800-token budget used
1 → ~8
one read replaces the read/list calls a blind agent makes

<!-- REPO.MD:SPEC:START -->

A convention, not a dump.

Every REPO.md has the same five marker-delimited sections, so any agent — and any teammate — knows exactly what’s where. Content outside the markers is yours and is never touched.

STRUCTURE — the tree

Compact ASCII tree with one-line purpose tags. ≤6 words per annotation, no sentences.

STACK — per-folder tech

package.json, go.mod, Cargo.toml, requirements.txt, and framework dirs become labels like Node+Express+Prisma.

ENTRY POINTS — start here

index, main, app, server, cli files, listed relative to root.

CONVENTIONS — enriched by AI

Starts empty; the optional agent pass fills in naming, patterns, and tooling notes. Hand-editable forever after.

UPDATED — freshness stamp

Timestamp, git branch and HEAD, uncommitted changes, recent commits — so an agent knows how stale the map is.

MARKERS — the contract

update rewrites only between markers. Your notes outside them survive every regeneration.

Bob ShellClaude CodeOpenCodeCodexAntigravity+ any agent that reads markdown

<!-- REPO.MD:INSTALL:START -->

Run it against any repo.

No install, no config file, no account. One command maps the repo you’re in.

get started
# map the current repo + inject pointers
$ npx @i_kabir/repo-md init
# refresh after structural changes
$ npx @i_kabir/repo-md update
# install the maintenance skill for Bob IDE
$ npx @i_kabir/repo-md skill --install
# or install globally
$ npm i -g @i_kabir/repo-md