{"id":47730177,"url":"https://github.com/bahdotsh/indxr","last_synced_at":"2026-04-02T21:24:38.435Z","repository":{"id":346757306,"uuid":"1189368902","full_name":"bahdotsh/indxr","owner":"bahdotsh","description":"A fast codebase indexer and MCP server for AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-03-25T18:34:19.000Z","size":378,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T12:54:18.333Z","etag":null,"topics":["ai","ai-agents","claude-code","mcp-server","openai","tokens"],"latest_commit_sha":null,"homepage":"https://github.com/bahdotsh/indxr","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bahdotsh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T08:51:53.000Z","updated_at":"2026-03-26T09:22:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bahdotsh/indxr","commit_stats":null,"previous_names":["bahdotsh/indxr"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bahdotsh/indxr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdotsh%2Findxr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdotsh%2Findxr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdotsh%2Findxr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdotsh%2Findxr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bahdotsh","download_url":"https://codeload.github.com/bahdotsh/indxr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdotsh%2Findxr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["ai","ai-agents","claude-code","mcp-server","openai","tokens"],"created_at":"2026-04-02T21:24:37.129Z","updated_at":"2026-04-02T21:24:38.428Z","avatar_url":"https://github.com/bahdotsh.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# indxr\n\n**A fast codebase indexer and MCP server for AI coding agents.**\n\n[![CI](https://github.com/bahdotsh/indxr/actions/workflows/ci.yml/badge.svg)](https://github.com/bahdotsh/indxr/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/indxr.svg)](https://crates.io/crates/indxr)\n[![License](https://img.shields.io/crates/l/indxr.svg)](LICENSE)\n\n\u003c/div\u003e\n\nAI coding agents waste thousands of tokens reading entire source files just to understand what's in them. indxr gives agents a structural map of your codebase — declarations, imports, relationships, and dependency graphs — so they can query for exactly what they need at a fraction of the token cost.\n\n---\n\n## Features\n\n- **27 languages** — tree-sitter AST parsing for 8 languages, regex extraction for 19 more\n- **26-tool MCP server** (3 compound default + 23 granular via `--all-tools`) — live codebase queries over JSON-RPC: symbol lookup, file summaries, caller tracing, signature search, complexity hotspots, type flow tracking, workspace support, and more\n- **Token-aware** — progressive truncation to fit context windows, ~5x reduction vs reading full files\n- **Git structural diffing** — declaration-level diffs (`+` added, `-` removed, `~` changed) against any git ref or GitHub PR\n- **Dependency graphs** — file and symbol dependency visualization as DOT, Mermaid, or JSON\n- **File watching** — continuous re-indexing as you edit, via `indxr watch` or `indxr serve --watch`\n- **Monorepo / workspace support** — auto-detects Cargo, npm, and Go workspaces; scope any tool or command to a specific member via `--member`\n- **One-command agent setup** — `indxr init` configures Claude Code, Cursor, Windsurf, and Codex CLI with MCP, instruction files, and hooks\n- **Incremental caching** — mtime + xxh3 content hashing, sub-20ms indexing for most projects\n- **Complexity hotspots** — per-function cyclomatic complexity, nesting depth, and parameter count via tree-sitter AST analysis; codebase health reports\n- **Type flow tracking** — cross-file analysis showing which functions produce (return) and consume (accept) a given type\n- **Composable filters** — by path, kind, symbol name, visibility, and language\n- **Three output formats** — Markdown (default), JSON, YAML at three detail levels\n\n## Install\n\n```bash\ncargo install indxr\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/bahdotsh/indxr.git\ncd indxr \u0026\u0026 cargo build --release\n```\n\n## Usage\n\n```bash\nindxr                                        # index cwd → stdout\nindxr ./my-project -o INDEX.md               # index project → file\nindxr -f json -l rust,python -o index.json   # JSON, filter by language\nindxr serve ./my-project                     # start MCP server\nindxr serve ./my-project --watch             # MCP server with auto-reindex\nindxr watch ./my-project                     # watch \u0026 keep INDEX.md updated\nindxr members                                # list workspace members (monorepo)\nindxr init                                   # set up all agent configs\n```\n\n## Agent Setup\n\n```bash\nindxr init                    # set up for all agents\nindxr init --claude           # Claude Code only\nindxr init --cursor           # Cursor only\nindxr init --windsurf         # Windsurf only\nindxr init --codex            # OpenAI Codex CLI only\nindxr init --global           # install globally for all projects\nindxr init --global --cursor  # global Cursor only\nindxr init --no-rtk           # skip RTK hook setup\n```\n\n| Agent | Project Files | Global Files (`--global`) |\n|---|---|---|\n| Claude Code | `.mcp.json`, `CLAUDE.md`, `.claude/settings.json` | `~/.claude.json`, `~/.claude/CLAUDE.md` |\n| Cursor | `.cursor/mcp.json`, `.cursor/rules/indxr.mdc` | `~/.cursor/mcp.json` |\n| Windsurf | `.windsurf/mcp.json`, `.windsurf/rules/indxr.md` | `~/.codeium/windsurf/mcp_config.json`, `~/.codeium/windsurf/memories/global_rules.md` |\n| Codex CLI | `.codex/config.toml`, `AGENTS.md` | `~/.codex/config.toml`, `~/.codex/AGENTS.md` |\n| All | `.gitignore` entry, `INDEX.md` | — |\n\nAgents don't always pick MCP tools over file reads on their own. `indxr init` sets up reinforcement — PreToolUse hooks intercept `Read`/`Bash` calls and instruction files teach the exploration workflow.\n\n## MCP Server\n\nJSON-RPC 2.0 over stdin/stdout (or Streamable HTTP with `--features http`). By default 3 compound tools are listed to minimize per-request token overhead; pass `--all-tools` to expose all 26 (3 compound + 23 granular).\n\n### Default tools (3 compound)\n\n| Tool | Description |\n|---|---|\n| `find` | Find files/symbols by concept, name, callers, or signature pattern. Modes: `relevant` (default), `symbol`, `callers`, `signature` |\n| `summarize` | Understand files/symbols without reading source. Auto-detects: glob -\u003e batch, no \"/\" -\u003e symbol name, file path -\u003e file summary. Scope: `all` (default), `public` |\n| `read` | Read source by symbol name or line range (same as `read_source`) |\n\n### Granular tools (23 — requires `--all-tools`)\n\n| Tool | Description |\n|---|---|\n| `search_relevant` | Multi-signal relevance search across paths, names, signatures, and docs |\n| `lookup_symbol` | Find declarations by name (case-insensitive substring) |\n| `explain_symbol` | Signature, doc comment, relationships, metadata — no body |\n| `get_file_summary` | Complete file overview without reading it |\n| `batch_file_summaries` | Summarize multiple files in one call |\n| `get_file_context` | File summary + reverse dependencies + related files |\n| `get_public_api` | Public declarations with signatures for a file or directory |\n| `get_callers` | Find who references a symbol across all files |\n| `list_declarations` | List declarations in a file with optional filters |\n| `search_signatures` | Search functions by signature pattern |\n| `read_source` | Read source by symbol name or line range |\n| `get_tree` | Directory/file tree |\n| `get_stats` | File count, line count, language breakdown |\n| `get_imports` | Import statements for a file |\n| `get_related_tests` | Find test functions by naming convention |\n| `get_hotspots` | Most complex functions ranked by composite score |\n| `get_health` | Codebase health summary with aggregate complexity metrics |\n| `get_type_flow` | Track which functions produce/consume a given type across the codebase |\n| `get_dependency_graph` | File and symbol dependency graph (DOT, Mermaid, JSON) |\n| `get_diff_summary` | Structural changes since a git ref or GitHub PR |\n| `get_token_estimate` | Estimate tokens before reading |\n| `list_workspace_members` | List monorepo workspace members (Cargo, npm, Go) |\n| `regenerate_index` | Re-index and update INDEX.md |\n\n\u003e Granular tools are always callable even when not listed — `--all-tools` only controls whether they appear in `tools/list`.\n\nIn workspace mode (multiple members), tools automatically gain a `member` param to scope queries. List tools support `compact` mode for ~30% token savings. See [MCP Server docs](docs/mcp-server.md) for full parameter details.\n\n## Output\n\nDefault format is Markdown at `signatures` detail level:\n\n```markdown\n# Codebase Index: my-project\n\n\u003e Generated: 2025-03-23 | Files: 42 | Lines: 8,234\n\u003e Languages: Rust (28), Python (10), TypeScript (4)\n\n## Directory Structure\nsrc/\n  main.rs\n  parser/\n    mod.rs\n    rust.rs\n\n## src/main.rs\n\n**Language:** Rust | **Size:** 1.2 KB | **Lines:** 45\n\n**Declarations:**\n`pub fn main() -\u003e Result\u003c()\u003e`\n`pub struct App`\n```\n\n| Detail Level | Content |\n|---|---|\n| `summary` | Directory tree + file list |\n| `signatures` (default) | + declarations, imports |\n| `full` | + doc comments, line numbers, body counts, metadata, relationships |\n\n## Filtering\n\n```bash\nindxr --filter-path src/parser              # subtree\nindxr --kind function --public-only         # public functions only\nindxr --symbol \"parse\"                      # symbol name search\nindxr -l rust,python                        # language filter\nindxr --filter-path src/model --kind struct --public-only  # combine\n```\n\nAll filters compose. `--kind` accepts: `function`, `struct`, `class`, `trait`, `enum`, `interface`, `module`, `method`, `constant`, `impl`, `type`, `namespace`, `macro`, and more.\n\n## Git Structural Diffing\n\n```bash\nindxr --since main\nindxr --since v1.0.0\nindxr --since HEAD~5\nindxr diff --pr 42                           # diff against a GitHub PR's base branch\n```\n\n```\n## Modified Files\n\n### src/parser/mod.rs\n+ `pub fn new_parser() -\u003e Parser`\n- `fn old_helper()`\n~ `fn process(x: i32)` → `fn process(x: i32, y: i32)`\n```\n\nMarkers: `+` added, `-` removed, `~` signature changed.\n\n## Complexity Hotspots\n\n```bash\nindxr --hotspots                             # top 30 most complex functions\nindxr --hotspots --filter-path src/parser    # scoped to a directory\n```\n\nShows cyclomatic complexity, max nesting depth, parameter count, body lines, and a composite score for each function. Only tree-sitter parsed languages are analyzed.\n\nMCP tools: `get_hotspots` (ranked list with filtering and sorting), `get_health` (aggregate metrics, documentation coverage, test ratio, hottest files), `get_type_flow` (cross-file type flow tracking — producers and consumers of any type).\n\n## Dependency Graph\n\n```bash\nindxr --graph dot                            # file-level DOT graph\nindxr --graph mermaid                        # file-level Mermaid diagram\nindxr --graph json                           # JSON graph\nindxr --graph dot --graph-level symbol       # symbol-level graph\nindxr --graph mermaid --filter-path src/mcp  # scoped to a directory\nindxr --graph dot --graph-depth 2            # limit to 2 hops\n```\n\n| Level | Description |\n|---|---|\n| `file` (default) | File-to-file import relationships |\n| `symbol` | Symbol-to-symbol relationships (trait impls, method calls) |\n\n## Token Budget\n\n```bash\nindxr --max-tokens 4000\n```\n\nTruncation order: doc comments → private declarations → children → least-important files. Directory tree and public API surface are preserved first.\n\n## Languages\n\n8 tree-sitter (full AST) + 19 regex (structural extraction):\n\n| Parser | Languages |\n|---|---|\n| tree-sitter | Rust, Python, TypeScript/TSX, JavaScript/JSX, Go, Java, C, C++ |\n| regex | Shell, TOML, YAML, JSON, SQL, Markdown, Protobuf, GraphQL, Ruby, Kotlin, Swift, C#, Objective-C, XML, HTML, CSS, Gradle, CMake, Properties |\n\nDetection is by file extension. Full details: [docs/languages.md](docs/languages.md)\n\n## Performance\n\nParallel parsing via rayon. Incremental caching via mtime + xxh3.\n\n| Codebase | Files | Lines | Cold | Cached |\n|---|---|---|---|---|\n| Small (indxr) | 47 | 19K | 17ms | 5ms |\n| Medium (atuin) | 132 | 22K | 20ms | 6ms |\n| Large (cloud-hypervisor) | 243 | 124K | 73ms | ~10ms |\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [CLI Reference](docs/cli-reference.md) | Complete flag and option reference |\n| [Languages](docs/languages.md) | Per-language extraction details |\n| [Output Formats](docs/output-formats.md) | Format and detail level reference |\n| [Filtering](docs/filtering.md) | Path, kind, symbol, visibility filters |\n| [Dependency Graph](docs/dep-graph.md) | File and symbol dependency visualization |\n| [Git Diffing](docs/git-diffing.md) | Structural diff since any git ref or GitHub PR |\n| [Token Budget](docs/token-budget.md) | Truncation strategy and scoring |\n| [Caching](docs/caching.md) | Cache format and invalidation |\n| [MCP Server](docs/mcp-server.md) | MCP tools, protocol, and client setup |\n| [Agent Integration](docs/agent-integration.md) | Usage with Claude, Codex, Cursor, Copilot, etc. |\n\n## Contributing\n\nContributions welcome — feel free to open an issue or submit a PR.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahdotsh%2Findxr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbahdotsh%2Findxr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahdotsh%2Findxr/lists"}