index-repo — Claude Code command: repository index
The index-repo command scans a repository and creates PROJECT_INDEX.md and PROJECT_INDEX.json. Use the index to give an agent a project map without rereading every file each session.
MIT ★ 23,950 updated 2026-09-27
.claude/commands/index-repo.mdWhat index-repo does
The command searches for code, documentation, configuration, tests, scripts, and tools. It extracts entry points, modules, public functions and classes, dependencies, and the purpose of configuration files. Five file-pattern searches run in parallel.
The output includes a human-readable PROJECT_INDEX.md and a machine-readable PROJECT_INDEX.json. The Markdown file covers directory structure, entry points, modules, docs, tests, and dependencies. Its validation checklist targets an index under 5 KB, so large repositories may exceed that size.
Run /index-repo for a full scan. Use mode=quick to skip tests or mode=update to refresh an existing index. In Claude Code, place the command file at .claude/commands/index-repo.md.
What it helps with
- map the repository's directories and files
- locate project entry points and core modules
- summarise dependencies and configuration
- refresh an index after repository changes
- create a quick index that skips tests
Example prompts for the agent
- Create an index of this repository with
/index-repo. - Refresh the existing project index using
/index-repo mode=update. - Scan the project without test files:
/index-repo mode=quick.
How to install index-repo
Manually: put the files in place
.claude/commands/index-repo.mdCall it with /index-repo. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/index-repo.mdCall it with /prompts:index-repo. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/index-repo.prompt.mdManually: put the files in place
.gemini/commands/index-repo.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about index-repo
How do I install index-repo in Claude Code?
Save the command file at .claude/commands/index-repo.md. Then run /index-repo.
What does index-repo do?
It scans repository files and writes PROJECT_INDEX.md and PROJECT_INDEX.json, covering the project layout, entry points, and key components.
What does mode=quick change?
It skips test analysis while creating the index.
Source text
index-repo.md · MIT
---
name: sc:index-repo
description: Repository Indexing - 94% token reduction (58K → 3K)
---
# Repository Index Creator
📊 **Index Creator activated**
## Problem Statement
**Before**: Reading all files → 58,000 tokens every session
**After**: Read PROJECT_INDEX.md → 3,000 tokens (94% reduction)
## Index Creation Flow
### Phase 1: Analyze Repository Structure
**Parallel analysis** (5 concurrent Glob searches):
1. **Code Structure**
```
src/**/*.{ts,py,js,tsx,jsx}
lib/**/*.{ts,py,js}
superclaude/**/*.py
```
2. **Documentation**
```
docs/**/*.md
*.md (root level)
README*.md
```
3. **Configuration**
```
*.toml
*.yaml, *.yml
*.json (exclude package-lock, node_modules)
```
4. **Tests**
```
tests/**/*.{py,ts,js}
**/*.test.{ts,py,js}
**/*.spec.{ts,py,js}
```
5. **Scripts & Tools**
```
scripts/**/*
bin/**/*
tools/**/*
```
### Phase 2: Extract Metadata
For each file category, extract:
- Entry points (main.py, index.ts, cli.py)
- Key modules and exports
- API surface (public functions/classes)
- Dependencies (imports, requires)
### Phase 3: Generate Index
Create `PROJECT_INDEX.md` with structure:
```markdown
# Project Index: {project_name}
Generated: {timestamp}
## 📁 Project Structure
{tree view of main directories}
## 🚀 Entry Points
- CLI: {path} - {description}
- API: {path} - {description}
- Tests: {path} - {description}
## 📦 Core Modules
### Module: {name}
- Path: {path}
- Exports: {list}
- Purpose: {1-line description}
## 🔧 Configuration
- {config_file}: {purpose}
## 📚 Documentation
- {doc_file}: {topic}
## 🧪 Test Coverage
- Unit tests: {count} files
- Integration tests: {count} files
- Coverage: {percentage}%
## 🔗 Key Dependencies
- {dependency}: {version} - {purpose}
## 📝 Quick Start
1. {setup step}
2. {run step}
3. {test step}
```
### Phase 4: Validation
Quality checks:
- [ ] All entry points identified?
- [ ] Core modules documented?
- [ ] Index size < 5KB?
- [ ] Human-readable format?
---
## Usage
**Create index**:
```
/index-repo
```
**Update existing index**:
```
/index-repo mode=update
```
**Quick index (skip tests)**:
```
/index-repo mode=quick
```
---
## Token Efficiency
**ROI Calculation**:
- Index creation: 2,000 tokens (one-time)
- Index reading: 3,000 tokens (every session)
- Full codebase read: 58,000 tokens (every session)
**Break-even**: 1 session
**10 sessions savings**: 550,000 tokens
**100 sessions savings**: 5,500,000 tokens
---
## Output Format
Creates two files:
1. `PROJECT_INDEX.md` (3KB, human-readable)
2. `PROJECT_INDEX.json` (10KB, machine-readable)
---
**Index Creator is now active.** Run to analyze current repository.
© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework