New advertisers: 50% off your first month with code FIRSTMONTHSee slots
cpoepke avatar

toondex

cpoepke/Toon-Dex

Semantic folder index that gives Claude Code priority-ordered summaries of each folder for faster navigation.

version
1.0.6

What it does

  • Adds /toondex to create an index.toon file and /redex to update it after code changes
  • Writes one line per folder, with the most important folders listed first and summaries describing behavior
  • Flags low-confidence summaries for user review and re-analyzes only the folders that changed
  • Includes a session hook that proposes reindexing when the index is outdated, plus /stats for usage metrics

Semantic folder index for codebase navigation. Creates index.toon files with summaries ordered by priority. "Oh, I see you've discovered my meticulously organized archive."

Add marketplace

/plugin marketplace add cpoepke/Toon-Dex

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install toondex@toon-dex

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

/redex - Update Existing Index

WHEN THIS SKILL IS INVOKED, IMMEDIATELY BEGIN EXECUTING THE STEPS BELOW. DO NOT JUST EXPLAIN THE PROCESS - ACTUALLY RUN THE COMMANDS AND PERFORM THE ANALYSIS.

This skill updates existing index.toon files to reflect codebase changes.

CRITICAL: Execution Instructions

When this skill loads, you MUST:

  1. START IMMEDIATELY with Step 1 below (detect changes)
  2. EXECUTE each step - run git commands, read files, analyze folders
  3. DO NOT just describe what the skill does - DO IT NOW
  4. ONLY show documentation if the user explicitly asks for help

If index.toon does not exist, tell the user to run /toondex first.

Implementation Steps (Execute Now)

BEGIN EXECUTION IMMEDIATELY:

When to Use

Run /redex when:

  • Files or folders have been added, deleted, or significantly modified
  • You see a suggestion that the index may be outdated
  • You want to refresh folder summaries

What It Does

  1. Detects changes since last index via git
  2. Identifies what changed: New folders, deleted folders, modified folders
  3. Re-analyzes only the changed folders
  4. Presents a diff showing old vs new summaries
  5. Updates the affected index.toon files

Process (EXECUTE THESE STEPS NOW)

Step 1: Detect Changes (DO THIS NOW)

RUN these git commands to find changes since the last index.toon commit:

LAST_REF=$(git log -1 --format="%H" -- index.toon)
git diff --name-only $LAST_REF..HEAD

Parse the output to identify changed folders.

Step 2: Identify What Changed (DO THIS NOW)

Categorize the changes:

  • New folders: Folders created since last index
  • Deleted folders: Folders that no longer exist
  • Modified folders: Folders with file changes

Step 3: Re-analyze Changed Folders (DO THIS NOW)

For EACH changed folder, IMMEDIATELY:

  1. Read 3-5 representative source files from that folder
  2. Generate a 1-3 sentence behavioral summary
  3. Calculate confidence score (0.0-1.0)
  4. Compare with the old summary from existing index.toon

###Step 4: Present Diff (DO THIS NOW)

SHOW the user this diff format:

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 Files

After user approval:

  • Update the relevant index.toon files (only those with changes)
  • Preserve order for unchanged entries
  • Insert new entries at appropriate priority position

Auto-Detection

The SessionStart hook automatically checks if the index is outdated and may suggest running /redex when:

  • Change score exceeds threshold (see detect-changes.sh)
  • New top-level folders exist (not in index)
  • Indexed folders are deleted
  • Many files changed in indexed folders
  • More than 7 days since last index

When you see: "PROPOSE_REINDEX: index.toon may be outdated...", consider running /redex.

Examples

Updating After Code Changes

User: /redex

Claude: Detecting changes since last index...

Found changes in 3 folders:
- src/components (15 files modified)
- src/api (new folder)
- src/legacy (deleted)

Re-analyzing...

index.toon changes:

MODIFIED:
  src/components:
    old: "UI components using shadcn."
    new: "UI components using shadcn. Added form components with validation." [0.9]

NEW:
  src/api: "REST API endpoints. Express routes with middleware." [0.8]

DELETED:
  src/legacy

Apply changes? [Y/n]

When No Changes Detected

User: /redex

Claude: No significant changes detected since last index. Your index.toon is up to date!

Tips

  • Run /redex regularly to keep the index current
  • The SessionStart hook will remind you when the index is stale
  • If you see low confidence scores during update, review those summaries
  • New folders are added at the end by default - you can manually reorder them for priority

See Also

  • /toondex - Create initial index
  • /toondex --stats - View usage statistics (requires TOONDEX_DEBUG=1)

For full documentation, see the main toondex skill or plugins/toondex/skills/toondex/SKILL.md.

From the cpoepke/Toon-Dex README

ToonDex

ToonDex - Repo navigation for agents!

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

ToonDex creates semantic folder indexes for LLM codebase navigation. It generates an index.toon file with concise summaries of each folder, ordered by importance.

Installation

Claude Code Plugin

# Add the marketplace
/plugin marketplace add cpoepke/Toon-Dex

# Install ToonDex
/plugin install toondex@Toon-Dex

Manual Installation

# Clone and run init script
git clone https://github.com/cpoepke/Toon-Dex.git
./Toon-Dex/.claude/skills/toondex/scripts/init.sh /path/to/your/project

Usage

Create Index

/toondex

Creates an index.toon file with semantic folder summaries:

# my-project
src/app,Next.js App Router. Page routes layouts and API handlers.
src/components,UI component library. Shadcn-based atomic design.
src/lib,Core utilities. API client with retry logic and shared hooks.

Update Index

/redex

Detects changes since last index and updates only modified folders.

Automatic Detection

ToonDex includes a session hook that automatically detects when your index is outdated and proposes updates.

Format

# {project-name}
{path},{summary}
{path},{summary}
  • Order = Priority: First entry is most important
  • Summaries describe behavior: "Handles auth" not "Contains auth.ts"
  • State via git: No separate state file needed

See docs/INDEX_SPEC.md for the full specification.

Features

  • Semantic summaries: Describes what code does, not what files exist
  • Priority ordering: Most important folders first
  • Confidence scoring: Reviews low-confidence summaries with user
  • Incremental updates: Only re-analyzes changed folders
  • Auto-detection: Session hook proposes updates when needed
  • Cross-platform: Bash and PowerShell scripts

Catchphrases

  • On success: "Best. Index. Ever."
  • On messy code: "Worst. Folder structure. Ever."
  • On startup: "Oh, I see you've discovered my meticulously organized archive."

License

MIT - See LICENSE

Details

Marketplace
cpoepke/Toon-Dex
Source
plugins/toondex
Author
Conrad Pöpke
Category
Productivity