index-codebase

Explore a project's codebase and produce a comprehensive CODEBASE.md reference in the vault.

Step 1: Parse Arguments

The user provides a project name (e.g., my-app, api-server).

Map to codebase path and vault path using the Project-Codebase Mapping table in CLAUDE.md (always in system prompt), or from agent-os.config.json.

If the project name doesn't match any entry in the mapping, ask the user to provide the codebase path.

Step 2: Explore the Codebase

Use the Explore subagent (Task tool with subagent_type=Explore, thoroughness="very thorough") to analyze:

1. Structure: Top-level directory layout, key folders, file organization
2. Dependencies: package.json / requirements.txt / pyproject.toml — frameworks, libraries, versions
3. Entry Points: Main files, startup scripts, CLI commands
4. Architecture: Routing, models/schemas, middleware, services, utilities
5. Configuration: Environment variables (.env.example), config files, constants
6. Tests: Test framework, test location, coverage setup
7. Build & Deploy: Build scripts, Dockerfile, CI/CD config
8. Code Conventions: Naming patterns, file naming, import style, error handling approach
9. State Management: How state is managed (database, in-memory, external services)
10. TODOs/FIXMEs/HACKs: Grep for these markers across the codebase

Step 3: Check for Existing CODEBASE.md

Read <vaultPath>/<projectVaultFolder>/CODEBASE.md if it exists.

• If exists: This is an update. Compare with new findings. Only update changed sections. Add a changelog entry at the bottom.
• If doesn't exist: Create new file.

Step 4: Write CODEBASE.md

Write to <vaultPath>/<projectVaultFolder>/CODEBASE.md:

---
date: YYYY-MM-DD
tags: [codebase, index, <project-name>]
auto-generated: true
---

# <Project Name> — Codebase Index

> Auto-generated by `/index-codebase`. Last updated: YYYY-MM-DD

## Overview
[1-2 sentence description of what this project does and its tech stack]

## Structure

<tree output, 2-3 levels deep, annotated>

## Dependencies
| Package | Version | Purpose |
|---|---|---|
| ... | ... | ... |

## Entry Points
- **Main**: `path/to/main` — [description]
- **CLI**: `path/to/cli` — [if applicable]
- **API**: `path/to/routes` — [if applicable]

## Architecture
[Description of the architecture pattern: MVC, service layer, etc.]

### Key Files
| File | Purpose |
|---|---|
| ... | ... |

## Configuration
| Env Variable | Purpose | Default |
|---|---|---|
| ... | ... | ... |

## Code Conventions
- [naming patterns, file naming, import style]
- [error handling approach]
- [logging approach]

## Tests
- Framework: [jest/pytest/etc]
- Location: [path]
- Run: [command]

## Known Issues / TODOs
- [ ] [TODO items found in code]

## Changelog
- YYYY-MM-DD: Initial index

Output

After writing, display a brief summary:

Codebase indexed: <project>
Written to: <vaultPath>/<projectFolder>/CODEBASE.md
Files scanned: N
Key findings: [1-2 notable things about the codebase]

Rules

• Use the Explore subagent for thorough analysis — don't try to manually glob everything
• Don't include file contents in the index — just structure, patterns, and metadata
• Keep the CODEBASE.md under 200 lines for readability
• On re-runs, preserve manual edits (check for sections not in the template)
• Skip node_modules, pycache, .git, dist, build directories
• If a section has nothing to report, use "N/A" rather than omitting it
• All paths come from agent-os.config.json — never hardcode user-specific paths