# Claude Code Indexer (cci)
A powerful code indexing tool that uses graph databases to analyze and understand code structure. Built specifically for Claude Code assistant workflows.
**🚀 Quick tip:** Use `cci` instead of `claude-code-indexer` for all commands!
## Features
- 📊 **Graph-based code analysis** using Ensmallen library
- 🔍 **Intelligent node ranking** based on importance and centrality
- 💾 **SQLite database** for persistent storage
- 🎯 **Relevance tagging** for different code entity types
- 📈 **Network analysis** with PageRank and centrality measures
- 🚀 **Easy CLI interface** for quick setup and usage
- 🤖 **MCP Integration** for direct Claude Desktop/Code support (v1.3.0+, Claude Code v1.14.0+)
- 🔬 **Multi-keyword search** with AND/OR logic (v1.3.0+)
- 📂 **Project-based indexing** for MCP with separate databases (v1.4.0+)
- 🚫 **Smart ignore patterns** - auto-ignores node_modules, .git, etc (v1.5.0+)
- 📝 **Respects .gitignore** and .dockerignore files (v1.5.0+)
- 🌐 **Multi-language support** - Python, JavaScript, TypeScript (v1.6.0+), Java (v1.10.0+), AutoIt (v1.11.0+)
- 🏠 **Centralized storage** - All data in ~/.claude-code-indexer/ (v1.7.0+)
- ⚡ **High-performance memory cache** - 10-100x faster with 100MB LRU cache (v1.12.0+)
- 🏗️ **Infrastructure detection** - Auto-detects databases, APIs, cloud services, DevOps tools (v1.13.0+)
- 🎯 **Professional CLI** - App name and version header on all commands (v1.13.0+)
- 🔄 **Automatic database migrations** - Seamless schema updates with backup/rollback (v1.14.0+)
## Installation
### From PyPI (Recommended)
```bash
# Basic installation
pip install claude-code-indexer
# With MCP support for Claude Desktop/Code
pip install 'claude-code-indexer[mcp]'
# After installation, use 'cci' for all commands!
```
### From Source
```bash
git clone https://github.com/anthropics/claude-code-indexer.git
cd claude-code-indexer
pip install -e .
```
### Updating
The package includes auto-update functionality:
```bash
# Check for updates
cci update --check-only
# Update to latest version
cci update
# Sync CLAUDE.md with latest template
cci sync
```
Updates will also be checked automatically when you run any command.
## What's New in v1.13.0
### 🎯 Enhanced User Experience
- **App Name & Version Display** - All CLI commands now show a professional header
- **Infrastructure Detection** - Automatically detects and tags databases, APIs, cloud services, and DevOps tools
- **GitHub Actions CI/CD** - Complete test automation with multi-platform support
### 🏗️ Infrastructure Tagging
The indexer now detects and tags infrastructure components:
- **Databases**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
- **APIs**: REST endpoints, GraphQL, gRPC, WebSocket
- **Message Queues**: Kafka, RabbitMQ, SQS, Celery
- **Cloud Services**: AWS, Azure, GCP, Docker, Kubernetes
- **DevOps Tools**: CI/CD, monitoring, deployment configurations
- **Environment Profiles**: production, staging, development
## What's New in v1.5.0
### 🚫 Smart Ignore Patterns
The indexer now automatically ignores common non-source directories:
- **Dependencies**: node_modules/, vendor/, packages/, bower_components/
- **Build outputs**: build/, dist/, target/, *.egg-info/
- **Version control**: .git/, .svn/, .hg/
- **Python**: __pycache__/, *.pyc, venv/, .env/
- **IDE**: .idea/, .vscode/, *.swp
- **And many more...**
### 📝 .gitignore Support
Automatically respects patterns from:
- `.gitignore` - Git ignore patterns
- `.dockerignore` - Docker ignore patterns
- Custom patterns via CLI or MCP
## Quick Start
### 1. Initialize in your project
```bash
cd your-project
cci init # Short and sweet!
```
This will:
- Create or update your `CLAUDE.md` file with indexing instructions
- Initialize project in centralized storage (`~/.claude-code-indexer/`)
- No local database files created in your project
### 2. Index your codebase
```bash
# Index current directory
cci index .
# Index specific directory
cci index /path/to/your/code
# Index with custom patterns
cci index . --patterns "*.py,*.js,*.ts"
# Index with custom ignore patterns
cci index . --custom-ignore "tests/" --custom-ignore "*.test.py"
# See what will be ignored before indexing
cci index . --show-ignored
```
### 3. Query your code
```bash
# Show most important code entities
cci query --important
# Show all entities of specific type
cci query --type class
# Search for specific terms (single keyword)
cci search UserModel
# Search with multiple keywords (OR logic)
cci search auth user login
# Search with multiple keywords (AND logic - must match all)
cci search database connection --mode all
# View indexing statistics
cci stats
```
### 4. Manage projects
```bash
# List all indexed projects
cci projects
# Remove a project's index
cci remove project-name
# Clean up orphaned projects
cci clean
# Query a specific project
cci query --important --project /path/to/project
```
## CLI Commands
### `init`
Initialize Claude Code Indexer in current directory.
```bash
cci init [--force]
```
Options:
- `--force`: Overwrite existing configuration
### `index`
Index source code in specified directory.
```bash
cci index PATH [options]
```
Options:
- `--patterns`: File patterns to index (default: "*.py")
- `--db`: Database file path (default: centralized storage)
- `--force`: Force re-index all files (ignore cache)
- `--workers`: Number of parallel workers (default: auto)
- `--no-cache`: Disable caching
- `--custom-ignore`: Additional ignore patterns (can be used multiple times)
- `--show-ignored`: Show what patterns are being ignored
### `query`
Query indexed code entities.
```bash
cci query [options]
```
Options:
- `--important`: Show only important nodes
- `--type`: Filter by node type (file, class, method, function)
- `--limit`: Maximum number of results (default: 20)
- `--db`: Database file path (default: centralized storage)
- `--project`: Project name/path to query (default: current directory)
### `search`
Search for code entities by name. Supports multiple keywords.
```bash
cci search TERMS... [options]
```
Options:
- `--mode`: Search mode - 'any' (OR logic) or 'all' (AND logic) (default: 'any')
- `--limit`: Maximum number of results (default: 20)
- `--db`: Database file path
Examples:
```bash
# Single keyword
cci search auth
# Multiple keywords (match any)
cci search auth user login
# Multiple keywords (must match all)
cci search database connection --mode all
```
### `stats`
Show indexing statistics.
```bash
cci stats [options]
```
Options:
- `--db`: Database file path (default: centralized storage)
- `--cache`: Show cache statistics
- `--project`: Project name/path for stats (default: current directory)
### `projects`
List all indexed projects.
```bash
cci projects [--all]
```
Options:
- `--all`: Show all projects including non-existent
### `remove`
Remove an indexed project.
```bash
cci remove PROJECT [--force]
```
Options:
- `--force`: Force removal without confirmation
### `clean`
Clean up orphaned project indexes.
```bash
cci clean
```
### `migrate`
Manage database schema migrations.
```bash
# Check and apply migrations
cci migrate
# Show what would be migrated without applying changes
cci migrate --dry-run
# Migrate to a specific version
cci migrate --target-version 1.6.0
# Force migration even if database appears corrupted
cci migrate --force
```
The migration system:
- Automatically detects current database version
- Creates backups before migration
- Rolls back on failure
- Preserves all existing data
- Supports incremental upgrades through multiple versions
### `background`
Manage background indexing service for automatic updates.
```bash
# Start the background service
cci background start
# Stop the background service
cci background stop
# Check service status
cci background status
# Set indexing interval for current project (in seconds)
cci background set-interval --interval 600 # 10 minutes
# Set default interval for all projects
cci background set-interval --interval 300 # 5 minutes (default)
# Disable background indexing for a project
cci background set-interval --project /path/to/project --interval -1
# Enable/disable the service globally
cci background config --enable
cci background config --disable
```
Background indexing automatically keeps your code indexes up-to-date:
- Default interval: 300 seconds (5 minutes)
- Configure per-project or global intervals
- Runs as a daemon process
- Only re-indexes when files have changed
- Set interval to -1 to disable for specific projects
## Database Schema
The tool creates a SQLite database with the following structure:
### code_nodes
Stores information about code entities.
```sql
CREATE TABLE code_nodes (
id INTEGER PRIMARY KEY,
node_type TEXT, -- 'file', 'class', 'method', 'function', 'import'
name TEXT, -- Entity name
path TEXT, -- File path
summary TEXT, -- Description
importance_score REAL, -- 0.0 to 1.0
relevance_tags TEXT, -- JSON array of tags
created_at TIMESTAMP
);
```
### relationships
Stores relationships between code entities.
```sql
CREATE TABLE relationships (
source_id INTEGER,
target_id INTEGER,
relationship_type TEXT, -- 'imports', 'contains', 'calls', 'inherits'
weight REAL,
created_at TIMESTAMP
);
```
## Integration with Claude Code
After running `cci init`, your `CLAUDE.md` file will include:
- Complete setup instructions
- Database schema documentation
- CLI command reference
- Usage examples for Claude Code workflows
## MCP Integration for Claude Desktop/Code (v1.3.0+)
Direct integration with Claude Desktop and Claude Code using Model Context Protocol:
**Claude Desktop**: Supported since v1.3.0
**Claude Code**: Supported since v1.14.0
### Quick Setup
```bash
# Install with MCP support
pip install 'claude-code-indexer[mcp]'
# Auto-configure Claude Desktop/Code (auto-detects which is installed)
cci mcp install
# Check status
cci mcp status
```
### MCP Tools Available
Once installed, Claude Desktop or Claude Code can directly use:
#### Core Tools
- **index_codebase(project_path, workers=4, force=False, custom_ignore=[])**: Index Python projects
- **get_project_stats(project_path)**: View code statistics and overview
- **query_important_code(project_path, limit=20, node_type=None)**: Find important components
- **search_code(project_path, terms, limit=10, mode="any")**: Multi-keyword search
- **manage_cache(project_path, action, days=30)**: Control indexing cache
#### New in v1.5.0
- **get_ignore_patterns(project_path)**: View active ignore patterns
- **list_indexed_projects()**: List all indexed projects
### Configuration Paths
The MCP installer automatically detects and configures the appropriate Claude app:
**Claude Desktop**:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
**Claude Code**:
- macOS: `~/Library/Application Support/Claude Code/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude Code\claude_desktop_config.json`
- Linux: `~/.config/Claude Code/claude_desktop_config.json`
### MCP Usage Examples
```python
# Index a project (ignores node_modules, .git, etc automatically)
index_codebase("/path/to/project")
# Index with custom ignore patterns
index_codebase("/path/to/project", custom_ignore=["tests/", "*.test.py"])
# Search with multiple keywords
search_code("/path/to/project", "auth user login", mode="all")
# Check what's being ignored
get_ignore_patterns("/path/to/project")
```
### Benefits
- **Zero friction**: No need to type CLI commands in Claude Desktop
- **Auto-indexing**: Projects indexed when opened
- **Rich UI**: Visual code exploration
- **Session persistence**: Maintains context between chats
## Graph Analysis Features
### Node Importance Scoring
- **Degree centrality**: Based on number of connections
- **PageRank**: Overall importance in the dependency graph
- **Weighted scoring**: Combines multiple centrality measures
### Relevance Tags
- `structural`: Classes and main components
- `highly-used`: Entities with many incoming dependencies
- `complex`: Entities with many outgoing dependencies
- `test`: Test-related code
- `module`: File-level entities
### Advanced Analysis
- **Hub detection**: Find central components in your architecture
- **Dependency tracking**: Understand code relationships
- **Impact analysis**: Trace how changes propagate
- **Similarity detection**: Find related code patterns
## Performance & Caching
### Memory Cache (v1.12.0+)
Claude Code Indexer includes a high-performance memory cache that dramatically improves performance for frequently accessed data:
- **100MB LRU Memory Cache**: Keeps hot data in memory for instant access
- **10-100x Faster**: Memory cache hits complete in <1ms vs 10-50ms for disk
- **Automatic Management**: LRU eviction and TTL-based expiration
- **Entity-Specific Policies**: Different cache strategies per entity type
### Cache Statistics
View detailed cache performance metrics:
```bash
# Show cache statistics with project stats
cci stats --cache
# Standalone cache management
cci cache
# Clear old cache entries
cci cache --clear --days 7
```
### Performance Benchmarks
#### Real-World Performance
- **Indexing Speed**: 22.4 files/sec (fresh index)
- **Cache Speedup**: 64.6x faster on subsequent runs
- **LLM Enhancement**: 1,116 nodes/sec
## Development
### Running Tests
Tests can be run in parallel for faster execution:
```bash
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests in parallel (auto-detect CPU cores)
pytest -n auto
# Run tests in parallel with specific worker count
pytest -n 4
# Run tests sequentially (default)
pytest
# Run tests with coverage in parallel
pytest -n auto --cov=claude_code_indexer --cov-report=term
```
Parallel test execution is powered by `pytest-xdist` and can significantly speed up test runs on multi-core systems.
**Note**: Some tests may fail when run in parallel due to shared resources (e.g., database files, cache directories). If you encounter failures with parallel execution, try running tests sequentially or with fewer workers.
- **Memory Usage**: <100MB for thousands of files
#### Scalability
| Project Size | Files | Time | Speed | Cache Speedup |
|-------------|-------|------|-------|---------------|
| Small | 50 | 2.3s | 22 files/s | 10-20x |
| Medium | 500 | 9.0s | 55 files/s | 30-50x |
| Large | 2000 | 21.6s | 93 files/s | 50-100x |
See [PERFORMANCE_BENCHMARKS.md](PERFORMANCE_BENCHMARKS.md) for detailed analysis.
### Performance Tips
1. **First Run**: Initial indexing populates both disk and memory cache
2. **Subsequent Runs**: Unchanged files load from memory cache (instant)
3. **Memory Usage**: Default 100MB limit with automatic eviction
4. **TTL Policies**: Files (7 days), Functions (3 days), Imports (1 day)
## Examples
### Basic Usage
```python
from claude_code_indexer import CodeGraphIndexer
# Create indexer
indexer = CodeGraphIndexer("my_project.db")
# Index a directory
indexer.index_directory("./src")
# Query important nodes
important_nodes = indexer.query_important_nodes(min_score=0.5)
for node in important_nodes:
print(f"{node['name']} ({node['node_type']}): {node['importance_score']}")
```
### Advanced Analysis
```python
# Get graph statistics
stats = indexer.get_stats()
print(f"Total nodes: {stats['total_nodes']}")
print(f"Node types: {stats['node_types']}")
# Build NetworkX graph for custom analysis
nx_graph = indexer.build_graph()
import networkx as nx
centrality = nx.betweenness_centrality(nx_graph)
```
## Requirements
- Python 3.8+
- ensmallen >= 0.8.0
- networkx >= 3.0
- pandas >= 1.5.0
- click >= 8.0.0
- rich >= 13.0.0
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
- 📖 [Documentation](https://docs.anthropic.com/claude-code)
- 🐛 [Issues](https://github.com/claude-ai/code-indexer/issues)
- 💬 [Discussions](https://github.com/claude-ai/code-indexer/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-code-indexer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Tony Nguyen <tony@startupascent.net>",
"keywords": "code-indexing, graph-database, ensmallen, claude, code-analysis, ast, development-tools",
"author": null,
"author_email": "Tony Nguyen <tony@startupascent.net>",
"download_url": "https://files.pythonhosted.org/packages/ce/30/39760defb30e032628c0ee34967cd205d32bff7835ba80c5ac306a4e54ac/claude_code_indexer-1.21.2.tar.gz",
"platform": null,
"description": "# Claude Code Indexer (cci)\n\nA powerful code indexing tool that uses graph databases to analyze and understand code structure. Built specifically for Claude Code assistant workflows.\n\n**\ud83d\ude80 Quick tip:** Use `cci` instead of `claude-code-indexer` for all commands!\n\n## Features\n\n- \ud83d\udcca **Graph-based code analysis** using Ensmallen library\n- \ud83d\udd0d **Intelligent node ranking** based on importance and centrality\n- \ud83d\udcbe **SQLite database** for persistent storage\n- \ud83c\udfaf **Relevance tagging** for different code entity types\n- \ud83d\udcc8 **Network analysis** with PageRank and centrality measures\n- \ud83d\ude80 **Easy CLI interface** for quick setup and usage\n- \ud83e\udd16 **MCP Integration** for direct Claude Desktop/Code support (v1.3.0+, Claude Code v1.14.0+)\n- \ud83d\udd2c **Multi-keyword search** with AND/OR logic (v1.3.0+)\n- \ud83d\udcc2 **Project-based indexing** for MCP with separate databases (v1.4.0+)\n- \ud83d\udeab **Smart ignore patterns** - auto-ignores node_modules, .git, etc (v1.5.0+)\n- \ud83d\udcdd **Respects .gitignore** and .dockerignore files (v1.5.0+)\n- \ud83c\udf10 **Multi-language support** - Python, JavaScript, TypeScript (v1.6.0+), Java (v1.10.0+), AutoIt (v1.11.0+)\n- \ud83c\udfe0 **Centralized storage** - All data in ~/.claude-code-indexer/ (v1.7.0+)\n- \u26a1 **High-performance memory cache** - 10-100x faster with 100MB LRU cache (v1.12.0+)\n- \ud83c\udfd7\ufe0f **Infrastructure detection** - Auto-detects databases, APIs, cloud services, DevOps tools (v1.13.0+)\n- \ud83c\udfaf **Professional CLI** - App name and version header on all commands (v1.13.0+)\n- \ud83d\udd04 **Automatic database migrations** - Seamless schema updates with backup/rollback (v1.14.0+)\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Basic installation\npip install claude-code-indexer\n\n# With MCP support for Claude Desktop/Code\npip install 'claude-code-indexer[mcp]'\n\n# After installation, use 'cci' for all commands!\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/anthropics/claude-code-indexer.git\ncd claude-code-indexer\npip install -e .\n```\n\n### Updating\n\nThe package includes auto-update functionality:\n\n```bash\n# Check for updates\ncci update --check-only\n\n# Update to latest version\ncci update\n\n# Sync CLAUDE.md with latest template\ncci sync\n```\n\nUpdates will also be checked automatically when you run any command.\n\n## What's New in v1.13.0\n\n### \ud83c\udfaf Enhanced User Experience\n- **App Name & Version Display** - All CLI commands now show a professional header\n- **Infrastructure Detection** - Automatically detects and tags databases, APIs, cloud services, and DevOps tools\n- **GitHub Actions CI/CD** - Complete test automation with multi-platform support\n\n### \ud83c\udfd7\ufe0f Infrastructure Tagging\nThe indexer now detects and tags infrastructure components:\n- **Databases**: PostgreSQL, MySQL, MongoDB, Redis, SQLite\n- **APIs**: REST endpoints, GraphQL, gRPC, WebSocket\n- **Message Queues**: Kafka, RabbitMQ, SQS, Celery\n- **Cloud Services**: AWS, Azure, GCP, Docker, Kubernetes\n- **DevOps Tools**: CI/CD, monitoring, deployment configurations\n- **Environment Profiles**: production, staging, development\n\n## What's New in v1.5.0\n\n### \ud83d\udeab Smart Ignore Patterns\n\nThe indexer now automatically ignores common non-source directories:\n- **Dependencies**: node_modules/, vendor/, packages/, bower_components/\n- **Build outputs**: build/, dist/, target/, *.egg-info/\n- **Version control**: .git/, .svn/, .hg/\n- **Python**: __pycache__/, *.pyc, venv/, .env/\n- **IDE**: .idea/, .vscode/, *.swp\n- **And many more...**\n\n### \ud83d\udcdd .gitignore Support\n\nAutomatically respects patterns from:\n- `.gitignore` - Git ignore patterns\n- `.dockerignore` - Docker ignore patterns\n- Custom patterns via CLI or MCP\n\n## Quick Start\n\n### 1. Initialize in your project\n\n```bash\ncd your-project\ncci init # Short and sweet!\n```\n\nThis will:\n- Create or update your `CLAUDE.md` file with indexing instructions\n- Initialize project in centralized storage (`~/.claude-code-indexer/`)\n- No local database files created in your project\n\n### 2. Index your codebase\n\n```bash\n# Index current directory\ncci index .\n\n# Index specific directory\ncci index /path/to/your/code\n\n# Index with custom patterns\ncci index . --patterns \"*.py,*.js,*.ts\"\n\n# Index with custom ignore patterns\ncci index . --custom-ignore \"tests/\" --custom-ignore \"*.test.py\"\n\n# See what will be ignored before indexing\ncci index . --show-ignored\n```\n\n### 3. Query your code\n\n```bash\n# Show most important code entities\ncci query --important\n\n# Show all entities of specific type\ncci query --type class\n\n# Search for specific terms (single keyword)\ncci search UserModel\n\n# Search with multiple keywords (OR logic)\ncci search auth user login\n\n# Search with multiple keywords (AND logic - must match all)\ncci search database connection --mode all\n\n# View indexing statistics\ncci stats\n```\n\n### 4. Manage projects\n\n```bash\n# List all indexed projects\ncci projects\n\n# Remove a project's index\ncci remove project-name\n\n# Clean up orphaned projects\ncci clean\n\n# Query a specific project\ncci query --important --project /path/to/project\n```\n\n## CLI Commands\n\n### `init`\nInitialize Claude Code Indexer in current directory.\n\n```bash\ncci init [--force]\n```\n\nOptions:\n- `--force`: Overwrite existing configuration\n\n### `index`\nIndex source code in specified directory.\n\n```bash\ncci index PATH [options]\n```\n\nOptions:\n- `--patterns`: File patterns to index (default: \"*.py\")\n- `--db`: Database file path (default: centralized storage)\n- `--force`: Force re-index all files (ignore cache)\n- `--workers`: Number of parallel workers (default: auto)\n- `--no-cache`: Disable caching\n- `--custom-ignore`: Additional ignore patterns (can be used multiple times)\n- `--show-ignored`: Show what patterns are being ignored\n\n### `query`\nQuery indexed code entities.\n\n```bash\ncci query [options]\n```\n\nOptions:\n- `--important`: Show only important nodes\n- `--type`: Filter by node type (file, class, method, function)\n- `--limit`: Maximum number of results (default: 20)\n- `--db`: Database file path (default: centralized storage)\n- `--project`: Project name/path to query (default: current directory)\n\n### `search`\nSearch for code entities by name. Supports multiple keywords.\n\n```bash\ncci search TERMS... [options]\n```\n\nOptions:\n- `--mode`: Search mode - 'any' (OR logic) or 'all' (AND logic) (default: 'any')\n- `--limit`: Maximum number of results (default: 20)\n- `--db`: Database file path\n\nExamples:\n```bash\n# Single keyword\ncci search auth\n\n# Multiple keywords (match any)\ncci search auth user login\n\n# Multiple keywords (must match all)\ncci search database connection --mode all\n```\n\n### `stats`\nShow indexing statistics.\n\n```bash\ncci stats [options]\n```\n\nOptions:\n- `--db`: Database file path (default: centralized storage)\n- `--cache`: Show cache statistics\n- `--project`: Project name/path for stats (default: current directory)\n\n### `projects`\nList all indexed projects.\n\n```bash\ncci projects [--all]\n```\n\nOptions:\n- `--all`: Show all projects including non-existent\n\n### `remove`\nRemove an indexed project.\n\n```bash\ncci remove PROJECT [--force]\n```\n\nOptions:\n- `--force`: Force removal without confirmation\n\n### `clean`\nClean up orphaned project indexes.\n\n```bash\ncci clean\n```\n\n### `migrate`\nManage database schema migrations.\n\n```bash\n# Check and apply migrations\ncci migrate\n\n# Show what would be migrated without applying changes\ncci migrate --dry-run\n\n# Migrate to a specific version\ncci migrate --target-version 1.6.0\n\n# Force migration even if database appears corrupted\ncci migrate --force\n```\n\nThe migration system:\n- Automatically detects current database version\n- Creates backups before migration\n- Rolls back on failure\n- Preserves all existing data\n- Supports incremental upgrades through multiple versions\n\n### `background`\nManage background indexing service for automatic updates.\n\n```bash\n# Start the background service\ncci background start\n\n# Stop the background service\ncci background stop\n\n# Check service status\ncci background status\n\n# Set indexing interval for current project (in seconds)\ncci background set-interval --interval 600 # 10 minutes\n\n# Set default interval for all projects\ncci background set-interval --interval 300 # 5 minutes (default)\n\n# Disable background indexing for a project\ncci background set-interval --project /path/to/project --interval -1\n\n# Enable/disable the service globally\ncci background config --enable\ncci background config --disable\n```\n\nBackground indexing automatically keeps your code indexes up-to-date:\n- Default interval: 300 seconds (5 minutes)\n- Configure per-project or global intervals\n- Runs as a daemon process\n- Only re-indexes when files have changed\n- Set interval to -1 to disable for specific projects\n\n## Database Schema\n\nThe tool creates a SQLite database with the following structure:\n\n### code_nodes\nStores information about code entities.\n\n```sql\nCREATE TABLE code_nodes (\n id INTEGER PRIMARY KEY,\n node_type TEXT, -- 'file', 'class', 'method', 'function', 'import'\n name TEXT, -- Entity name\n path TEXT, -- File path\n summary TEXT, -- Description\n importance_score REAL, -- 0.0 to 1.0\n relevance_tags TEXT, -- JSON array of tags\n created_at TIMESTAMP\n);\n```\n\n### relationships\nStores relationships between code entities.\n\n```sql\nCREATE TABLE relationships (\n source_id INTEGER,\n target_id INTEGER,\n relationship_type TEXT, -- 'imports', 'contains', 'calls', 'inherits'\n weight REAL,\n created_at TIMESTAMP\n);\n```\n\n## Integration with Claude Code\n\nAfter running `cci init`, your `CLAUDE.md` file will include:\n\n- Complete setup instructions\n- Database schema documentation\n- CLI command reference\n- Usage examples for Claude Code workflows\n\n## MCP Integration for Claude Desktop/Code (v1.3.0+)\n\nDirect integration with Claude Desktop and Claude Code using Model Context Protocol:\n\n**Claude Desktop**: Supported since v1.3.0\n**Claude Code**: Supported since v1.14.0\n\n### Quick Setup\n\n```bash\n# Install with MCP support\npip install 'claude-code-indexer[mcp]'\n\n# Auto-configure Claude Desktop/Code (auto-detects which is installed)\ncci mcp install\n\n# Check status\ncci mcp status\n```\n\n### MCP Tools Available\n\nOnce installed, Claude Desktop or Claude Code can directly use:\n\n#### Core Tools\n- **index_codebase(project_path, workers=4, force=False, custom_ignore=[])**: Index Python projects\n- **get_project_stats(project_path)**: View code statistics and overview\n- **query_important_code(project_path, limit=20, node_type=None)**: Find important components\n- **search_code(project_path, terms, limit=10, mode=\"any\")**: Multi-keyword search\n- **manage_cache(project_path, action, days=30)**: Control indexing cache\n\n#### New in v1.5.0\n- **get_ignore_patterns(project_path)**: View active ignore patterns\n- **list_indexed_projects()**: List all indexed projects\n\n### Configuration Paths\n\nThe MCP installer automatically detects and configures the appropriate Claude app:\n\n**Claude Desktop**:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Claude Code**:\n- macOS: `~/Library/Application Support/Claude Code/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude Code\\claude_desktop_config.json`\n- Linux: `~/.config/Claude Code/claude_desktop_config.json`\n\n### MCP Usage Examples\n\n```python\n# Index a project (ignores node_modules, .git, etc automatically)\nindex_codebase(\"/path/to/project\")\n\n# Index with custom ignore patterns\nindex_codebase(\"/path/to/project\", custom_ignore=[\"tests/\", \"*.test.py\"])\n\n# Search with multiple keywords\nsearch_code(\"/path/to/project\", \"auth user login\", mode=\"all\")\n\n# Check what's being ignored\nget_ignore_patterns(\"/path/to/project\")\n```\n\n### Benefits\n\n- **Zero friction**: No need to type CLI commands in Claude Desktop\n- **Auto-indexing**: Projects indexed when opened\n- **Rich UI**: Visual code exploration\n- **Session persistence**: Maintains context between chats\n\n## Graph Analysis Features\n\n### Node Importance Scoring\n- **Degree centrality**: Based on number of connections\n- **PageRank**: Overall importance in the dependency graph\n- **Weighted scoring**: Combines multiple centrality measures\n\n### Relevance Tags\n- `structural`: Classes and main components\n- `highly-used`: Entities with many incoming dependencies\n- `complex`: Entities with many outgoing dependencies\n- `test`: Test-related code\n- `module`: File-level entities\n\n### Advanced Analysis\n- **Hub detection**: Find central components in your architecture\n- **Dependency tracking**: Understand code relationships\n- **Impact analysis**: Trace how changes propagate\n- **Similarity detection**: Find related code patterns\n\n## Performance & Caching\n\n### Memory Cache (v1.12.0+)\n\nClaude Code Indexer includes a high-performance memory cache that dramatically improves performance for frequently accessed data:\n\n- **100MB LRU Memory Cache**: Keeps hot data in memory for instant access\n- **10-100x Faster**: Memory cache hits complete in <1ms vs 10-50ms for disk\n- **Automatic Management**: LRU eviction and TTL-based expiration\n- **Entity-Specific Policies**: Different cache strategies per entity type\n\n### Cache Statistics\n\nView detailed cache performance metrics:\n\n```bash\n# Show cache statistics with project stats\ncci stats --cache\n\n# Standalone cache management\ncci cache\n\n# Clear old cache entries\ncci cache --clear --days 7\n```\n\n### Performance Benchmarks\n\n#### Real-World Performance\n- **Indexing Speed**: 22.4 files/sec (fresh index)\n- **Cache Speedup**: 64.6x faster on subsequent runs\n- **LLM Enhancement**: 1,116 nodes/sec\n\n## Development\n\n### Running Tests\n\nTests can be run in parallel for faster execution:\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests in parallel (auto-detect CPU cores)\npytest -n auto\n\n# Run tests in parallel with specific worker count\npytest -n 4\n\n# Run tests sequentially (default)\npytest\n\n# Run tests with coverage in parallel\npytest -n auto --cov=claude_code_indexer --cov-report=term\n```\n\nParallel test execution is powered by `pytest-xdist` and can significantly speed up test runs on multi-core systems.\n\n**Note**: Some tests may fail when run in parallel due to shared resources (e.g., database files, cache directories). If you encounter failures with parallel execution, try running tests sequentially or with fewer workers.\n- **Memory Usage**: <100MB for thousands of files\n\n#### Scalability\n| Project Size | Files | Time | Speed | Cache Speedup |\n|-------------|-------|------|-------|---------------|\n| Small | 50 | 2.3s | 22 files/s | 10-20x |\n| Medium | 500 | 9.0s | 55 files/s | 30-50x |\n| Large | 2000 | 21.6s | 93 files/s | 50-100x |\n\nSee [PERFORMANCE_BENCHMARKS.md](PERFORMANCE_BENCHMARKS.md) for detailed analysis.\n\n### Performance Tips\n\n1. **First Run**: Initial indexing populates both disk and memory cache\n2. **Subsequent Runs**: Unchanged files load from memory cache (instant)\n3. **Memory Usage**: Default 100MB limit with automatic eviction\n4. **TTL Policies**: Files (7 days), Functions (3 days), Imports (1 day)\n\n## Examples\n\n### Basic Usage\n\n```python\nfrom claude_code_indexer import CodeGraphIndexer\n\n# Create indexer\nindexer = CodeGraphIndexer(\"my_project.db\")\n\n# Index a directory\nindexer.index_directory(\"./src\")\n\n# Query important nodes\nimportant_nodes = indexer.query_important_nodes(min_score=0.5)\nfor node in important_nodes:\n print(f\"{node['name']} ({node['node_type']}): {node['importance_score']}\")\n```\n\n### Advanced Analysis\n\n```python\n# Get graph statistics\nstats = indexer.get_stats()\nprint(f\"Total nodes: {stats['total_nodes']}\")\nprint(f\"Node types: {stats['node_types']}\")\n\n# Build NetworkX graph for custom analysis\nnx_graph = indexer.build_graph()\nimport networkx as nx\ncentrality = nx.betweenness_centrality(nx_graph)\n```\n\n## Requirements\n\n- Python 3.8+\n- ensmallen >= 0.8.0\n- networkx >= 3.0\n- pandas >= 1.5.0\n- click >= 8.0.0\n- rich >= 13.0.0\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://docs.anthropic.com/claude-code)\n- \ud83d\udc1b [Issues](https://github.com/claude-ai/code-indexer/issues)\n- \ud83d\udcac [Discussions](https://github.com/claude-ai/code-indexer/discussions)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Multi-language code indexing with graph database, supports Python/JavaScript/TypeScript/Java/AutoIt, auto-ignores node_modules/.git, respects .gitignore, multi-keyword search, MCP for Claude Desktop, automated installation",
"version": "1.21.2",
"project_urls": {
"Changelog": "https://github.com/tuannx/claude-prompts/blob/main/claude_code_indexer/CHANGELOG.md",
"Documentation": "https://github.com/tuannx/claude-prompts/tree/main/claude_code_indexer/README.md",
"Homepage": "https://github.com/tuannx/claude-prompts/tree/main/claude_code_indexer",
"Issues": "https://github.com/tuannx/claude-prompts/issues",
"Repository": "https://github.com/tuannx/claude-prompts.git"
},
"split_keywords": [
"code-indexing",
" graph-database",
" ensmallen",
" claude",
" code-analysis",
" ast",
" development-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf091f326c074462fb4ddbc8aae99396f06ce145ea3d02082b20666e77e79fd1",
"md5": "6de73f595ded2ca9901543d675f80074",
"sha256": "0bc2730503399dfbaf694f4ecf7fb99b328042f12a5c10cb48df4837001f990f"
},
"downloads": -1,
"filename": "claude_code_indexer-1.21.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6de73f595ded2ca9901543d675f80074",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 146402,
"upload_time": "2025-07-25T00:39:38",
"upload_time_iso_8601": "2025-07-25T00:39:38.564089Z",
"url": "https://files.pythonhosted.org/packages/cf/09/1f326c074462fb4ddbc8aae99396f06ce145ea3d02082b20666e77e79fd1/claude_code_indexer-1.21.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ce3039760defb30e032628c0ee34967cd205d32bff7835ba80c5ac306a4e54ac",
"md5": "10e31821ba75033eb0001ddff674436b",
"sha256": "ae03f87bb3044fcec8b014bfba30803c6c1d94e0219a41db7fe45a81d24cb180"
},
"downloads": -1,
"filename": "claude_code_indexer-1.21.2.tar.gz",
"has_sig": false,
"md5_digest": "10e31821ba75033eb0001ddff674436b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 193915,
"upload_time": "2025-07-25T00:39:40",
"upload_time_iso_8601": "2025-07-25T00:39:40.109459Z",
"url": "https://files.pythonhosted.org/packages/ce/30/39760defb30e032628c0ee34967cd205d32bff7835ba80c5ac306a4e54ac/claude_code_indexer-1.21.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 00:39:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tuannx",
"github_project": "claude-prompts",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "claude-code-indexer"
}
JSON
