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
Add a gitignore-style file named .claude-indexignore (or .project-index-ignore) to your project root to keep generated blobs, massive fixtures, or other irrelevant files out of the index without touching your real .gitignore. The syntax matches .gitignore, so you can reuse existing patterns, directories, or glob rules, and the filter applies automatically to /index, the -i flag, and any hook-driven refresh.
Need something temporary? Run the indexer manually with extra ignore lists:
python scripts/project_index.py --ignore-file path/to/custom.ignore
python scripts/project_index.py --ignore-file configs/ci.ignore --ignore-file ~/.config/claude/global.ignoreEach --ignore-file is optional and repeatable, and patterns match even if the files are already committed to Git.
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)
- PHP (.php)
File tracking (listing only):
- Go, Rust, Java, C/C++, Ruby, 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