Skip to main content
subagent CX Codex

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

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

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

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set56

The whole set →
deep-research deep-research gathers authoritative external information outside the repository and compiles structured findings with a citation table. CX Codex ★ 23,950repo stars self-review self-review reviews a completed implementation by checking test evidence, edge cases, requirements, and residual risks before the final response. CX Codex ★ 23,950repo stars backend-architect backend-architect is a Claude Code subagent for planning backend systems and APIs. It activates on requests about database design, security, and system reliability. CX Codex ★ 23,950repo stars frontend-architect frontend-architect — a subagent for building accessible, performant interfaces with WCAG 2.1 AA compliance. Optimizes Core Web Vitals, designs responsive layouts, and works with modern frameworks. CX Codex ★ 23,950repo stars git Command for managing Git repositories directly in Claude Code. Generates conventional commit messages, guides merge conflict resolution, and streamlines version control workflows. CX Codex +1 ★ 23,950repo stars 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

Project sponsors

Companies that keep this analytics open