codeindex

AI-native code indexing tool for large codebases.

codeindex automatically generates intelligent documentation (README_AI.md) for your directories using tree-sitter parsing and external AI CLIs. Perfect for understanding large codebases, onboarding new developers, and maintaining living documentation.

---

✨ Features

• 🚀 AI-Powered Documentation: Generate comprehensive README files using Claude, GPT, or any AI CLI
• 🌳 Tree-sitter Parsing: Accurate symbol extraction (classes, functions, methods, imports) for Python (more languages coming)
• ⚡ Parallel Scanning: Scan multiple directories concurrently for fast indexing
• 🎯 Smart Filtering: Include/exclude patterns with glob support
• 🔧 Flexible Integration: Works with any AI CLI tool via configurable commands
• 📊 Coverage Tracking: Check which directories have been indexed
• 🎨 Fallback Mode: Generate basic documentation without AI

---

📦 Installation

Using pipx (Recommended)

pipx install codeindex

Using pip

pip install codeindex

From Source

git clone https://github.com/yourusername/codeindex.git
cd codeindex
pip install -e .

---

🚀 Quick Start

1. Initialize Configuration

cd /your/project
codeindex init

This creates .codeindex.yaml in your project.

2. Configure AI CLI

Edit .codeindex.yaml:

ai_command: 'claude -p "{prompt}" --allowedTools "Read"'

include:
  - src/
exclude:
  - "**/test/**"
  - "**/__pycache__/**"

languages:
  - python

output_file: "README_AI.md"

Other AI CLI examples:

# OpenAI
ai_command: 'openai chat "{prompt}" --model gpt-4'

# Gemini
ai_command: 'gemini "{prompt}"'

# Custom script
ai_command: '/path/to/my-ai-wrapper.sh "{prompt}"'

3. Scan a Directory

# Scan single directory
codeindex scan ./src/auth

# Preview prompt without executing
codeindex scan ./src/auth --dry-run

# Generate without AI (fallback mode)
codeindex scan ./src/auth --fallback

4. Batch Processing

# List all indexable directories
codeindex list-dirs

# Scan all directories in parallel (4 workers)
codeindex list-dirs | xargs -P 4 -I {} codeindex scan {}

# Or with GNU parallel
codeindex list-dirs | parallel -j 4 codeindex scan {}

5. Check Status

codeindex status

Output:

Indexing Status
───────────────────────────────────────
✅ src/auth/
✅ src/utils/
⚠️  src/api/ (no README_AI.md)
✅ src/db/

Indexed: 3/4 (75%)

---

📖 Documentation

• Getting Started - Detailed installation and setup
• Configuration Guide - All config options explained
• Advanced Usage - Parallel scanning, custom prompts
• Contributing - Development setup and guidelines
• Roadmap - Future plans and milestones
• Architecture - Design decisions and ADRs
• Changelog - Version history

---

🤖 Claude Code Integration

codeindex includes skills for Claude Code to enhance your AI-assisted development workflow.

Install Skills

# Navigate to codeindex directory
cd /path/to/codeindex

# Run install script
./skills/install.sh

Available Skills

Command	Description
/mo:arch	Query code architecture using README_AI.md indexes
/mo:index	Generate repository index with codeindex

Usage Example

After indexing your project:

You: /mo:arch Where is the parser implemented?

Claude: Based on README_AI.md, the parser is in src/codeindex/parser.py.
        It uses tree-sitter for AST parsing and extracts Symbol and Import...

CLAUDE.md Integration

Add to your project's CLAUDE.md:

Each source directory has README_AI.md - read it before modifying code to understand module structure.

See skills/README.md for detailed documentation.

---

🎯 Use Cases

📚 Code Understanding

Generate comprehensive documentation for legacy codebases to help new developers onboard faster.

🔍 Codebase Navigation

Create structured overviews of large projects (10,000+ files) for efficient exploration.

🤖 AI Agent Integration

Use generated indexes with tools like Claude Code or Cursor for better code context.

📝 Living Documentation

Keep documentation up-to-date by regenerating README_AI.md files as code changes.

---

🛠️ How It Works

Directory → Scanner → Parser (tree-sitter) → Prompt Generator → AI CLI → README_AI.md

1. Scanner: Walks directories, filters by config patterns
2. Parser: Extracts symbols (classes, functions, imports) using tree-sitter
3. Writer: Formats parsed data into a prompt
4. Invoker: Executes external AI CLI with the prompt
5. Output: AI generates README_AI.md with intelligent documentation

---

🌍 Language Support

Language	Status	Parser
Python	✅ Supported	tree-sitter
TypeScript/JS	🚧 Coming Soon	tree-sitter
Java	🚧 Planned	tree-sitter
Go	🚧 Planned	tree-sitter
Rust	🚧 Planned	tree-sitter

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• TDD workflow
• Code style guidelines
• How to add new languages
• Release process

Quick Start for Contributors

# Clone and install
git clone https://github.com/yourusername/codeindex.git
cd codeindex
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check src/
ruff format src/

---

📊 Roadmap

See 2025 Q1 Roadmap for detailed plans.

Upcoming:

• Multi-language support (TypeScript, Java, Go)
• MCP service integration for Claude Code
• Incremental indexing (only scan changed files)
• Performance optimizations
• Plugin system for custom AI providers

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• tree-sitter - Fast, incremental parsing
• Claude CLI - AI integration inspiration
• All contributors and users

---

📞 Support

• Questions: GitHub Discussions
• Bugs: GitHub Issues
• Feature Requests: GitHub Issues

---

⭐ Star History

If you find codeindex useful, please star the repository to show your support!

---

Made with ❤️ by the codeindex team