repo-indexer

Repo Indexer

Indexes codebases with minimal context window overhead using tiered memory.

Getting Started

Prerequisites: Python 3.9+. Run from the project root directory.

Memory Architecture

L0: Claude Native Memory  → repo roster, patterns (~100 tokens, auto)
L1: CLAUDE.md             → boot loader only (<500 tokens, auto-load)
L2: .claude/memory/*.md   → deep context (on-demand, explicit load)
L3: Conversation History  → full analysis (searchable, 0 cost until used)

Token budgets: Native Memory ~100–300 | CLAUDE.md <500 | memory/*.md <10,000 total | Past chats: 0 until searched

L2 file loading guide: Architecture decisions → architecture.md | Code style → conventions.md | Unknown terms → glossary.md

Task Progress

Use TodoWrite to track each phase dynamically:

• Phase 1: Detect repo type
• Phase 2: Analyze codebase (9 areas)
• Phase 3: Generate output files
• Phase 4: Validate token budgets
• Phase 5: Suggest memory update

Workflow

Phase 1: Detect Repo Type

python3 scripts/detect-repo-type.py "$ARGUMENTS"

Phase 2: Index

Analyze systematically:

1. Config: package.json, pyproject.toml, Cargo.toml, go.mod
2. Entry points: main files, CLI, server bootstrap
3. Structure: directory layout to depth 3
4. Core modules: business logic, services, models
5. API surface: routes, endpoints, schemas
6. Data layer: models, migrations, ORM
7. External deps: third-party integrations
8. Build/deploy: Dockerfile, CI/CD, Makefile
9. Tests: structure, fixtures, patterns

Before generating files, present the proposed .claude/ structure to the user for confirmation.

Phase 3: Generate Output

Output to conversation (L3):

Full analysis using format in references/templates.md → "Indexing Output Format". Include ### SEARCH KEYWORDS for retrieval.

Select CLAUDE.md template by repo type:

Use the type-specific variant from references/templates.md:

• Monorepo → "CLAUDE.md — Monorepo variant" (packages list, workspace commands)
• Library → "CLAUDE.md — Library variant" (public API section, publish commands)
• Microservices → "CLAUDE.md — Microservices variant" (services table, compose commands)
• Single App → base "CLAUDE.md" template

Create files:

.claude/
├── memory/
│   ├── architecture.md   # From references/templates.md
│   ├── conventions.md
│   └── glossary.md
├── plans/                # Empty, user-managed
└── checkpoints/          # Empty, user-managed

CLAUDE.md                 # At repo root, <500 tokens

Phase 4: Validate

python3 scripts/estimate-tokens.py

Must pass: CLAUDE.md < 500 tokens, all memory files within budget.

If validation fails:

1. Move content from CLAUDE.md to .claude/memory/ files
2. Re-run scripts/estimate-tokens.py
3. Repeat until all files pass their budget

Phase 5: Memory Update

python3 scripts/generate-memory-update.py

Suggest user add to Claude's native memory:

Repo: {name} | Type: {type} | Stack: {stack}
{name} indexed {date} | Key: {modules}

Examples

User: "Index this repo"

1. Run detect-repo-type.py (Phase 1)
2. Analyze all 9 areas (Phase 2)
3. Output full analysis to conversation + create .claude/ structure (Phase 3)
4. Validate token budgets (Phase 4)
5. Suggest native memory update (Phase 5)

User: "Help me understand this codebase"

1. Check Claude memory for prior indexing
2. Search past chats: "{repo-name} architecture"
3. If not found: run full indexing workflow

If .claude/ Exists

1. Load existing files
2. Compare with current codebase
3. Flag inconsistencies
4. Update incrementally
5. Preserve <!-- USER --> sections

Error Handling

Common issues:

• Python version error → requires Python 3.9+: python3 --version or which python3

Critical Rules

• CLAUDE.md hard limit: 500 tokens
• Full analysis goes in conversation, not files
• Files are pointers, not stores
• Always suggest native memory update
• Include search keywords in output