{"id":46535262,"url":"https://github.com/jsbattig/code-indexer","last_synced_at":"2026-03-06T23:32:31.249Z","repository":{"id":298999275,"uuid":"1001747299","full_name":"jsbattig/code-indexer","owner":"jsbattig","description":"Python application to index code locally and support running server with indexed repos. Works with VoyageAI to power semantic searching a large codebase, enabling AI optimized code navigation. Supports FTS searching, and indexing git log. Experimental support for SCIP indexing.","archived":false,"fork":false,"pushed_at":"2026-01-11T22:49:19.000Z","size":13843,"stargazers_count":2,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-12T02:28:02.634Z","etag":null,"topics":["code-indexing","fulltext-search","rag","scip","semantic-search","voyageai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsbattig.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-14T00:06:46.000Z","updated_at":"2026-01-11T22:49:24.000Z","dependencies_parsed_at":"2025-12-07T00:00:18.803Z","dependency_job_id":null,"html_url":"https://github.com/jsbattig/code-indexer","commit_stats":null,"previous_names":["jsbattig/code-indexer"],"tags_count":110,"template":false,"template_full_name":null,"purl":"pkg:github/jsbattig/code-indexer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsbattig%2Fcode-indexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsbattig%2Fcode-indexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsbattig%2Fcode-indexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsbattig%2Fcode-indexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsbattig","download_url":"https://codeload.github.com/jsbattig/code-indexer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsbattig%2Fcode-indexer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30203352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-indexing","fulltext-search","rag","scip","semantic-search","voyageai"],"created_at":"2026-03-06T23:32:30.573Z","updated_at":"2026-03-06T23:32:31.233Z","avatar_url":"https://github.com/jsbattig.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code Indexer (`cidx`)\n\nAI-powered semantic code search for your codebase. Find code by meaning, not just keywords.\n\n**Version 8.4.46** - [Changelog](CHANGELOG.md) | [Migration Guide](docs/migration-to-v8.md) | [Architecture](docs/architecture.md)\n\n## Quick Navigation\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Key Features](#key-features)\n- [Operating Modes](#operating-modes)\n- [Common Commands](#common-commands)\n- [Documentation](#documentation)\n\n## What is CIDX?\n\nCIDX combines semantic embeddings with traditional search to help you find code by meaning, not just keywords. Search your codebase with natural language queries like \"authentication logic\" or \"database connection setup\", trace symbol references with SCIP code intelligence, and explore git history semantically.\n\n## Installation\n\n### pipx (Recommended)\n\n```bash\npipx install git+https://github.com/jsbattig/code-indexer.git@v8.4.46\n\n# Verify installation\ncidx --version\n```\n\n### pip with virtual environment\n\n```bash\npython3 -m venv code-indexer-env\nsource code-indexer-env/bin/activate\npip install git+https://github.com/jsbattig/code-indexer.git@v8.4.46\n```\n\n**Requirements**: Python 3.9+, 4GB+ RAM, VoyageAI API key\n\nFor detailed installation instructions including Windows, configuration, and troubleshooting, see [Installation Guide](docs/installation.md).\n\n## Quick Start\n\n```bash\n# Navigate to your project\ncd /path/to/your/project\n\n# Set VoyageAI API key (required for semantic search)\nexport VOYAGE_API_KEY=\"your-api-key-here\"\n\n# Index your codebase\ncidx index\n\n# Search semantically\ncidx query \"authentication logic\" --limit 5\n\n# Search with filters\ncidx query \"user\" --language python --min-score 0.7\ncidx query \"save\" --path-filter \"*/models/*\" --limit 10\n```\n\nFor comprehensive query options and search strategies, see [Query Guide](docs/query-guide.md).\n\n## Key Features\n\n### Semantic Search\n\nFind code by meaning using AI embeddings powered by VoyageAI. Ask natural language questions and get semantically relevant results ranked by similarity.\n\n```bash\ncidx query \"authentication logic\" --limit 10\ncidx query \"database connection setup\" --language python\n```\n\nSee: [Query Guide](docs/query-guide.md)\n\n### Full-Text Search (FTS)\n\nFast exact text matching with fuzzy search, regex support, and case sensitivity options. Up to 50x faster than grep with indexed searching.\n\n```bash\ncidx query \"authenticate_user\" --fts\ncidx query \"ParseError\" --fts --case-sensitive\ncidx query \"test_.*\" --fts --regex --language python\n```\n\nSee: [Query Guide](docs/query-guide.md#full-text-search-fts)\n\n### SCIP Code Intelligence\n\nPrecise code navigation using SCIP (Source Code Intelligence Protocol). Find symbol definitions, references, dependencies, dependents, call chains, and perform impact analysis.\n\n```bash\ncidx scip generate                    # Generate SCIP indexes\ncidx scip definition \"UserService\"    # Find definition\ncidx scip references \"authenticate\"   # Find all usages\ncidx scip callchain \"main\" \"login\"    # Trace execution path\ncidx scip impact \"DatabaseManager\"    # Impact analysis\n```\n\nSee: [SCIP Code Intelligence Guide](docs/scip/README.md)\n\n### Git History Search (Temporal)\n\nSearch your entire commit history semantically. Find when code was added, modified, or deleted with time-range filtering, author filtering, and diff type selection.\n\n```bash\ncidx index --index-commits                # Index git history (one-time)\ncidx query \"JWT auth\" --time-range-all    # Search all history\ncidx query \"bug fix\" --time-range 2024-01-01..2024-12-31\ncidx query \"login\" --time-range-all --author \"john@example.com\"\n```\n\nSee: [Temporal Search Guide](docs/temporal-search.md)\n\n### Real-Time Watch Mode\n\nMonitor file changes and automatically re-index in real-time with daemon mode. Get ~5ms cached queries versus ~1s from disk.\n\n```bash\ncidx config --daemon    # Enable daemon mode\ncidx start              # Start daemon\ncidx watch              # Start watch mode\ncidx query \"search\"     # Fast cached queries\n```\n\nSee: [Operating Modes Guide](docs/operating-modes.md#daemon-mode)\n\n### AI Integration\n\nConnect AI assistants to CIDX for semantic search directly in conversations. Supports local CLI integration (Claude Code, Gemini, Codex) and remote MCP server integration (Claude Desktop).\n\n```bash\n# Local CLI integration\ncidx teach-ai --claude --project    # Creates CLAUDE.md\n\n# Remote MCP server for Claude Desktop\n# See MCP Bridge guide for setup\n```\n\nSee: [AI Integration Guide](docs/ai-integration.md) | [MCP Bridge Guide](docs/mcpb/README.md)\n\n## Operating Modes\n\nCIDX operates in three modes optimized for different use cases:\n\n### CLI Mode (Individual Developers \u0026 Remote Access)\n\nDirect command-line interface with two operational sub-modes:\n\n**Local Mode** (default) - Direct file access with instant setup and no dependencies:\n```bash\ncidx init      # Create .code-indexer/ locally\ncidx index     # Index codebase locally\ncidx query     # Search (~1s per query from disk)\n```\n\n**Remote Mode** - Connect to CIDX server with repository linking:\n```bash\n# Initialize remote connection\ncidx init --remote https://cidx.example.com --username user --password pass\n\n# Query executes on remote server\ncidx query \"search term\"  # Transparent remote execution\n\n# Sync repositories with server\ncidx sync                 # Sync current repository\ncidx sync my-project     # Sync specific repository\ncidx sync --all          # Sync all repositories (multi-repo support)\n```\n\n**Remote Mode Features**:\n- Repository linking (automatic matching between local repo and server golden repo)\n- Transparent remote query execution (same CLI, server-side processing)\n- Multi-repo support (manage and sync multiple repositories)\n- OAuth 2.0 authentication with server\n- Access team's centralized indexed repositories\n\n### Daemon Mode (Performance)\n\nBackground service with in-memory caching for faster queries (~5ms) and real-time watch mode.\n\n```bash\ncidx config --daemon    # Enable daemon\ncidx start              # Start daemon\ncidx query \"search\"     # Fast cached queries\ncidx watch              # Real-time indexing\n```\n\n### Server Mode (Team Collaboration)\n\nMulti-user server with centralized golden repositories for team-wide semantic search. Deploy CIDX as an HTTP/HTTPS service with OAuth 2.0 authentication, REST API, MCP interface, and web UI administration.\n\n```bash\ncidx-server start       # Start multi-user server\n# Users query via REST API or MCP\n# Admin manages repos via web UI\n```\n\n**Core Capabilities**:\n- **Multi-Repo Indexing**: Centralized golden repositories shared across team\n- **Multi-User Access**: OAuth 2.0/OIDC authentication with role-based permissions\n- **Advanced Caching**: HNSW cache with \u003c1ms warm queries (100-1800x speedup)\n- **REST API**: Programmatic access with full query parameter support\n- **MCP Protocol**: Claude Desktop integration for AI-assisted code search\n- **Web Administration**: Manage users, repositories, and configuration via browser\n- **Repository Management**: Add, refresh, remove golden repositories\n- **User Management**: Create users, assign roles (admin/power_user/normal_user)\n- **Cache Monitoring**: Real-time cache statistics and performance metrics\n\n**Authentication \u0026 Authorization**:\n- OAuth 2.0 and OIDC (OpenID Connect) support\n- Three role levels: admin (full access), power_user (activate repos), normal_user (query only)\n- Secure token-based API access\n\n**Performance**:\n- Cold query: ~277ms (first access, loads from disk)\n- Warm query: \u003c1ms (cached, 100-1800x faster)\n- Configurable cache TTL (default 10 minutes)\n- Per-repository cache isolation\n\nFor detailed setup, deployment, and configuration, see [Operating Modes Guide](docs/operating-modes.md).\n\n## Common Commands\n\n### Indexing\n\n```bash\ncidx init                    # Create .code-indexer/ config\ncidx index                   # Semantic indexing (default)\ncidx index --fts             # Add full-text search\ncidx index --index-commits   # Add git history indexing\ncidx scip generate           # Generate SCIP indexes\n```\n\n### Querying\n\n```bash\n# Semantic search\ncidx query \"search term\" --limit 10\n\n# Full-text search\ncidx query \"exact text\" --fts\n\n# Regex pattern matching\ncidx query \"pattern\" --fts --regex\n\n# Git history search\ncidx query \"term\" --time-range-all --quiet\n\n# SCIP code intelligence\ncidx scip definition \"Symbol\"\ncidx scip references \"function_name\"\n```\n\n### Filtering\n\n```bash\n--language python           # Filter by language\n--path-filter \"*/tests/*\"   # Filter by path pattern\n--exclude-path \"*/vendor/*\" # Exclude paths\n--min-score 0.8             # Minimum similarity score\n--limit 20                  # Max results\n```\n\n### Daemon Mode\n\n```bash\ncidx config --daemon        # Enable daemon\ncidx start                  # Start daemon\ncidx stop                   # Stop daemon\ncidx status                 # Check status\ncidx watch                  # Start watch mode\ncidx watch-stop             # Stop watch mode\n```\n\n## Configuration\n\nCIDX requires minimal configuration. The VoyageAI API key is the only required setting.\n\n### VoyageAI API Key (Required)\n\n```bash\n# Add to shell profile (~/.bashrc or ~/.zshrc)\nexport VOYAGE_API_KEY=\"your-api-key-here\"\nsource ~/.bashrc\n```\n\n### Project Configuration\n\nCIDX auto-creates `.code-indexer/config.json` on first run with sensible defaults. You can customize:\n\n- `file_extensions` - File types to index\n- `exclude_dirs` - Directories to skip\n- `max_file_size` - Maximum file size (default 1MB)\n\nFor complete configuration reference including environment variables, daemon settings, and watch mode options, see [Configuration Guide](docs/configuration.md).\n\n## Documentation\n\n### Getting Started\n- [Installation Guide](docs/installation.md) - Complete installation for all platforms\n- [Query Guide](docs/query-guide.md) - All 23 query parameters and search strategies\n- [Configuration Guide](docs/configuration.md) - VoyageAI setup, config options, environment variables\n\n### Features\n- [SCIP Code Intelligence](docs/scip/README.md) - Symbol navigation, dependencies, call chains\n- [Temporal Search](docs/temporal-search.md) - Git history search with time-range filtering\n- [Operating Modes](docs/operating-modes.md) - CLI, Daemon, Server modes explained\n\n### AI Integration\n- [AI Integration Guide](docs/ai-integration.md) - Connect AI assistants to CIDX\n- [MCP Bridge Guide](docs/mcpb/README.md) - Claude Desktop integration via MCP\n\n### Server Administration\n- [Auto-Update Guide](docs/auto-update.md) - Job-aware auto-update with graceful drain mode\n\n### Advanced\n- [Architecture Guide](docs/architecture.md) - System design and storage architecture\n- [Migration Guide](docs/migration-to-v8.md) - Upgrading from v7.x to v8.x\n- [Changelog](CHANGELOG.md) - Version history and release notes\n\n## Contributing\n\nContributions welcome! We appreciate bug reports, feature suggestions, and code contributions.\n\n### For Developers\n\n**Quick Setup:**\n```bash\n# 1. Clone and install\ngit clone https://github.com/YOUR_USERNAME/code-indexer.git\ncd code-indexer\npip install -e \".[dev]\"\n\n# 2. Install pre-commit hooks (REQUIRED)\npre-commit install\n\n# 3. Run tests\n./fast-automation.sh\n```\n\n**Pre-commit Hooks**: All commits are automatically checked for linting, formatting, and type errors. Hooks auto-fix most issues.\n\n**See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development setup, testing guidelines, and code quality standards.**\n\n### Reporting Issues\n\n- **Bugs**: [GitHub Issues](https://github.com/jsbattig/code-indexer/issues)\n- **Features**: [GitHub Issues](https://github.com/jsbattig/code-indexer/issues)\n- **Questions**: [GitHub Discussions](https://github.com/jsbattig/code-indexer/discussions)\n\n## License\n\nMIT License - See repository for full license text.\n\n---\n\n**Support**: [GitHub Issues](https://github.com/jsbattig/code-indexer/issues)\n**Repository**: [https://github.com/jsbattig/code-indexer](https://github.com/jsbattig/code-indexer)\n\n\u003c!-- E2E Test: Auto-deployment validation for story #657 - 2025-12-31 16:15 CST --\u003e\n\u003c!-- E2E Test: Final auto-deployment test after fixes deployed - 2025-12-31 16:23 CST --\u003e\n\u003c!-- E2E Test: Complete workflow with server restart - 2025-12-31 16:26 CST --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsbattig%2Fcode-indexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsbattig%2Fcode-indexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsbattig%2Fcode-indexer/lists"}