{"id":50826919,"url":"https://github.com/harf-promo/indexa","last_synced_at":"2026-06-13T20:01:13.153Z","repository":{"id":360779532,"uuid":"1251594634","full_name":"harf-promo/indexa","owner":"harf-promo","description":"The local context engine for AI. Indexa reads your code or your disk once, on your machine, and serves any AI tool — Claude Code, Cursor, or a local Ollama model — the relevant slice on demand. Saves cloud tokens; lets local models punch above their context window. Local-first, MCP-native. Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-06-13T19:06:09.000Z","size":2053,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T20:00:28.182Z","etag":null,"topics":["claude-code","context-engine","developer-tools","embeddings","local-first","mcp","ollama","rag","retrieval","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harf-promo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["wikithoughts"]}},"created_at":"2026-05-27T18:24:23.000Z","updated_at":"2026-06-13T19:06:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harf-promo/indexa","commit_stats":null,"previous_names":["harf-promo/indexa"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/harf-promo/indexa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harf-promo%2Findexa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harf-promo%2Findexa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harf-promo%2Findexa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harf-promo%2Findexa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harf-promo","download_url":"https://codeload.github.com/harf-promo/indexa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harf-promo%2Findexa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34298248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["claude-code","context-engine","developer-tools","embeddings","local-first","mcp","ollama","rag","retrieval","rust"],"created_at":"2026-06-13T20:00:32.577Z","updated_at":"2026-06-13T20:01:08.164Z","avatar_url":"https://github.com/harf-promo.png","language":"Rust","funding_links":["https://github.com/sponsors/wikithoughts"],"categories":[],"sub_categories":[],"readme":"# Indexa\n\n**The local context engine for AI.**\n\nYour AI meets your codebase cold on every session — burning paid tokens to relearn what it knew yesterday, or choking on a context window that can't hold your repo at all. Indexa reads your code or your entire disk **once, on your machine**, builds a persistent hierarchical context store, and serves any AI tool the precise, ranked slice it needs — instantly, every time.\n\n```bash\nindexa index  ~/code/my-repo            # scan + embed + summarize in one command\nindexa ask    \"where is auth handled?\"  # grounded answer with sources\nindexa export ~/code/my-repo --format xml \u003e .context.xml\nclaude \"given @.context.xml, find the auth flow and add MFA\"\n# the model spends its budget on the work you asked for — not on re-reading your tree\n```\n\n*The index is the substrate; context is the product. Local-first · model-agnostic · Apache-2.0.*\n\n\u003e Indexa is production-ready for daily use on one or more repos. Whole-disk indexing is fast; the storage format stabilises before 1.0. New here? Start with the **[Usage Guide](USAGE.md)** or **[Quickstart](docs/quickstart.md)**. Something broken? **[Troubleshooting](docs/TROUBLESHOOTING.md)**.\n\n---\n\n## See it work\n\nFour commands. One context. Every session.\n\n```console\n$ indexa index ~/code/my-repo\nScanning ~/code/my-repo\n  1,284 entries indexed.\n  Embedded 6,470 new chunks.\n  318 summaries generated.\nContext is ready.\n\n$ indexa ask \"where is auth handled?\"\nSearching 6,470 indexed chunks...\n\nAnswer:\nAuthentication is handled in src/auth/middleware.rs (the `require_auth` route\nguard) and src/auth/login.rs (the `login` entry point). Session tokens are\nminted and validated in src/auth/session.rs. [1, 2, 3]\n\nSources:\n  [1] src/auth/middleware.rs — require_auth\n  [2] src/auth/login.rs — login\n  [3] src/auth/session.rs — mint_token\n```\n\nThen hand the context to your AI tool — or let your agent pull it live over MCP:\n\n```bash\nindexa export ~/code/my-repo --format xml \u003e .context.xml   # the artifact, built on your machine\nindexa serve                                               # open the web workspace at :7620\nindexa mcp                                                 # expose the live index to any agent\n```\n\n---\n\n## Why Indexa\n\n**Stop paying to re-teach your AI your own codebase.** Every coding assistant wakes up amnesiac. Before it helps, it reads its way back to orientation — burning context window, paid tokens, and your patience on a lesson it learned five minutes ago. Indexa teaches it *once*: it builds a persistent, hierarchical context store on your machine and serves a small ranked slice on demand, so the model spends its budget on the work you asked for.\n\n\u003e **What that's worth — a worked example** *(illustrative, ~4 chars/token — run `indexa status`\n\u003e after a few sessions to see your own measured usage and estimated savings)*: an agent orienting itself in a medium repo\n\u003e typically reads ~40 files at ~2,000 tokens each ≈ **80K tokens — every session**. The same\n\u003e orientation through Indexa: one `search` (~300 tokens) + ten L0 one-line abstracts (~30 each) +\n\u003e the two files it actually needs in full (~4K) ≈ **5K tokens**. That's roughly **94% less**,\n\u003e before the session's real work starts — and the index was built locally, for zero tokens.\n\n**There are two kinds of context, and almost everyone conflates them.** *Working context* is what's in the model's window right now — scarce, paid, gone when the session ends. *Searchable context* is everything your AI could know: the store on disk. Indexa separates them. The model never holds your repo; it holds the ~2–4K characters that actually matter, retrieved from a store that can be gigabytes.\n\n**Local isn't the compromise — it's the unlock.** Your data never leaves the machine unless *you* point it at a cloud model, and zero tokens leave while Indexa builds context. A small local model stops being small: feed it a retrieved slice instead of the whole project and a 4K-window model reasons over a 100 MB codebase — fast, even on CPU, with a KV-cache sized by your choice, not your repo. One engine, two wins: it saves cloud tools their tokens **and** gives local models the context they can't hold.\n\n*(How retrieval keeps that slice relevant — hybrid search, the ANN index, the honest trade-offs — is in [docs/methodology.md](docs/methodology.md).)*\n\n---\n\n## The only tool of its kind\n\n**No other tool does this.** Indexa is the first local context engine that builds a persistent, hierarchically-summarised, locally-queryable index over your entire disk — and exposes it simultaneously through a CLI, a live web workspace, a native desktop app, and an MCP server that any AI agent can call in real time.\n\nThis is not a repo-to-prompt converter. It is not a document chat app. It is not an IDE extension. It is a persistent, on-device intelligence layer that any AI tool can reach — without re-reading your files, without sending your data to a server, and without starting from zero every session.\n\n**Indexa ends the cold-start problem, permanently.**\n\n---\n\n## What Indexa does\n\n- **One-command context** — `indexa index \u003cpath\u003e` scans, embeds, and summarises in a single step. Context is ready immediately; no pipeline to manage.\n- **Two-phase context** — an instant surface scan (zero AI, classifies code vs media vs build artifacts) then deep context: parse → chunk → embed → LLM file summaries rolled up bottom-up into a hierarchical context graph, with **L0 / L1 / L2 progressive disclosure** (one-line abstract → full summary → raw content).\n- **Hybrid retrieval** — keyword (BM25) + semantic (vector) fused with RRF, plus an **opt-in ANN index** that keeps dense search fast on 50K-plus-chunk corpora.\n- **Local multimodal** *(opt-in, on-device)* — caption images with a local vision model and transcribe audio with a local whisper CLI, so you can find media by what's *in* it, not just its filename.\n- **Code intelligence** — a code-relationship graph (imports + defined symbols + call edges) across Rust, Python, JS/TS, Go, and Java, plus `who_calls`, `blast_radius`, and an interactive **call-graph visualization** in the web Map tab — all queryable over MCP.\n- **Four ways to reach the index** — a CLI, a live web workspace with an Engine status bar, a native macOS desktop app (menu-bar, auto-updating), and an MCP server (42 tools) that AI agents call directly.\n- **Resource-aware** — a memory watchdog that won't freeze your machine, and a hardware-aware model picker that annotates every model with its memory footprint, fit against your live RAM, and a per-job ETA.\n- **Use your Claude subscription** — the `claude-code` provider runs summaries and answers on your Claude Pro/Max plan (no per-token billing); embeddings always stay local.\n- **Export** — XML (the format Anthropic's own docs recommend for context windows), Markdown, or JSON. **Watch** keeps the context current as files change.\n\n---\n\n## Four ways to use it\n\n- **CLI** — `index · ask · export · scan · deep · summarize · watch · serve · mcp · doctor · classify · completion · update`. Scriptable, pipeable, zero services required (`indexa completion \u003cshell\u003e` emits tab-completions).\n- **Web workspace** — `indexa serve` → `http://localhost:7620`. Responsive (collapses to a drawer on a phone), keyboard-navigable, and honest about impact — a **token-savings panel** shows what retrieval saved your AI tools this week. A live Engine status bar shows what the machine is doing while it builds:\n  ```\n  Engine  Building · 42 files/s · ETA 1m12s · gemma3:4b    CPU 38%   RAM 9.1 / 16 GB   pressure: ok\n  ```\n- **Desktop app** — a native macOS app that lives in the menu bar. Auto-updates silently. Bundles the web workspace — no separate `indexa serve` needed.\n- **MCP server** — `indexa mcp` exposes the live index to any [MCP](https://modelcontextprotocol.io) client (Claude Desktop, Cursor, Claude Code) over **42 tools** — retrieval (`search · browse_tree · get_summary · read_file · get_chunk_context · ask`), code graph (`dependencies · who_imports · who_calls · blast_radius · code_graph`), Context Packs, importance weights, smart classification, insights, decision review, config introspection, and indexing triggers.\n\n---\n\n## Code intelligence\n\nDeep-indexing records each code file's graph edges — what it **imports**, the symbols it **defines**, and what it **calls** — across Rust, Python, JS/TS, Go, and Java. Query it over MCP, so your agent reasons about structure without reading every file:\n\n```text\ndependencies(\"src/auth/session.rs\")\n  → imports:  crate::store::Db\n  → defines:  Session, mint_token, validate\n\nwho_imports(\"crate::store::Db\")\n  → src/auth/session.rs\n\nblast_radius(\"mint_token\")\n  → src/auth/session.rs, src/auth/login.rs, src/auth/middleware.rs\n```\n\nOr **see** the whole call graph: `indexa graph \u003cdir\u003e` on the CLI, or the **Graph** sub-view in the\nweb Map tab — an interactive force-directed view of which files call into which.\n\n---\n\n## Install\n\nDownload a pre-built binary from [Releases](../../releases):\n\n```bash\n# macOS (Apple Silicon)\ncurl -L -o /usr/local/bin/indexa \\\n  https://github.com/harf-promo/indexa/releases/latest/download/indexa-aarch64-apple-darwin\nchmod +x /usr/local/bin/indexa\nxattr -d com.apple.quarantine /usr/local/bin/indexa   # bypass Gatekeeper if prompted\n\n# macOS (Intel): indexa-x86_64-apple-darwin\n# Linux x86_64:  indexa-x86_64-linux-gnu      ·  Linux arm64: indexa-aarch64-linux-gnu\n# Windows x64:   indexa-x86_64-windows.exe\n```\n\nPull the local models (one-time, ~11 GB total; everything runs offline after this):\n\n```bash\nollama pull nomic-embed-text   # embeddings (~270 MB)\nollama pull gemma3:4b          # file summaries (~2.5 GB)\nollama pull gemma3:12b         # answers + directory roll-ups (~8 GB)\n```\n\nOr build from source (Rust ≥ 1.82): `git clone … \u0026\u0026 cargo build --release` → `target/release/indexa`.\n\n---\n\n## Bring your own model\n\nNo model is bundled — Indexa works with whatever you run. Configure in `~/.indexa/config.toml`:\n\n| Adapter | How it runs |\n|---|---|\n| **Ollama** | Local, fully offline (default). Point elsewhere with `OLLAMA_HOST`. |\n| **Claude subscription** | `provider = \"claude-code\"` — synthesis on your Claude Pro/Max plan, no per-token billing. Embeddings stay local. |\n| **llama.cpp** | Local via its HTTP server. |\n| **Google Gemini · OpenAI · Anthropic** | Cloud — data leaves your device; API key required. |\n\nDefaults: `nomic-embed-text` (embeddings) · `gemma3:4b` (file context) · `gemma3:12b` (answers + roll-ups). Optional cross-encoder reranking *fails open* — a model hiccup falls back to the original order, so it can never make `ask` worse.\n\n---\n\n## What's coming\n\n- **Mobile companion** — browse your index from a phone on the same network. The read-only API is already LAN-ready (`indexa serve --host 0.0.0.0`); a native client is next.\n- **Plugin marketplace** — the parser SDK is shipped (`indexa_parsers::Registry`); next is discovery and distribution of third-party parsers.\n\nRecently shipped: **agentic `ask`** (multi-hop plan→search→refine), **PageRank centrality** (hub files in the code graph), **signature graph visualization**, **universal macOS desktop build**, **Importance weighting**, **Insights** (duplicates / stale / weekly diff), **video captioning**, **Plugin SDK**, **LAN serve**.\n\nIdeas and votes in [Discussions](../../discussions/categories/ideas). Full detail in [ROADMAP.md](ROADMAP.md).\n\n---\n\n## Contributing\n\nIndexa is built in the open and welcomes contributors of every level. Read [CONTRIBUTING.md](CONTRIBUTING.md), browse [`good first issue`](../../issues?q=label%3A%22good+first+issue%22), and join [Discussions](../../discussions). Commits sign off with the [DCO](https://developercertificate.org/) (`git commit -s`); no CLA.\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE). Copyright 2025 Harf Promo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharf-promo%2Findexa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharf-promo%2Findexa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharf-promo%2Findexa/lists"}