ToonDex creates semantic folder indexes for LLM codebase navigation. It generates an index.toon file with concise summaries of each folder, ordered by importance.
93
Quality
93%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
#!/bin/bash
# Initialize ToonDex in a project
# Usage: ./init.sh [target-project-dir]
# "Oh, I see you've discovered my meticulously organized archive."
set -e
TARGET_DIR="${1:-.}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"
echo "📚 Installing ToonDex..."
echo " \"Oh, I see you've discovered my meticulously organized archive.\""
echo ""
# Create .claude directory if needed
mkdir -p "$TARGET_DIR/.claude/skills/toondex/scripts"
mkdir -p "$TARGET_DIR/.claude/skills/toondex/references"
# Copy skill files
cp "$SKILL_DIR/SKILL.md" "$TARGET_DIR/.claude/skills/toondex/"
cp "$SKILL_DIR/scripts/detect-changes.sh" "$TARGET_DIR/.claude/skills/toondex/scripts/"
cp "$SKILL_DIR/scripts/detect-changes.ps1" "$TARGET_DIR/.claude/skills/toondex/scripts/"
cp "$SKILL_DIR/references/scoring-rubric.md" "$TARGET_DIR/.claude/skills/toondex/references/"
# Make script executable
chmod +x "$TARGET_DIR/.claude/skills/toondex/scripts/detect-changes.sh"
# Create or update settings.json
SETTINGS_FILE="$TARGET_DIR/.claude/settings.json"
if [ -f "$SETTINGS_FILE" ]; then
# Check if hooks already configured
if grep -q "SessionStart" "$SETTINGS_FILE"; then
echo "⚠️ SessionStart hook already exists in settings.json"
echo " Please manually add the toondex hook if needed."
else
echo "📝 Adding hooks to existing settings.json..."
# Use a temp file for safe editing
python3 -c "
import json
import sys
with open('$SETTINGS_FILE', 'r') as f:
settings = json.load(f)
settings['hooks'] = settings.get('hooks', {})
settings['hooks']['SessionStart'] = [
{
'matcher': 'startup|resume',
'hooks': [
{
'type': 'command',
'command': '\"\$CLAUDE_PROJECT_DIR\"/.claude/skills/toondex/scripts/detect-changes.sh'
}
]
}
]
with open('$SETTINGS_FILE', 'w') as f:
json.dump(settings, f, indent=2)
" 2>/dev/null || echo "⚠️ Could not auto-update settings.json. Please add hooks manually."
fi
else
echo "📝 Creating settings.json..."
cat > "$SETTINGS_FILE" << 'EOF'
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"hooks": {
"SessionStart": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/skills/toondex/scripts/detect-changes.sh"
}
]
}
]
}
}
EOF
fi
# Add .toondex-state to gitignore
GITIGNORE="$TARGET_DIR/.gitignore"
if [ -f "$GITIGNORE" ]; then
if ! grep -q "^\.toondex-state$" "$GITIGNORE"; then
echo "" >> "$GITIGNORE"
echo "# ToonDex state" >> "$GITIGNORE"
echo ".toondex-state" >> "$GITIGNORE"
echo ".toondex-propose" >> "$GITIGNORE"
echo "📝 Added ToonDex files to .gitignore"
fi
else
echo "# ToonDex state" > "$GITIGNORE"
echo ".toondex-state" >> "$GITIGNORE"
echo ".toondex-propose" >> "$GITIGNORE"
echo "📝 Created .gitignore with ToonDex files"
fi
# Add index.toon reference to AGENTS.md or CLAUDE.md
INDEX_REF='## Folder Index
`index.toon` contains semantic folder summaries (path,summary format, ordered by importance).
Read this before navigating unfamiliar parts of the codebase.'
AGENTS_FILE=""
if [ -f "$TARGET_DIR/AGENTS.md" ]; then
AGENTS_FILE="$TARGET_DIR/AGENTS.md"
elif [ -f "$TARGET_DIR/CLAUDE.md" ]; then
AGENTS_FILE="$TARGET_DIR/CLAUDE.md"
elif [ -f "$TARGET_DIR/.claude/AGENTS.md" ]; then
AGENTS_FILE="$TARGET_DIR/.claude/AGENTS.md"
fi
if [ -n "$AGENTS_FILE" ]; then
if ! grep -q "index.toon" "$AGENTS_FILE"; then
echo "" >> "$AGENTS_FILE"
echo "$INDEX_REF" >> "$AGENTS_FILE"
echo "📝 Added index.toon reference to $(basename $AGENTS_FILE)"
else
echo "ℹ️ index.toon already referenced in $(basename $AGENTS_FILE)"
fi
else
# Create AGENTS.md with minimal content
PROJECT_NAME=$(basename "$TARGET_DIR")
cat > "$TARGET_DIR/AGENTS.md" << EOF
# $PROJECT_NAME
$INDEX_REF
EOF
echo "📝 Created AGENTS.md with index.toon reference"
fi
echo ""
echo "✅ ToonDex installed successfully!"
echo " \"Best. Index. Ever.\""
echo ""
echo "Next steps:"
echo " 1. Run /toondex to create your first index.toon"
echo " 2. The hook will automatically detect changes on session start"
echo " 3. Run /redex to update when needed"
echo ""Install with Tessl CLI
npx tessl i cpoepke/toon-dex