I created this tool for myself and talked about it in this video and this X post. People requested it, so here it is! This works alongside my Claude Code Docs mirror project.
I may post videos explaining how I use this project - check my X/Twitter for updates and explanations.
This isn't a product - just a tool that solves Claude Code's architectural blindness for me. Fork it, improve it, make it yours!
Automatically gives Claude Code architectural awareness of your codebase. Add -i to any prompt to generate or update a PROJECT_INDEX.json containing your project's functions, classes, and structure.
curl -fsSL https://raw.githubusercontent.com/ericbuess/claude-code-project-index/main/install.sh | bashJust add -i to any Claude prompt:
claude "fix the auth bug -i" # Auto-creates/uses index (default 50k)
claude "refactor database code -i75" # Target ~75k tokens (if project needs it)
claude "analyze architecture -ic200" # Export up to 200k to clipboard for external AI
# Or manually create/update the index anytime
/indexKey behaviors:
- One-time setup: Use
-ionce in a project and the index auto-updates forever - Size memory: The number (e.g., 75) is remembered until you specify a new one
- Auto-maintenance: Every file change triggers automatic index updates
- To stop indexing: Simply delete PROJECT_INDEX.json
PROJECT_INDEX extracts and tracks:
- Functions & Classes: Full signatures with parameters and return types
- Call Relationships: Which functions call which others
- File Organization: All code files respecting .gitignore
- Directory Structure: Project layout with file counts
This helps Claude:
- Find the right code without searching
- Understand dependencies before making changes
- Place new code in the correct location
- Avoid creating duplicate functions
# Reference directly in your prompt
@PROJECT_INDEX.json what functions call authenticate_user?
# Or auto-load in every session by adding to CLAUDE.md:
# Add @PROJECT_INDEX.json to your CLAUDE.md fileBest for: Small projects where the index fits comfortably in context. Gives Claude's main agent direct awareness of your whole project structure.
# Invokes specialized subagent to analyze PROJECT_INDEX.json
claude "refactor the auth system -i" # Default up to 50k tokens
claude "find performance issues -i75" # Target ~75k tokens for more detailBest for: Medium to large projects where you want to preserve the main agent's context. The subagent analyzes the index separately and returns only relevant findings.
The subagent provides:
- Call graph analysis and execution paths
- Dependency mapping and impact analysis
- Dead code detection
- Strategic recommendations on where to make changes
# Export to clipboard for external AI with larger contexts
claude "analyze entire codebase -ic200" # Up to 200k tokens
claude "architecture review -ic800" # Up to 800k tokensBest for: Very large projects whose index won't fit in Claude's context window. Export to AI models with larger context windows:
- Gemini Pro (2M tokens)
- Claude models with 200k+ tokens
- ChatGPT
- Grok
Note: I'm not using this on large projects myself yet - this is inspiration/theory. Your mileage may vary. If you hit snags, have Claude Code update it to work for your specific use case!
The number after -i is a maximum target, not a guaranteed size:
- Default: 50k tokens (remembered per project)
- -i mode range: 1k to 100k maximum
- -ic mode range: 1k to 800k maximum for external AI
- Actual size: Often much smaller - only uses what the project needs
- Compression: Automatic to fit within limits
Examples:
- Small project with
-i200: Might only generate 10k tokens - Large project with
-i50: Compresses to fit ~50k target - Huge project with
-ic500: Allows up to 500k if needed
The tool remembers your last -i size per project and targets that amount, but actual size depends on your codebase.
Full parsing (extracts functions, classes, methods):
- Python (.py)
- JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
- Shell scripts (.sh, .bash)
File tracking (listing only):
- Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, and 20+ more
- Location:
~/.claude-code-project-index/ - Hooks configured:
UserPromptSubmit: Detects -i flagStop: Refreshes index after session
- Commands:
/indexfor manual creation/update - Agent:
~/.claude/agents/index-analyzer.mdfor deep analysis - Python: Automatically finds newest 3.8+ version
The whole point of this tool is that Claude Code can unbobble it for you! When you hit issues, don't wait for me - have Claude fix them immediately. This is a community tool meant to be forked and adapted.
How to customize:
- Fork the repo or work with the installed version
- Describe your problem to Claude Code
- Let Claude modify it for your exact needs
- Share your improvements with others
Common customizations:
cd ~/.claude-code-project-index
# Then ask Claude:
# "The indexer hangs on my 5000 file project - fix it"
# "Add support for Ruby and Go files with full parsing"
# "Skip test files and node_modules even if not in .gitignore"
# "Make it work with my monorepo structure"
# "Change compression to handle my specific project better"Remember: Claude Code can rewrite this entire tool in minutes to match your needs. That's the power you have - use it!
Large projects (>2000 files): May timeout or hang during compression
- Fix: Ask Claude "Rewrite compress_if_needed() to handle my 3000 file project"
.claude directory: Already fixed - now excluded from indexing
Timeouts: Default is 30 seconds, may be too short for huge projects
- Fix: Ask Claude "Make timeout dynamic based on file count in i_flag_hook.py"
For any issue, just describe it to Claude and let it fix the tool for you!
- Python 3.8 or higher
- Claude Code with hooks support
- macOS or Linux
- git and jq (for installation)
Index not creating?
- Check Python:
python3 --version - Verify hooks:
cat ~/.claude/settings.json | grep i_flag_hook - Manual generation:
python3 ~/.claude-code-project-index/scripts/project_index.py
-i flag not working?
- Run installer again
- Check hooks are configured
- Remove and reinstall if needed
Clipboard issues?
- Install pyperclip:
pip install pyperclip - SSH users: Content saved to
.clipboard_content.txt - For unlimited clipboard over SSH: VM Bridge
The index uses a compressed format to save ~50% space:
- Minified JSON (single line) for file storage
- Short keys:
f→files,g→graph,d→docs,deps→dependencies - Compact function signatures with line numbers
- Clipboard mode (
-ic) uses readable formatting for external AI tools
~/.claude-code-project-index/uninstall.shCreated by Eric Buess
