toondex

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:

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

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:

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.