turboprop 0.2.0

Lightning-fast semantic code search and indexing with DuckDB vector operations

Turboprop 🚀

Lightning-fast semantic code search with AI embeddings. Transform your codebase into a searchable knowledge base using natural language queries.

✨ Key Features

• 🔍 Semantic Search: Find code by meaning, not just keywords ("JWT authentication" finds auth logic)
• 🐆 Lightning Fast: DuckDB vector operations for sub-second search across large codebases
• 🔄 Live Updates: Watch mode with intelligent debouncing - your index stays fresh as you code
• 🤖 MCP Ready: Perfect integration with Claude and other AI coding assistants
• 📁 Git-Aware: Respects .gitignore and only indexes what matters
• 💻 Simple CLI: Clean command-line interface with helpful guidance

🚀 Quick Start

MCP Configuration (Claude Integration) - Front and Center!

Add this to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "turboprop": {
      "command": "uvx",
      "args": [
        "turboprop",
        "mcp",
        "--repository",
        "/path/to/your/codebase",
        "--auto-index"
      ]
    }
  }
}

Then restart Claude Desktop and start asking questions about your code:

• "Find JWT authentication code"
• "Show me error handling patterns"
• "Where is the database connection setup?"

Installation & Basic Usage

# Install globally
pip install turboprop

# Index your codebase
turboprop index .

# Search with natural language
turboprop search "JWT authentication"

# Watch for changes (keeps index updated)
turboprop watch .

⚙️ CLI Usage

index - Build Search Index

turboprop index <repository_path> [options]

Options:
  --max-mb FLOAT       Maximum file size in MB to index (default: 1.0)
  --workers INTEGER    Number of parallel workers (default: CPU count)
  --force-all         Force reprocessing of all files

Examples:
  turboprop index .                    # Index current directory
  turboprop index ~/my-project         # Index specific project
  turboprop index . --max-mb 2.0      # Allow larger files

search - Semantic Code Search

turboprop search "<query>" [options]

Options:
  --repo PATH         Repository path (default: current directory)
  --k INTEGER         Number of results to return (default: 5)

Query Examples:
  turboprop search "JWT authentication"              # Find auth-related code
  turboprop search "parse JSON response"             # Discover JSON parsing logic
  turboprop search "error handling middleware"       # Locate error handling patterns
  turboprop search "database connection setup"       # Find DB initialization code
  turboprop search "React component for forms"       # Find form-related components

watch - Live Index Updates

turboprop watch <repository_path> [options]

Options:
  --max-mb FLOAT        Maximum file size in MB (default: 1.0)
  --debounce-sec FLOAT  Seconds to wait before processing changes (default: 5.0)

Example:
  turboprop watch . --debounce-sec 3.0  # Faster updates

mcp - Start MCP Server

turboprop mcp [options]

Options:
  --repository PATH     Repository to index and monitor (default: current directory)
  --max-mb FLOAT       Maximum file size in MB (default: 1.0)
  --debounce-sec FLOAT Seconds to wait before processing changes (default: 5.0)
  --auto-index         Automatically index on startup (default: True)
  --no-auto-index      Don't automatically index on startup
  --auto-watch         Automatically watch for changes (default: True)
  --no-auto-watch      Don't automatically watch for changes

Examples:
  turboprop mcp --repository .                     # Start MCP server for current directory
  turboprop mcp --repository /path/to/repo         # Index specific repository
  turboprop mcp --repository . --max-mb 2.0        # Allow larger files
  turboprop mcp --repository . --no-auto-index     # Don't auto-index on startup

Features Available in Claude

When using the MCP server with Claude:

• 🔍 Semantic Code Search: Ask Claude to find code using natural language
• 📁 Repository Indexing: Automatically index and watch your codebase
• 🔄 Real-time Updates: Index stays fresh as you code
• 💬 Natural Queries: "Find JWT authentication code", "Show error handling patterns"

💡 Pro Tips & Search Examples

Query Examples

• "JWT authentication" → Find auth-related code
• "parse JSON response" → Discover JSON parsing logic
• "error handling middleware" → Locate error handling patterns
• "database connection setup" → Find DB initialization code
• "React component for forms" → Find form-related components

Performance Tips

• File size limit: Adjust --max-mb based on your repository size and available memory
• Debounce timing: Lower --debounce-sec for faster updates, higher for less CPU usage
• Search results: Increase --k to see more results, decrease for faster queries

📄 License

MIT License - feel free to use this in your projects!

---

Ready to supercharge your code exploration? Get started in 60 seconds! 🚀✨

🧠 Optimized for Claude Code

Add .claude/code-index.commands.md for slash commands.

---

That’s it—fucking easy as pie. 🍰🚀

💻 Enhanced CLI Experience

Turboprop now features a beautiful, user-friendly CLI with:

Rich Help System

uv run python code_index.py --help     # Main help with examples
uv run python code_index.py index --help    # Detailed command help
uv run python code_index.py search --help   # Search-specific guidance

Visual Feedback

• 🚀 Branded startup messages
• ⚡ Progress indicators with emojis
• 📊 Rich search result formatting
• 💡 Helpful tips and suggestions
• ❌ Clear error messages with solutions

Smart Error Handling

• Missing index detection with guidance
• File size limit recommendations
• Search result explanations
• Recovery suggestions

🔗 MCP Integration (Claude & AI Assistants)

Quick Setup for Claude

1. Start the MCP server:

   uv run uvicorn server:app --host localhost --port 8000
   

2. Index your repository:

   uv run python code_index.py index /path/to/your/repo
   

3. Use in Claude with slash commands:

   • /search JWT authentication - Find auth-related code
   • /search React form validation - Find form components
   • /status - Check index health

Available MCP Tools

• index_repository - Build searchable index from code repository
• search_code - Search code using natural language queries
• get_index_status - Check current state of the code index
• watch_repository - Monitor repository for changes
• list_indexed_files - Show files currently in the index

MCP Configuration

The repository includes ready-to-use MCP configuration:

• .mcp/config.json - Server configuration
• .claude/turboprop-commands.md - Claude slash commands

⚙️ Complete CLI Reference

index - Build Search Index

uv run python code_index.py index <repository_path> [options]

Options:
  --max-mb FLOAT    Maximum file size in MB to index (default: 1.0)

Examples:
  uv run python code_index.py index .                    # Index current directory
  uv run python code_index.py index ~/my-project         # Index specific project
  uv run python code_index.py index . --max-mb 2.0      # Allow larger files

search - Semantic Code Search

uv run python code_index.py search "<query>" [options]

Options:
  --k INTEGER      Number of results to return (default: 5)

Query Examples:
  "JWT authentication"              → Find auth-related code
  "parse JSON response"             → Discover JSON parsing logic
  "error handling middleware"       → Locate error handling patterns
  "database connection setup"       → Find DB initialization code
  "React component for forms"       → Find form-related components

watch - Live Index Updates

uv run python code_index.py watch <repository_path> [options]

Options:
  --max-mb FLOAT        Maximum file size in MB (default: 1.0)
  --debounce-sec FLOAT  Seconds to wait before processing changes (default: 5.0)

Example:
  uv run python code_index.py watch . --debounce-sec 3.0  # Faster updates

🌐 HTTP API Server

Start the Server

# Development mode with auto-reload (using uv)
uv run uvicorn server:app --reload --host 0.0.0.0 --port 8000

# Production mode
uv run uvicorn server:app --host 0.0.0.0 --port 8000

# OR with activated virtual environment
uvicorn server:app --reload --host 0.0.0.0 --port 8000

API Endpoints

POST /index - Build Index

curl -X POST "http://localhost:8000/index" \
  -H "Content-Type: application/json" \
  -d '{"repo": "/path/to/repository", "max_mb": 1.0}'

# Response: {"status": "indexed", "files": 1247}

GET /search - Search Code

curl "http://localhost:8000/search?query=JWT%20authentication&k=5"

# Response:
[
  {
    "path": "/src/auth/middleware.py",
    "snippet": "def verify_jwt_token(token: str):\n    \"\"\"Verify JWT token and extract claims...",
    "distance": 0.234
  }
]

GET /status - Index Status

curl "http://localhost:8000/status"

# Response:
{
  "files_indexed": 1247,
  "database_size_mb": 125.6,
  "search_index_ready": true,
  "last_updated": "Recent",
  "embedding_dimensions": 384,
  "model_name": "all-MiniLM-L6-v2"
}

Interactive API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

💡 Pro Tips & Best Practices

Search Query Optimization

• Use descriptive phrases: "authentication middleware" vs just "auth"
• Ask conceptual questions: "how to handle errors" vs "try catch"
• Combine multiple concepts: "JWT token validation middleware"
• Be domain-specific: "React form validation" vs "form validation"

Performance Tuning

• File size limit: Adjust --max-mb based on your repository size and available memory
• Debounce timing: Lower --debounce-sec for faster updates, higher for less CPU usage
• Search results: Increase --k to see more results, decrease for faster queries

File Management

• Index files: code_index.duckdb (database) and hnsw_code.idx (search index)
• Location: Created in the current working directory
• Cleanup: Delete these files to reset the index completely
• Backup: Copy these files to backup your index

🏗️ Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Git Repository │───▶│  File Scanner    │───▶│  Code Files     │
│   (.gitignore    │    │  (scan_repo)     │    │  (.py, .js, etc)│
│    aware)        │    └──────────────────┘    └─────────────────┘
└─────────────────┘                                       │
                                                          ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Search Results │◀───│  HNSW Index     │◀───│  Embeddings     │
│   (ranked by    │    │  (fast vector   │    │  (ML model:     │
│    similarity)  │    │   search)        │    │   all-MiniLM)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                 ▲                        │
                                 │                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Query    │───▶│  Query Embedding │    │  DuckDB Storage │
│   ("parse JSON") │    │  (same model)   │    │  (persistent)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                 ▲
                                 │
                   ┌──────────────────┐
                   │   FastAPI Server │ ←── MCP Integration
                   │   (HTTP API)     │     Claude, etc.
                   └──────────────────┘

🤝 Contributing

We welcome contributions! Key areas for improvement:

• Additional programming language support
• Performance optimizations for large repositories
• IDE/editor integrations
• Advanced search features (regex, file filters, etc.)
• Better error handling and user feedback
• Enhanced MCP tool capabilities

📄 License

MIT License - feel free to use this in your projects!

---

Ready to supercharge your code exploration? Get started in 60 seconds! 🚀✨

Turboprop: Because finding code should be as smooth as flying.