Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/index-repo.md
Open on GitHub

What 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.md

Call it with /index-repo. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set56

The whole set →
devops-architect devops-architect automates infrastructure and CI/CD pipelines. Useful when planning zero-downtime releases and disaster recovery. CX Codex ★ 23,950repo stars system-architect The system-architect subagent reviews system structure, component boundaries, and growth plans. Use it when choosing patterns, technologies, or a migration path. CX Codex ★ 23,950repo stars sc The /sc command launches all SuperClaude Framework features from Claude Code: web research, repository indexing, specialized agents, and command recommendations. CX Codex +1 ★ 23,950repo stars performance-engineer performance-engineer profiles bottlenecks and speeds up web apps through before-and-after measurements. Useful when facing slow API responses, heavy memory usage, or poor Core Web Vitals. CX Codex ★ 23,950repo stars agent The /sc:agent slash command manages your session workflow: runs a startup checklist to confirm project readiness, coordinates investigation and implementation through helper skills, and validates results before handing off. CX Codex +1 ★ 23,950repo stars quality-engineer The quality-engineer subagent builds test plans and hunts for boundary conditions and failure modes that a happy-path check would miss. CX Codex ★ 23,950repo stars technical-writer technical-writer — a subagent that writes technical documentation: API references, guides, specs, and installation instructions with code examples and accessibility checks. CX Codex ★ 23,950repo stars refactoring-expert The refactoring-expert subagent cuts cyclomatic complexity and eliminates technical debt using SOLID principles. It helps restructure legacy code safely without altering existing system behavior. CX Codex ★ 23,950repo stars

Project sponsors

Companies that keep this analytics open