Skill: deep-codebase-navigator

Purpose

Combat context window overflow by creating and maintaining a compressed, semantic index of the codebase. This skill allows the agent to work effectively on large codebases that would otherwise exceed the context window limit.

When to Use

• •When the codebase has more than 50 files or 10,000 lines of code.
• •When the agent reports "losing track" of earlier context.
• •When working on a monorepo or large enterprise codebase.

How It Works

This skill delegates indexing to a CodeIndexer Sub-Agent that runs in its own isolated context window.

Step 1: Generate the Codebase Index

Run the following command at the start of each Ralph session:

# From the project root
claude --print "You are a CodeIndexer sub-agent. Your task is to create a compressed semantic index of this codebase.

1. List all source files (excluding node_modules, .git, etc.).
2. For each file, extract:
   - File path
   - Primary exports (classes, functions, constants)
   - Key dependencies (imports)
   - A one-sentence summary of the file's purpose.
3. Output the result as a JSON file at .ralph/codebase_index.json.

Be extremely concise. The goal is to minimize tokens while maximizing information density."

Step 2: Load the Index into Context

At the start of each iteration, the main Ralph agent should read the index:

Read .ralph/codebase_index.json to understand the structure of the codebase.

Step 3: On-Demand Deep Dives

When the agent needs to understand a specific module in detail, it should:

1. •Query the index to find the relevant file(s).
2. •Read only those specific files into context.
3. •Perform the task.
4. •Summarize any new learnings back into progress.txt.

Configuration

Add the following to your CLAUDE.md:

## Codebase Navigation

- **Index Location**: `.ralph/codebase_index.json`
- **Excluded Directories**: `node_modules`, `.git`, `dist`, `build`, `coverage`
- **Max Files Per Deep Dive**: 5

Example Index Entry

{
  "path": "src/services/UserService.ts",
  "exports": ["UserService", "createUser", "getUserById"],
  "imports": ["UserRepository", "Logger", "ValidationError"],
  "summary": "Handles user creation, retrieval, and validation logic."
}