# Index Codebase

> Build persistent CODEBASE.md in the vault for a project. Explores the codebase structure, conventions, and architecture. Use when the user says "index codebase", "map codebase", or "/index-codebase <project>". Takes a project name as argument.

- Skill: `desertcache/index-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add desertcache/index-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/desertcache/index-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: desertcache (https://skillmd.com/u/desertcache)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/desertcache/index-codebase

---


# 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`:

```markdown
---
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