claude-code-indexer 1.29.1
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
License: MIT
Requires Python: >=3.8
Keywords: code-indexing, graph-database, ensmallen, claude, code-analysis, ast, development-tools

# Claude Code Indexer

[![PyPI version](https://badge.fury.io/py/claude-code-indexer.svg)](https://badge.fury.io/py/claude-code-indexer)
[![Python](https://img.shields.io/pypi/pyversions/claude-code-indexer.svg)](https://pypi.org/project/claude-code-indexer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Install with VS Code

[![Install with PIP in VS Code](https://img.shields.io/badge/VS_Code-PIP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=claude-code-indexer&config=%7B%22command%22%3A%22python%22%2C%22args%22%3A%5B%22-m%22%2C%22claude_code_indexer.mcp_server%22%5D%7D)
[![Install with PIP in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-PIP-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=claude-code-indexer&config=%7B%22command%22%3A%22python%22%2C%22args%22%3A%5B%22-m%22%2C%22claude_code_indexer.mcp_server%22%5D%7D&quality=insiders)

## 📖 Description

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.

## 🎯 Features

- **Multi-language Support**: Python, JavaScript, TypeScript, Java, AutoIt
- **Graph Database**: Advanced code relationship mapping using Ensmallen
- **Smart Ignoring**: Automatically respects .gitignore and skips node_modules/.git
- **Fast Search**: Multi-keyword search with FTS5 full-text search
- **MCP Integration**: Seamless integration with Claude Desktop/VS Code
- **Performance**: ~50 files/sec with caching enabled
- **AI Enhancement**: Optional AI-powered metadata generation

## 📦 Installation

### Via pip (Recommended)

```bash
pip install claude-code-indexer
```

### Via VS Code MCP

Click one of the badges above to automatically configure Claude Code Indexer as an MCP server in VS Code.

### Manual MCP Setup

```bash
# Install the package
pip install claude-code-indexer

# Setup MCP integration
cci mcp install
```

## 🚀 Quick Start

```bash
# Initialize project
cci init

# Index codebase
cci index .

# Search code
cci search "authentication"

# Find important components
cci query --important

# Get insights
cci insights
```

## 🤖 LLM Guidance (MCP-first)

If MCP is not set up, do this once:

```bash
cci mcp install
cci mcp-daemon start
```

When answering code questions, LLMs should always prefer MCP tools over manual file scanning:

1. `index_codebase` (if not indexed)
2. `search_code` for keywords
3. `query_important_code` for key components
4. `get_project_stats` + `get_codebase_insights` for overview
5. `enhance_metadata` only when needed

## 📊 Commands

### Core Commands

- `cci init` - Initialize project with CLAUDE.md and database
- `cci index [path]` - Index source code into graph database
- `cci stats` - Show project statistics

### Query Commands

- `cci query [--important] [--type TYPE] [--limit N]` - Query indexed entities
- `cci search <keywords>` - Full-text search across codebase
- `cci critical [--limit N]` - Find most critical components

### Analysis Commands

- `cci insights` - Architectural analysis and health check
- `cci enhanced [filters]` - Query AI-enhanced metadata
- `cci enhance . [--limit N]` - Add AI-powered metadata (requires API)

### State Management

- `cci state capture` - Save codebase snapshot
- `cci state diff` - Show changes since last capture
- `cci state tasks` - List development task history

### MCP Integration

- `cci mcp install` - Setup MCP server for Claude
- `cci mcp-daemon [start|stop|status]` - Background service management

## 🔧 MCP Server Configuration

When installed via VS Code badges or manual MCP setup, the server provides these tools:

### Available MCP Tools

- `index_codebase` - Index project code
- `search_code` - Search codebase with keywords
- `query_important_code` - Find critical components
- `get_project_stats` - Get project statistics
- `get_codebase_insights` - Health and architecture analysis
- `enhance_metadata` - Add AI-powered metadata
- `store_llm_memory` - Store analysis insights
- `store_coding_pattern` - Save reusable patterns
- `store_best_practice` - Document best practices

## 📈 Performance

| Operation | First Run | With Cache | Notes             |
| --------- | --------- | ---------- | ----------------- |
| init      | 1-2s      | N/A        | One-time          |
| index     | 5-10s     | 0.5-1s     | 95%+ cache hit    |
| query     | 0.1-0.5s  | 0.05s      | Database query    |
| search    | 0.2-1s    | 0.1s       | Full-text search  |

## 🆚 Competitor Comparison (high level)

| Approach | Strengths | Tradeoffs |
| -------- | --------- | --------- |
| CCI (graph + MCP) | Local-first, structured graph, MCP tools for LLMs | Needs initial indexing and MCP setup |
| Sourcegraph/OpenGrok | Large-scale code search UI | Heavier setup, less LLM-native workflows |
| LSP/ctags | Fast editor navigation | Limited cross-file graph insights |
| Vector search only | Strong semantic matching | Weaker structural/relationship precision |

## 📊 Benchmarks (required for real comparisons)

We do not claim superiority without measurable data. Use the scripts below to capture real numbers on your machine and publish them.

```bash
# Cold run (no cache)
cci index . --force

# Warm run (cache)
cci index .

# Database benchmark
cci benchmark --records 1000
```

Document your results in docs/benchmarks.md.

## ⚠️ Security

- **Never index sensitive data** (API keys, tokens, credentials)
- Check for .env files: `find . -name "*.env"`
- Add sensitive files to .gitignore

## 🤝 Contributing

Issues and pull requests are welcome at [GitHub](https://github.com/tuannx/claude-prompts).

- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Security policy: [SECURITY.md](SECURITY.md)
- Support: [SUPPORT.md](SUPPORT.md)
- Index metrics: [docs/index-metrics.md](docs/index-metrics.md)

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- [Homepage](https://github.com/tuannx/claude-prompts/tree/main/claude_code_indexer)
- [Documentation](https://github.com/tuannx/claude-prompts/tree/main/claude_code_indexer/README.md)
- [Issues](https://github.com/tuannx/claude-prompts/issues)
- [PyPI](https://pypi.org/project/claude-code-indexer/)