toon-dex

name

toon-dex

description

Semantic folder index for codebase navigation. Generates index.toon files with concise folder summaries ordered by importance, enabling fast LLM codebase traversal without reading every file. Commands: /toondex (create initial index), /redex (update with changes). Use when the user wants to index a codebase, understand project structure, map codebase folders, index project layout, navigate a large codebase, understand folder structure, or asks about /toondex or /redex commands.

ToonDex

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

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

When to use

• User runs /toondex — create a new index.toon index from scratch
• User runs /redex — update an existing index after code changes
• Context contains PROPOSE_REINDEX (injected by SessionStart hook) — on the user's next message, briefly ask if they want to run /redex first or continue. One sentence only, e.g.: "Your index.toon may be outdated (X files changed) — run /redex first, or continue?"

Instructions

Commands

Command	Purpose
/toondex	Create initial index.toon (interactive)
/redex	Update index.toon with changes

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

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

Step 1: Ask Traversal Depth

Before scanning, 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):

/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):

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:

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

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

./scripts/detect-changes.sh

Or compute manually:

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):

{
  "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 with proposal timestamp:

{"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 (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.