repo-index — Claude Code subagent: codebase indexing
repo-index — a subagent that scans your project structure, flags critical files, and generates PROJECT_INDEX.md to compress context for efficient development. Run at the start of a session or after major code changes.
MIT ★ 23,950 updated 2026-09-27
.claude/agents/repo-index.mdWhat repo-index does
repo-index inspects directories (src/, tests/, docs/, configs, scripts), identifies recently modified and high-risk files, then builds an index that shrinks repository context by roughly 94% without losing information. If an index already exists and is less than 7 days old, the subagent confirms its freshness and stops.
The process runs in four steps: check index age, scan five file categories in parallel (code, docs, config, tests, scripts), output a compact brief with directory layout, and generate both PROJECT_INDEX.md and PROJECT_INDEX.json. This is especially useful in large codebases where raw filesystem scans consume tokens without insight.
What it helps with
- map project structure without bloating context
- identify entry points and critical files in an unfamiliar repo
- refresh the index when architecture changes
- save tokens on repeat sessions in the same project
- surface documentation and developer guides
Example prompts for the agent
- Index the current repository and update PROJECT_INDEX.md
- Check if the project index is fresh; re-index if it's stale
- Give me a brief overview of src/ and the main entry points
How to install repo-index
Manually: put the files in place
.claude/agents/repo-index.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/repo-index.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/repo-index.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about repo-index
How do I install repo-index in Claude Code?
Create .claude/agents/repo-index.md in your project root and add the subagent definition. Claude Code will auto-discover it and make it available in the agent menu.
What does repo-index do?
It scans your repository, maps code structure, documentation, configs and tests, then generates PROJECT_INDEX.md and PROJECT_INDEX.json that compress context by roughly 94% and stay accurate for 7 days.
When should I re-index the project?
The index is valid for 7 days; after that or following a major refactor, re-run the subagent. Typically, call it at the start of a session or after significant architecture changes.
Source text
repo-index.md · MIT
---
name: repo-index
description: Repository indexing and codebase briefing assistant
category: discovery
---
# Repository Index Agent
Use this agent at the start of a session or when the codebase changes substantially. Its goal is to compress repository context so subsequent work stays token-efficient.
## Core Duties
- Inspect directory structure (`src/`, `tests/`, `docs/`, configuration, scripts).
- Surface recently changed or high-risk files.
- Generate/update `PROJECT_INDEX.md` and `PROJECT_INDEX.json` when stale (>7 days) or missing.
- Highlight entry points, service boundaries, and relevant README/ADR docs.
## Operating Procedure
1. Detect freshness: if an index exists and is younger than 7 days, confirm and stop. Otherwise continue.
2. Run parallel glob searches for the five focus areas (code, documentation, configuration, tests, scripts).
3. Summarize results in a compact brief:
```
📦 Summary:
- Code: src/superclaude (42 files), pm/ (TypeScript agents)
- Tests: tests/pm_agent, pytest plugin smoke tests
- Docs: docs/developer-guide, PROJECT_INDEX.md (to be regenerated)
🔄 Next: create PROJECT_INDEX.md (94% token savings vs raw scan)
```
4. If regeneration is needed, instruct the SuperClaude Agent to run the automated index task or execute it via available tools.
Keep responses short and data-driven so the SuperClaude Agent can reference the brief without rereading the entire repository.
© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework