---
name: toondex
description: |
  Semantic folder index for codebase navigation. Commands: /toondex (create), /redex (update).
  IMPORTANT: If you see "PROPOSE_REINDEX" in your context (injected by SessionStart hook),
  when the user sends their next message, briefly ask if they want you to run /redex first
  or if you should continue answering their question.
  "Oh, I see you've discovered my meticulously organized archive."
---

# ToonDex

> "Oh, I see you've discovered my meticulously organized archive."

Create and maintain semantic folder indexes for efficient LLM codebase navigation.

## Commands

| Command | Purpose |
|---------|---------|
| `/toondex` | Create initial index.toon (interactive) |
| `/redex` | Update index.toon with changes |
| `/toondex --stats` | Show debug mode usage statistics |

### /toondex --stats

Display ToonDex usage statistics (requires `TOONDEX_DEBUG=1`).

**Implementation:** Run the statistics script:

```bash
${CLAUDE_PLUGIN_ROOT}/scripts/show-stats.sh
```

Or directly from project root:

```bash
./plugins/toondex/scripts/show-stats.sh
```

The script will:
- Check if debug mode is enabled
- Display warning if `TOONDEX_DEBUG=1` is not set
- Show hook execution counts, index file reads, and effectiveness metrics
- Format timestamps as relative times (e.g., "2m ago", "5h ago")

## Format Specification

See `docs/INDEX_SPEC.md` for full spec. Summary:

```
# {folder-name}
{child-folder},{summary}
{child-folder},{summary}
```

- **Recursive**: An `index.toon` is created in each scanned folder, not just the root
- Each `index.toon` only lists its **direct child folders** (relative names, not full paths)
- Order = priority (first = most important)
- Summaries describe behavior, not file listings
- State tracked via git (no separate state file)
- Navigating the codebase: start at root `index.toon`, then drill into child `index.toon` files

---

## /toondex - Create Initial Index

**WHEN THIS SKILL IS INVOKED, IMMEDIATELY START WITH STEP 1. EXECUTE THE STEPS - DO NOT JUST DESCRIBE THEM.**

On success, respond with: `"Best. Index. Ever."`

### Step 1: Ask Traversal Depth (DO THIS NOW)

Ask the user how deep to traverse:

```
How many levels deep should I scan? (default: 2)
```

Common choices:
- **2** - Top-level and one sublevel (good for most projects)
- **3** - Deeper scan (monorepos, nested packages)
- **1** - Shallow scan (very large codebases)

### Step 2: Scan Folders

Use the **Bash tool** to scan directories. Detect the platform and use the appropriate command with the user's chosen depth (`$DEPTH`):

**macOS / Linux** (use `/usr/bin/find` to bypass shell aliases):
```bash
/usr/bin/find . -maxdepth $DEPTH -type d \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/.next/*' \
  -not -path '*/build/*' \
  -not -path '*/coverage/*' \
  -not -path '*/vendor/*' \
  -not -path '*/tmp/*' \
  -not -name '.*' \
  | sort
```

**Windows** (PowerShell):
```powershell
Get-ChildItem -Directory -Recurse -Depth $DEPTH |
  Where-Object { $_.FullName -notmatch 'node_modules|\.git|dist|\.next|build|coverage|vendor|tmp' } |
  Where-Object { -not $_.Name.StartsWith('.') } |
  Sort-Object FullName
```

**Platform detection:** Check the environment info (darwin = macOS, linux = Linux, otherwise assume Windows).

### Step 3: Filter Results (MANDATORY)

**BEFORE analyzing, remove ALL of the following from the scan results. Do NOT analyze or index these:**

- Hidden folders (starting with `.`) — e.g. `.git/`, `.cache/`, `.hive-mind/`, `.specify/`
- Dependencies: `node_modules/`, `vendor/`
- Generated output: `dist/`, `build/`, `.next/`, `coverage/`, `tmp/`
- Single-file folders (describe the parent folder instead)
- Any folder that is purely generated output, cached data, or third-party code

If unsure whether a folder is generated, check for a `.gitignore` entry or absence from version control.

### Step 4: Analyze Each Folder

For each folder, create a summary with confidence score. See `references/scoring-rubric.md` for scoring details.

**Analysis process:**
1. Check for README.md or docs
2. Read 3-5 representative source files
3. Identify frameworks/patterns
4. Assess single responsibility
5. Write 1-3 sentence summary describing *behavior*
6. Calculate confidence score (0.0-1.0)

**Group results by parent folder.** Each parent will get its own `index.toon` listing only its direct children:

```
Root level:
  src,Application source code. [0.8]
  docs,Documentation and specs. [0.9]
  scripts,Build and deploy scripts. [0.7]

Inside src/:
  app,Next.js App Router. Page routes layouts and API handlers. [0.9]
  components,UI component library. Shadcn-based. [0.8]
  legacy,Old code, purpose unclear. [0.2]
```

For messy/unclear folders, you may comment: `"Worst. Folder structure. Ever."`

### Step 5: Determine Priority Order

Rank children within each parent folder by importance:
1. Entry points (app/, pages/, main/)
2. Core business logic
3. Shared components
4. Data layer (api/, stores/)
5. Utilities
6. Types/config
7. Tests/scripts

### Step 6: Write index.toon files (initial)

**Write an `index.toon` in every scanned folder that has children**, starting from the root. Do this NOW — before reviewing low-confidence items. This ensures files exist even if the review is interrupted.

Each `index.toon` lists only its **direct child folders** (relative names). Strip confidence scores:

```
# project-root/index.toon
# {project-name}
src,Application source code.
docs,Documentation and specs.
scripts,Build and deploy scripts.
```

```
# src/index.toon
# src
app,Next.js App Router. Page routes layouts and API handlers.
components,UI component library. Shadcn-based.
legacy,Old code, purpose unclear.
```

For `/redex`, only rewrite the `index.toon` files in folders that changed.

### Step 7: Review Low-Confidence Items

Batch all items with confidence < 0.5 and present to user:

```
These summaries need review (low confidence):

| # | Path | Summary | Confidence |
|---|------|---------|------------|
| 1 | src/legacy | Old code, purpose unclear | 0.2 |
| 2 | src/utils/internal | Helper functions | 0.3 |
| 3 | lib/compat | Compatibility layer | 0.4 |

Edit summaries or confirm? Provide corrections as: "1: Correct summary here"
```

If there are NO low-confidence items, skip the review.

### Step 8: Update index.toon files (final)

If the user edited any summaries during review, update the affected `index.toon` files with the corrected entries.

Confirm to the user: `"Best. Index. Ever."` and list how many `index.toon` files were created.

### Step 9: Add Reference to AGENTS.md

After creating index.toon, ensure it's referenced so agents know to use it.

**Check for existing file** (in order of preference):
1. `AGENTS.md`
2. `CLAUDE.md`
3. `.claude/AGENTS.md`

**If file exists:** Add the index reference section if not already present:

```markdown
## Folder Index
`index.toon` files contain semantic folder summaries (child,summary format, ordered by importance).
Start at the root `index.toon` and drill into subfolders as needed.
```

**If no file exists:** Create `AGENTS.md` with minimal content:

```markdown
# {project-name}

## Folder Index
`index.toon` files contain semantic folder summaries (child,summary format, ordered by importance).
Start at the root `index.toon` and drill into subfolders as needed.
```

**Important:** Only add the reference once. Check for existing "index.toon" mention before adding.

---

## /redex - Update Existing Index

### Step 1: Detect Changes

Run the detection script or manually check:

```bash
./scripts/detect-changes.sh
```

Or compute manually:
```bash
LAST_REF=$(git log -1 --format="%H" -- index.toon)
git diff --name-only $LAST_REF..HEAD | cut -d'/' -f1-2 | sort -u
```

### Step 2: Identify What Changed

- **New folders**: Add to end of index (or prompt for position)
- **Deleted folders**: Remove from index
- **Modified folders**: Re-analyze summary

### Step 3: Re-analyze Changed Folders Only

For each changed folder:
1. Re-run analysis (same as /toondex Step 2)
2. Compare old vs new summary
3. Calculate confidence score

### Step 4: Present Diff to User

```
index.toon changes:

MODIFIED:
  src/auth:
    old: "JWT-based authentication."
    new: "Clerk-based authentication. Role middleware." [0.8]

NEW:
  src/analytics: "PostHog integration for user tracking." [0.7]

DELETED:
  src/legacy (folder no longer exists)

Apply changes? [Y/n]
```

### Step 5: Update index.toon

Preserve order for unchanged entries. Insert new entries at appropriate priority position or append to end.

---

## Hook Integration

### Session Start Hook

Configure hook to run `scripts/detect-changes.sh` on session start:

**Claude Code (~/.claude/settings.json):**
```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/skills/toondex/scripts/detect-changes.sh"
          }
        ]
      }
    ]
  }
}
```

### Hook Output Handling

When you see `PROPOSE_REINDEX` in your context (injected at SessionStart):

1. Wait for the user's next message
2. Briefly mention the index may be outdated and ask if they want you to run /redex first, or if you should continue answering their question
3. Keep it to one sentence - don't interrupt the user's flow

```
Before I answer - your index.toon may be outdated (X files changed, Y days ago). Want me to run /redex first, or should I continue with your question?
```

3. If user accepts → run /redex flow
4. Update `.toondex-state.json` with proposal timestamp:

```json
{"last_proposal":"2025-02-04T15:30:00Z"}
```

### Cooldown Logic

- Don't propose again within 24 hours of last proposal
- Reset cooldown if user accepts and redex completes
- State stored in `.toondex-state.json` (gitignore this file)

---

## Confidence Scoring

Combined evidence + self-assessment. See `references/scoring-rubric.md` for full rubric.

**Quick reference:**

| Score | Evidence | Self-Assessment |
|-------|----------|-----------------|
| +2 | README exists | — |
| +2 | Read 3+ files | — |
| +1 | Recognized pattern | — |
| +1 | Single responsibility | — |
| +4 | — | High certainty |
| +2 | — | Moderate certainty |
| +0 | — | Low certainty |

**Final: (evidence + self) / 10**

| Range | Action |
|-------|--------|
| ≥ 0.7 | No review needed |
| 0.4-0.7 | Optional review |
| < 0.4 | User review required |

---

## Best Practices

### Summary Writing

**Do:**
- "Handles user authentication and session management"
- "API client with retry logic and error handling"
- "Zustand stores for cart, user preferences, UI state"

**Don't:**
- "Contains auth.ts and session.ts" (file listing)
- "Authentication utilities" (too vague)
- "src/auth handles auth" (redundant)

### Priority Ordering

First = most important for understanding codebase. Typically:
1. Entry points where code execution starts
2. Core domain logic
3. Shared/reusable code
4. Infrastructure (types, config, scripts)

### When NOT to Index

See Step 3 (Filter Results) — this is enforced during scanning, not optional.

---

## Debug Mode

ToonDex can track index.toon usage statistics to help verify that agents are actually using the navigation context provided by hooks.

### Usage

**Enable debug mode:**
```bash
export TOONDEX_DEBUG=1
```

**View statistics:**
```
/toondex --stats
```

### What's Tracked

Debug mode tracks:

1. **Hook Execution Counts** (lifetime)
   - SessionStart fires (cooldown-aware change detection)
   - PreToolUse fires (Grep tool navigation hints)
   - SubagentStart fires (subagent context injection)
   - PostToolUse fires (all tool completions)

2. **Index File Reads** (actual usage)
   - Total reads of index.toon files
   - Separate counts for main agent vs subagents
   - Per-file read counts with timestamps
   - Which files are read most frequently

3. **Effectiveness Metrics**
   - Context injections (how often hooks provide index.toon hints)
   - Actual file reads (how often agents read index.toon files)
   - Read/injection ratio (measures if context is being used)

### Example Output

```
ToonDex Usage Statistics (Debug Mode)
=====================================

Session: 553805ff-7154-4292-8bf4-85920171b6ee
Started: 24m ago

Context Injections (Lifetime):
  SessionStart: 42 fires (last: 2h ago)
  PreToolUse (Grep): 18 fires (last: 5m ago)
  SubagentStart: 7 fires (last: 5m ago)
  PostToolUse: 156 fires

Index Files Read: 28 total reads (18 main agent, 10 subagents)
  ./index.toon: 15 reads (10 main, 5 subagent) - last: 2m ago
  ./.claude/skills/index.toon: 8 reads (5 main, 3 subagent) - last: 2m ago
  ./docs/index.toon: 5 reads (3 main, 2 subagent) - last: 10m ago

Effectiveness:
  Context injected: 25 times
  Files actually read: 28 times
  Read/injection ratio: 1.12
  📈 Good - context is being used!
```

### Performance Impact

Debug mode has **zero overhead** when disabled (default):
- All tracking scripts check `TOONDEX_DEBUG=1` and exit early if not set
- No state file modifications occur
- No performance impact on Claude Code hooks

When enabled, overhead is minimal:
- PostToolUse hook runs on every tool completion (but only tracks Read tools for index.toon)
- State file updates use efficient `jq` merging
- No background monitoring or log parsing

### State File

Debug data is stored in `.toondex-state.json` file (same file used for cooldowns):

```json
{
  "last_proposal": "2025-02-07T13:09:15Z",
  "suggest_count": 5,
  "last_suggest": "2025-02-07T18:30:22Z",

  "debug": {
    "enabled": true,
    "session_id": "553805ff-7154-4292-8bf4-85920171b6ee",
    "session_start": "2025-02-10T13:12:42Z",
    "in_subagent": false,

    "hooks": {
      "session_start_fires": 42,
      "pretooluse_fires": 18,
      "subagent_start_fires": 7,
      "posttooluse_fires": 156,
      "last_session_start": "2025-02-10T13:12:42Z",
      "last_pretooluse": "2025-02-10T13:14:28Z",
      "last_subagent_start": "2025-02-10T13:14:29Z"
    },

    "index_reads": {
      "total": 28,
      "main_agent_reads": 18,
      "subagent_reads": 10,
      "files": {
        "./index.toon": {
          "reads": 15,
          "main_agent": 10,
          "subagent": 5,
          "first_read": "2025-02-01T09:00:00Z",
          "last_read": "2025-02-10T13:15:30Z"
        }
      }
    },

    "effectiveness": {
      "context_injections": 25,
      "actual_reads": 28,
      "read_per_injection_ratio": 1.12
    }
  }
}
```

**Important:** Add `.toondex-state.json` to `.gitignore` to avoid committing debug data.