Chippery Docs

Appearance

Troubleshooting ​

Common issues and solutions when using Chippery.

LLM Not Saving Tokens ​

Problem: The LLM is reading entire files instead of using token-efficient tools.

Solution: Explicitly tell the LLM to use orient and func tools:

Use /chippery-orient to find relevant files, then /chippery-func to get specific functions.
Don't read entire files - use the chippery tools instead.

You can also:

  • Switch to a stricter mode: /chippery-mode balanced-pro or /chippery-mode frugal
  • Frugal mode blocks raw file reads and requires using chippery tools

Session Management ​

Problem: Context getting cluttered with unrelated work.

Solution: Create separate sessions for specific tasks:

  • Start a new session for each distinct task
  • Use descriptive session names
  • Don't mix unrelated work in one session

Benefits:

  • Cleaner context
  • Better token efficiency
  • Easier to resume specific work

Rebuilding the Index ​

Problem: Index is outdated, missing files, or corrupted.

Solution 1: Using commands

/map-clear
/map-rebuild

Solution 2: Delete the .chippery folder

bash
rm -rf .chippery

The index will rebuild automatically on the next session start.

Solution 3: Manual rebuild via CLI

bash
chippery-indexer index-dir /path/to/project
chippery-indexer analyze /path/to/project

Index Not Building ​

Problem: Index doesn't exist and isn't being created.

Check 1: Verify you're in a git repository

bash
git status

The indexer only runs in git repos.

Check 2: Verify binaries exist

bash
ls ~/.chippery/bin/chippery-indexer
ls ~/.chippery/bin/chippery-navigator

If missing, reinstall Chippery.

Check 3: Check for errors

Look for error messages when starting a session. The indexer runs in the background and may fail silently.

Orient Returns No Results ​

Problem: /chippery-orient returns empty or unhelpful results.

Causes and Solutions:

  1. Index not ready - Wait for indexing to complete
  2. Query too vague - The LLM might need to use more specific terms: "user authentication" vs "auth"

Func Can't Find Function ​

Problem: /chippery-func can't find the function.

Check naming format:

# For class methods
/chippery-func ClassName.methodName

# For standalone functions
/chippery-func functionName

Rebuild index if needed:

/map-clear
/map-rebuild

Claude Code Hooks Not Working ​

Problem: Hooks don't run or produce errors.

Check hooks are installed:

bash
ls ~/.claude/hooks/chippery_*

Check hooks are executable:

bash
chmod +x ~/.claude/hooks/chippery_*.sh

Reinstall if needed:

bash
curl -fsSL https://chippery.ai/install.sh | bash -s -- --with-claude-code

Binary Not Found ​

Problem: Commands fail with "command not found".

Add to PATH:

bash
export PATH="$HOME/.chippery/bin:$PATH"

Add this to your shell profile (~/.bashrc, ~/.zshrc).

Verify installation:

bash
ls ~/.chippery/bin/

Should contain: chippery, chippery-indexer, chippery-navigator, etc.

Claude is not starting ​

This is typically caused by the initial indexing when the initial session in a project is started.

If you need to remove the Chippery integration, you can remove the hooks and skills inside these folders:

  • Claude Code hooks to ~/.claude/hooks/
  • Claude Code skills to ~/.claude/skills/
  • Configuration file ~/.claude/CHIPPERY.md

Getting Help ​

You can email us at [email protected] anytime.