ToonDex

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

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

Commands

/toondex --stats

Display ToonDex usage statistics (requires TOONDEX_DEBUG=1).

Implementation: Run the statistics script:

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

Or directly from project root:

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

/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.json 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.json (gitignore this file)

Confidence Scoring

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

Quick reference:

Final: (evidence + self) / 10

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:

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

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