---
name: codebase-summarizer
description: Use codebase_summarizer to generate and maintain a codebase map. Trigger this skill when exploring a new or unfamiliar codebase, when working across multiple files in a large project, or after making changes to function signatures, docstrings, class definitions, or other exported symbols. The agent should consult codebase_summary.md as a map before reading individual files, and re-run `codebase_summarizer` in the project root after any structural changes.
---

## Tool: codebase_summarizer

A CLI tool that extracts a concise summary of a codebase — public symbols, their types, signatures, and documentation — into `codebase_summary.md`.

**Available at:** `codebase_summarizer` (installed globally) or `cargo run --release` from the project directory.

## When to Use

### At the start of a multi-file task
Before reading multiple files to understand a codebase, check if `codebase_summary.md` already exists. If it doesn't, or if the project has changed significantly, run:

```bash
codebase_summarizer --directory <project-root>
```

Use the summary to identify which files contain the logic you need, then deep-dive into those specific files.

### After making structural changes
Re-run the tool when you've changed any of the following:
- Function or method signatures
- Docstrings / documentation comments
- Class, struct, enum, or interface definitions
- Type aliases or trait definitions
- Exported symbols in general

From the project root:
```bash
codebase_summarizer
```

If `codebase_summary.md` already exists, the tool updates it in place. It also creates or updates `AGENTS.md` with navigation instructions.

## Reading the Summary

`codebase_summary.md` is organized by file. Each section lists the symbols in that file with their kind, name, signature, and documentation. Use it to:

1. **Find the right file** — identify which file contains the function or type you need
2. **Understand intent** — read the doc comments without reading the full implementation
3. **Know the API surface** — see what a module exports before diving into it

## How It Works

1. Scans the directory, filtering out `target/`, `node_modules/`, `.git/`, and other build/generated directories
2. Extracts symbols from code files using language-aware parsers
3. Outputs `codebase_summary.md` with the file tree and symbol documentation
4. Creates `AGENTS.md` with navigation protocol (if it doesn't exist)

## Supported Languages

Go, Rust, Python, Dart, R, TypeScript/JavaScript, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, and more.

## Output Format

The tool generates a markdown file with this structure:

```markdown
# Codebase Architecture Map

## File: src/main.rs

### func main
**Doc:**
Entry point for the application.

### struct Config
**Doc:**
Configuration for the application.
```

Each symbol shows its kind (func, struct, method, etc.), name, and any associated doc comments.