{"id":51583031,"url":"https://github.com/Mathews-Tom/archex","last_synced_at":"2026-07-30T08:00:35.012Z","repository":{"id":341235956,"uuid":"1168211370","full_name":"Mathews-Tom/archex","owner":"Mathews-Tom","description":"Verified code context for agents","archived":false,"fork":false,"pushed_at":"2026-07-23T02:01:35.000Z","size":17184,"stargazers_count":54,"open_issues_count":1,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T04:03:53.995Z","etag":null,"topics":["agents","archex","ast","code-intelligence","code-retrieval","code-search","coding-agents","context-engineering","context-window-optimization","developer-tools","local-first","mcp","pi","python","retrieval","semantic-search","token-efficiency","tree-sitter"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mathews-Tom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/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-02-27T06:04:33.000Z","updated_at":"2026-07-23T02:01:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"b304c8bd-c46e-43b3-859c-611de3c4a002","html_url":"https://github.com/Mathews-Tom/archex","commit_stats":null,"previous_names":["mathews-tom/archex","determ-ai/archex"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/Mathews-Tom/archex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mathews-Tom%2Farchex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mathews-Tom%2Farchex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mathews-Tom%2Farchex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mathews-Tom%2Farchex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mathews-Tom","download_url":"https://codeload.github.com/Mathews-Tom/archex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mathews-Tom%2Farchex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36067204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-30T02:00:05.956Z","response_time":106,"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":["agents","archex","ast","code-intelligence","code-retrieval","code-search","coding-agents","context-engineering","context-window-optimization","developer-tools","local-first","mcp","pi","python","retrieval","semantic-search","token-efficiency","tree-sitter"],"created_at":"2026-07-11T08:00:23.469Z","updated_at":"2026-07-30T08:00:34.991Z","avatar_url":"https://github.com/Mathews-Tom.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# archex\n\n[![CI](https://github.com/Mathews-Tom/archex/actions/workflows/ci.yml/badge.svg)](https://github.com/Mathews-Tom/archex/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/archex)](https://pypi.org/project/archex/)\n[![Downloads](https://img.shields.io/pypi/dm/archex)](https://pypi.org/project/archex/)\n[![Python](https://img.shields.io/pypi/pyversions/archex)](https://pypi.org/project/archex/)\n[![Tests](https://img.shields.io/badge/tests-3619_passing-brightgreen)](https://github.com/Mathews-Tom/archex/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-91.1%25-brightgreen)](https://github.com/Mathews-Tom/archex/actions/workflows/ci.yml)\n[![Languages](https://img.shields.io/badge/languages-26-orange)](#language-support)\n[![MCP tools](https://img.shields.io/badge/MCP_tools-17-purple)](#mcp-and-claude-code)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Typing](https://img.shields.io/badge/typing-pyright_strict-blue)](https://github.com/microsoft/pyright)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n[![archex banner](assets/archex-banner.png)](assets/archex-banner.svg)\n\n---\n\n**Verified local code context for agents.**\n\nAI coding agents usually start by opening a file, following an import, checking a type definition, and backtracking through the repo until the context window is partly spent before the real task starts. archex does that retrieval and structural expansion up front and returns a ranked, token-budgeted context bundle plus a receipt that records what was included, what was skipped, and whether the bundle is complete enough to act on.\n\nIt runs locally, uses deterministic retrieval and analysis, and does not require hosted inference or an API key. The v0.16 line adds five full-tier language promotions (PHP, Ruby, Scala, C, C++), a new `structured` tier for markup/config languages (HTML, XML, YAML, Markdown, CSS) with a Maven POM dependency-graph plugin, portable index artifacts for team-shared bootstrap, and diff-scoped blast-radius analysis with per-symbol risk classification. The v0.17 line adds opt-in, non-blocking tool-call hooks across six clients (Claude Code, oh-my-pi, Pi, OpenCode, Codex CLI, Cursor) that augment `grep`/`glob`-shaped calls with archex results — or, where a client has no matching hook to augment, log a diagnostics-only trace instead of claiming a capability that isn't there. The v0.18 line slims the default `--format json` chunk output (unset/empty fields dropped, `--full` to restore) and adds an opt-in `--format toon` encoding for further token savings on top of that.\n\n**Start:** [30-second quickstart](#30-second-quickstart) · [MCP and Claude Code](#mcp-and-claude-code) · [Python API](#python-api) · [Local metrics](docs/LOCAL_METRICS.md) · [Compatibility matrix](docs/CLIENT_COMPATIBILITY_MATRIX.md) · [Installation trust contract](docs/INSTALLATION_TRUST_CONTRACT.md) · [Security policy](SECURITY.md)\n\n**Quick links:** [Proof bar](#proof-bar) · [Fast paths](#fast-paths) · [What archex returns](#what-archex-returns) · [Use it your way](#use-it-your-way) · [Trust and operations](#trust-and-operations) · [Measured results](#measured-results) · [Advanced workflows](#advanced-workflows) · [Installation details](#installation-details) · [Language support](#language-support) · [Development](#development) · [Documentation map](#documentation-map)\n\n[![archex explainer](assets/archex-explainer.gif)](assets/archex-explainer.gif)\n\n[Watch the explainer](assets/archex-explainer.mp4) · [Open banner SVG](assets/archex-banner.svg) · [Open infographic SVG](assets/archex-infographic-landscape.svg) · [Read the measured comparison](docs/ARCHEX_VS_COCOINDEX.md)\n\n## Proof bar\n\n| Safe-to-act signals | Surfaces | Language coverage | Public evidence |\n| --- | --- | --- | --- |\n| Query/scout receipts expose freshness, index revision, skipped candidates, omitted edges, completeness, and next action | CLI, MCP, Python API, Docker, Claude Code skill | 26 declared language IDs across `full`, `structured`, and `chunk-only` tiers | C1 public comparison, raw-ripgrep/read baseline, bundle-only evaluator lane, and TurboQuant A/B measurement with 7.07× mean vector `.npz` compression |\n\narchex does not ask the downstream agent to trust ranking alone. Every query/scout receipt explains what was returned, what was skipped, whether freshness was current, and whether the bundle is complete enough to act on.\n\n**External replication.** archex tried to reproduce a published retrieval win in its original authors' own reference setup, and did not. [`GATE-A.md`](GATE-A.md) records the result: the reproduced delta landed below its pre-registered band, so every null this project has measured to date remains attributable to its own implementation rather than to the literature.\n\n## Fast paths\n\n| If you are evaluating... | Start here | Why |\n| --- | --- | --- |\n| Agent workflows | `archex doctor`, then `archex context \"question\"` | Checks local trust first, then returns a candidate map, exact fetch handles, selected code, relation paths, a route decision, and a receipt in one call. |\n| Already using an agent that calls Grep/Glob | `archex install-client \u003cclient\u003e --hooks` | Zero added context cost — augments existing tool calls instead of registering a new MCP tool surface. |\n| Want the full tool surface (graph, impact, symbol lookup, etc.) | [MCP and Claude Code](#mcp-and-claude-code) | Stdio MCP server, optional warm `--watch`, additive top-level receipts. Registers 18 tool schemas that resend every turn regardless of use — heavier than hooks, richer than grep/glob augmentation. |\n| Python applications | [Python API](#python-api) | Deterministic `query()`, `analyze()`, `compare()`, and receipt-bearing bundles. |\n| Benchmark proof | [Measured results](#measured-results) and [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) | Same-task C1 report, raw-ripgrep/read baseline, bundle-only evaluator reports, required-file trust gates, and TurboQuant storage/recall evidence. |\n| Installation and clients | [Compatibility matrix](docs/CLIENT_COMPATIBILITY_MATRIX.md) | Client bootstrap paths for Claude Code, Codex, Pi, OpenCode, Cursor, and oh-my-pi (`omp`); global/user scope by default, `--dry-run` previews. |\n\n## 30-second quickstart\n\n```bash\nuv tool install archex\narchex setup\narchex context \"How does authentication work?\"\n```\n\n`archex context` is the documented primary agent path — one call returns a candidate map, exact fetch handles, selected code, relation paths, a route decision, and a receipt. The specialized `archex query`/`archex scout`/`archex symbol` commands remain fully supported for their narrower use cases:\n\n```bash\narchex query \"How does authentication work?\" --format xml\n```\n\n`archex setup` is the primary guided onboarding command. It initializes repo-local state, builds the first index, checks MCP runtime health, and offers to configure detected clients and agent guidance.\n\n`archex doctor` reports whether the local index, grammar support, model cache, MCP registration, and `.archex/` state are healthy. Repo-local commands default to the current working directory.\n\nFor explicit repo initialization without the full guided setup:\n\n```bash\narchex init\narchex query \"How does authentication work?\" --format xml\n```\n\n## What archex returns\n\narchex returns a **context bundle plus receipt**, not an answer. The downstream agent or model still does the reasoning; archex decides which code, symbols, dependencies, and type context belong in the prompt, then records why that bundle is safe or incomplete.\n\n```xml\n\u003ccontext query=\"How does authentication work?\"\u003e\n  \u003cstructural-context\u003e\n    \u003cfile-tree\u003e\u003c![CDATA[\nsrc/auth/\n  middleware.py\n  tokens.py\n  models.py\n    ]]\u003e\u003c/file-tree\u003e\n  \u003c/structural-context\u003e\n  \u003cchunks\u003e\n    \u003cchunk file=\"src/auth/middleware.py\" lines=\"42-78\" symbol=\"authenticate\" score=\"0.9312\" tokens=\"284\"\u003e\n      \u003cimports\u003e\u003c![CDATA[from auth.tokens import verify_jwt]]\u003e\u003c/imports\u003e\n      \u003ccode\u003e\u003c![CDATA[\ndef authenticate(request: Request) -\u003e User:\n    token = extract_bearer(request)\n    claims = verify_jwt(token)\n    return load_user(claims.sub)\n      ]]\u003e\u003c/code\u003e\n    \u003c/chunk\u003e\n  \u003c/chunks\u003e\n  \u003ctype-definitions\u003e\n    \u003ctype-def file=\"src/auth/models.py\" symbol=\"User\" lines=\"10-24\"\u003e\u003c![CDATA[\n@dataclass\nclass User: ...\n    ]]\u003e\u003c/type-def\u003e\n  \u003c/type-definitions\u003e\n  \u003cdependencies\u003e\n    \u003cinternal\u003eauth.tokens.verify_jwt\u003c/internal\u003e\n    \u003cexternal\u003epyjwt\u003c/external\u003e\n  \u003c/dependencies\u003e\n\u003c/context\u003e\n```\n\nThe bundle carries ranked chunks, import context, referenced type definitions, dependency edges, token counts, and provenance. Use `--format json` or `--format markdown` when XML is not the right downstream envelope, or `--format toon` (optional `archex[toon]` extra) for a smaller-still encoding built on the same field selection. `json` and `toon` output omit unset/empty chunk fields by default — pass `--full` to restore every field.\n\nSmall receipt example:\n\n```json\n{\n  \"receipt\": {\n    \"freshness\": \"clean\",\n    \"index_revision\": \"3d8b0c…\",\n    \"token_budget\": { \"requested\": 12000, \"consumed\": 6132 },\n    \"returned_total\": 12,\n    \"skipped_total\": 23,\n    \"included_edges_total\": 9,\n    \"omitted_edges_total\": 17,\n    \"context_complete\": \"incomplete\",\n    \"context_complete_reason\": \"dependency_frontier_cut\",\n    \"recommended_next_action\": \"fetch_skipped_candidate\",\n    \"returned_context\": [\n      {\n        \"handle\": \"chunk:src/auth/middleware.py::authenticate#function\",\n        \"file_path\": \"src/auth/middleware.py\",\n        \"start_line\": 42,\n        \"end_line\": 78,\n        \"score\": 0.9312\n      }\n    ],\n    \"skipped_candidates\": [\n      { \"file_path\": \"src/auth/session.py\", \"reason\": \"below_threshold\" }\n    ]\n  }\n}\n```\n\nUse [CONTEXT_RECEIPTS](docs/CONTEXT_RECEIPTS.md) for the full field contract.\n\n\n## Why archex is different\n\nAgents usually explore repositories by opening one file, following imports, checking type definitions, and backtracking. That burns context before the real task starts. Unlike a hosted RAG service, a vector database, or a chatbot, archex does not answer questions, host anything remotely, or require vector search to work — it performs local retrieval and structural expansion first: BM25F, optional local vector/SPLADE signals, graph expansion with edge confidence, type-definition packing, and intent-routed token budgets.\n\n```text\nRepository → repo-local index → intent routing → retrieval → graph/type expansion → token-budgeted bundle → agent / MCP client\n```\n\narchex is a selection and assembly layer. Compression tools can shrink the final bundle later, but compressed irrelevant context is still irrelevant. For the vector index itself, v0.13 enables 4-bit TurboQuant storage by default when vector retrieval is turned on: same measured recall/MRR on the current corpus, about seven times smaller vector artifacts, and self-describing compatibility with older unquantized `.npz` files.\n\n## Use it your way\n\n### CLI\n\n```bash\narchex context \"Where is cache invalidation handled?\"\narchex query \"Where is cache invalidation handled?\" --format xml\narchex scout \"How does authentication flow through this repo?\" --budget 1000 --format json\narchex query \"How does authentication work?\" --format toon   # requires: uv add \"archex[toon]\"\narchex index --quantize-vectors --quantize-bits 4 --allow-remote-code\narchex graph export --output .archex/archgraph.json\narchex graph neighbors src/auth/middleware.py --graph .archex/archgraph.json --format markdown\narchex symbol 'symbol:src/auth/middleware.py::authenticate#function'\n```\n\n### MCP and Claude Code\n\nRegisters all 18 archex tools with a client; every tool's schema resends on every conversational turn regardless of use, since tool-calling APIs are stateless. That is real, measurable context cost — roughly 6,000 tokens for the full set, computed from the tool schemas in `src/archex/integrations/mcp.py`. If a client only needs grep/glob-shaped lookups, `archex install-client \u003cclient\u003e --hooks` (documented further down this section) gets the same retrieval quality with zero added schema cost. Use MCP when the fuller surface — graph inspection, impact analysis, batch symbol lookup — is worth that fixed per-turn cost. The `context` tool is the same primary agent path as the CLI's `archex context`: query/intent/profile/filters/budgets/handles in, candidate map/fetch handles/selected code/relation paths/route/receipt/next action out.\n\nInstall the MCP extra and register the stdio server:\n\n```bash\nuv tool install \"archex[mcp]\"\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"archex\": { \"command\": \"archex\", \"args\": [\"mcp\"] }\n  }\n}\n```\n\nInstall the client config (global/user scope by default; pass a SOURCE path or `--scope project` for a repo-local install). Add `--dry-run` to preview the exact target and config without writing:\n\n```bash\narchex install-client claude-code            # global, writes immediately\narchex install-client claude-code --dry-run  # preview only, no changes\narchex install-client claude-code . --scope project\n```\n\nFor warm local sessions, keep the MCP process alive and optionally watch the repo:\n\n```bash\narchex mcp --watch --watch-path .\n```\n\narchex is a first-class `install-client` target for Claude Code, Codex, Cursor, OpenCode, Pi, and oh-my-pi (`omp` → `~/.omp/agent/mcp.json`). Registration alone is not enough: harnesses with on-demand tool discovery surface a registered server's tools only after the agent activates them, and agent guidance that names only the CLI never produces MCP calls. Append the ready-to-paste guidance prompt to a global or repo-specific agent file so agents reach for the MCP tools first:\n\n```bash\narchex install-client omp --agent-file ~/.omp/agent/AGENTS.md\n```\n\n`archex metrics` then reports a CLI-vs-MCP surface split so you can see whether agents actually route context through archex. The [compatibility matrix](docs/CLIENT_COMPATIBILITY_MATRIX.md) explains the registration → surfacing → invocation distinction.\n\nThe in-repo Claude Code skill lives at [`skills/archex/`](skills/archex/). Its `/archex` command runs `archex doctor`, initializes/indexes when needed, scouts first for broad questions, then fetches exact `symbol:` or `chunk:` handles before a larger bundle query.\n\nSix of those clients also get an opt-in, non-blocking tool-call hook: `archex install-client \u003cclient\u003e --hooks` (`--remove-hooks` to uninstall) wires `python -m archex.integrations.hook`'s lookup/timeout/freshness engine into the client's own hook mechanism. On Claude Code, oh-my-pi, Pi, and OpenCode it augments `grep`/`glob`-equivalent tool calls with archex symbol-search results (receipt-stamped, freshness-marked); Codex CLI and Cursor have no matching tool-call hook to attach that to, so they ship a diagnostics-only fallback that logs what would have been surfaced instead of injecting anything. Every one of the six degrades silently on a missing/stale index, a timeout (~500ms hard budget), or any internal error — none of them ever block a tool call, and none ever match `Read`/`beforeReadFile`. Full per-client contracts, confirmation-spike findings, and manual verification steps live in the [compatibility matrix](docs/CLIENT_COMPATIBILITY_MATRIX.md#claude-code-pretooluse-hook-opt-in).\n\nExact install, MCP, Docker, cache, uninstall, and trust semantics are documented in the [installation trust contract](docs/INSTALLATION_TRUST_CONTRACT.md). Client-specific config targets and bootstrap paths live in the [compatibility matrix](docs/CLIENT_COMPATIBILITY_MATRIX.md).\n\nLocal usage metrics are off by default. If a user explicitly enables them with `archex metrics enable`, `ARCHEX_USAGE_METRICS=on`, or the persisted metrics setting, archex writes a machine-local ledger at `~/.archex/usage.sqlite`. That ledger records anonymous counters only: tool name, category, token counts, file count, repo-local random ID, freshness, and index revision. It does not store query text, file paths, symbols, handles, rendered outputs, prompt bodies, remote URLs, org names, or repo names in event rows. `archex metrics summary` reports two labeled savings numbers, and the headline one is **savings versus a realistic targeted read** (`savings_pct_vs_targeted_read`): the matched line ranges plus a small context window, which is what an agent that reads `grep` line numbers before opening a file actually pays. The second number, savings versus a full-file paste (`tokens_saved = max(full_file_tokens - returned, 0)`), is a compression figure against a naive whole-file paste and is systematically larger — on a representative single-query ledger row from this repository, 14.9% versus targeted read against 90.1% versus full-file paste. Quote the targeted-read number. Both baselines are derived from the index, so the metrics path re-reads no file and calls no model. Targeted-read tokens are recorded only where returned chunks carry line spans (`query`); `scout`'s file-only results record no targeted-read baseline, so a scout-only ledger shows `Savings vs targeted: 0.0%` — that is an absent baseline, not a measured zero. Whole-repo avoided tokens are demoted below the savings lines and labeled an upper-bound/context figure, not savings.\n\nImportant boundary: archex ships with no telemetry by default. Optional local metrics are separate from telemetry, stay on the machine, and require explicit enablement. Detailed traces remain a second explicit opt-in on top of metrics enablement. The exact calculation rules, privacy boundary, and controls live in [LOCAL_METRICS](docs/LOCAL_METRICS.md).\n\n`archex metrics` is the control surface:\n\n```bash\narchex metrics enable\narchex metrics\narchex metrics export --output usage.json\narchex metrics delete --all\narchex metrics trace enable\nARCHEX_USAGE_METRICS=on archex query \"Where is auth handled?\"\n```\n\nDetailed traces stay opt-in via `archex metrics trace enable` or `ARCHEX_USAGE_TRACE=on`. Traces remain local-only and still do not store source code or rendered outputs. Metrics code paths make no LLM calls, no hosted upload calls, and no background network calls in v1.\n### Python API\n\n```python\nfrom archex import query\nfrom archex.models import RepoSource\n\nbundle = query(\n    RepoSource(local_path=\".\"),\n    \"Where is database connection pooling implemented?\",\n)\nprint(bundle.to_prompt(format=\"xml\"))\n```\n\n`analyze()` returns an `ArchProfile`; `compare()` returns deterministic cross-repo dimension comparisons. LangChain and LlamaIndex retrievers ship as optional extras.\n\n### Docker\n\nTwo local-first images are built in CI:\n\n\u003cdetails\u003e\n\u003csummary\u003eDocker and warm-container MCP examples\u003c/summary\u003e\n\n```bash\n# BM25-only, no torch\ndocker run --rm -v \"$PWD:/workspace\" -w /workspace ghcr.io/mathews-tom/archex:slim archex doctor\n\n# Full local-embedding image with FastEmbed runtime\ndocker run --rm -v \"$PWD:/workspace\" -w /workspace ghcr.io/mathews-tom/archex:full archex query \"Where is cache invalidation handled?\" --strategy hybrid\n```\n\nWarm-container MCP pattern:\n\n```bash\ndocker run -d --name archex-mcp -v \"$PWD:/workspace\" -w /workspace ghcr.io/mathews-tom/archex:slim sleep infinity\ndocker exec -i archex-mcp archex mcp\n```\n\nMCP client config for that container:\n\n```json\n{\n  \"mcpServers\": {\n    \"archex\": {\n      \"command\": \"docker\",\n      \"args\": [\"exec\", \"-i\", \"archex-mcp\", \"archex\", \"mcp\"]\n    }\n  }\n}\n```\n\nThe mounted repository owns `.archex/`, so indexes survive container restarts and stay out of source control.\n\u003c/details\u003e\n\n## Trust and operations\n\n| Surface | Contract |\n| --- | --- |\n| Security policy | Supported versions, disclosure workflow, no-telemetry posture, secret-handling guidance, and model remote-code policy live in [SECURITY](SECURITY.md). |\n| Context receipts | Field contract, freshness/completeness semantics, output surfaces, and benchmark linkage live in [CONTEXT_RECEIPTS](docs/CONTEXT_RECEIPTS.md). |\n| Compatibility matrix | Tested vs unverified clients, exact config shapes, bootstrap commands, and verification steps live in [CLIENT_COMPATIBILITY_MATRIX](docs/CLIENT_COMPATIBILITY_MATRIX.md). |\n| Installation trust contract | Exact CLI, MCP, Docker, skill, cache, network, freshness, benchmark, and uninstall semantics live in [INSTALLATION_TRUST_CONTRACT](docs/INSTALLATION_TRUST_CONTRACT.md). |\n| `archex install-client` | Client config writer for Claude Code, Codex, Pi, OpenCode, Cursor, and oh-my-pi (`omp`). Global/user scope by default; `--dry-run` previews without writing. |\n| `archex doctor` | Text/JSON diagnostics for index health, staleness, local model cache presence, grammar availability by tier, MCP registration, model security, and `.archex/` disk usage. |\n| Repo-local `.archex/` | Generated state: settings, metadata, SQLite index, optional vectors, graph artifacts, dogfood history. Keep it uncommitted. |\n| Local usage metrics | Calculation rules, privacy boundaries, default-off versus opt-in behavior, export/delete controls, and retention live in [LOCAL_METRICS](docs/LOCAL_METRICS.md). |\n| `archex report status-card` | Opt-in, dimensioned documentation/release status summary: doc-link, ADR, and CODEOWNERS-style ownership evidence (each disabled unless its `documentation_evidence_providers` entry is configured) plus local CHANGELOG/CI-workflow evidence. Every dimension links to immutable local evidence; there is no composite score or letter grade, and the output is never written back into the repository automatically — paste it into your own README by hand if you want to publish it. |\n| `archex report release-artifact` | Per-release compatibility + benchmark evidence bundle: archex's own installed version, supported Python range, report/index schema versions, a pointer to any checked-in benchmark manifest, and an embedded status card, as one read-only JSON document suitable for attaching to a GitHub release. |\n| Read-only CI examples | `.github/workflows/report-diff.yml` and `.github/workflows/status-card.yml` grant only `contents: read`, pin every Action to a full commit SHA (never a floating tag), and upload only their own declared report/status/compatibility outputs — verified by `tests/test_report_ci_workflow.py`. |\n\n## Measured results\n\nThe public C1 harness publishes the same external-repo comparison for archex, cocoindex-code (`ccc`), and a raw-ripgrep/read baseline. It records cold-start, warm latency, recall, precision, F1, token efficiency, required-file recall, missed-required-file rate, missed-required-task rate, all-required-present rate, receipt accuracy, and bundle-completion penalty tokens. The checked-in artifacts include those trust fields; receipt accuracy is `n/a` for the historical C1 run because those artifacts predate query receipt capture. Core retrieval benchmarks make no LLM calls.\n\nSee [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) for the current published comparison and [Retrieval Default Decisions](docs/RETRIEVAL_DEFAULT_DECISIONS.md) for the decision trail.\n\nA broader competitive comparison is available with `archex benchmark headtohead competitive --input benchmarks/headtohead/results --format markdown`. It groups the same lanes by repo/task family and aggregate (no aggregate-only winner) and adds warm p50/p95 latency, region/line recall where labeled, compression ratio, and an operational table. The checked-in public artifact set now includes the benchmark-only archex candidate lanes (`archex_query_compressed`, `archex_query_efficiency_packed`) alongside `archex`, `ccc`, raw-ripgrep/read, and two Graphify follow-up lanes: `graphify_build_plus_query` (aggregate recall `0.70`, required-file recall `0.70`, cold-start `937 ms`, warm p50/p95 `165/184 ms`) and `graphify_query_warm` (aggregate recall `0.70`, required-file recall `0.70`, cold-start `0 ms`, warm p50/p95 `168/207 ms`). Graphify is reported as a graph / memory layer, not as a direct retrieval-equivalent winner, so build cost and warm-query cost stay separate. Headroom-style compression lanes appear when operator artifacts are present. No new public claim is made unless the corresponding checked-in artifacts exist under `benchmarks/headtohead/results/`.\n\nBundle-only evaluation is a separate opt-in lane: `archex benchmark bundle-eval --evaluator-command ...` gives a user-supplied local command only the rendered bundle and receipt JSON, then reports bundle-only success and files the evaluator still needed outside returned context. archex does not provide hosted evaluator calls, telemetry, credentials, or default network behavior for that lane.\n\nCross-tool token efficiency is measured offline with `archex benchmark cross-tool`: it compares the tokens archex spends to localize a task's required files against a naive grep/read agent (whole grep-hit files, or `+/-K` context windows around hits) at a fixed required-file recall, so no figure compares unequal recall. On the checked-in reference artifact ([`benchmarks/cross-tool-efficiency/cross-tool-comparison.json`](benchmarks/cross-tool-efficiency/cross-tool-comparison.json)), restricted to tasks where archex reaches 100% required-file recall, the token reduction **versus that naive grep/read agent** runs from 95.4% to 97.2% across the two external corpora (for example external-localization: 13,247 vs 469,836 tokens, 97.2% versus the naive agent). The self-repo corpus is withdrawn from every currently published figure: archex's own generic keywords (`index`, `query`, `config`) match everywhere in its own source, so the naive agent there reads a median of 32.5 units per task against 3.0 on the external corpora, and the resulting per-corpus reduction is an artifact of the corpus rather than a property of archex. Shipped changelog entries are historical records and are not rewritten, so the `0.15.0` entry still quotes the older self-inclusive range; the figures here supersede it. The baseline is also a blind-read agent with no triage step between `grep` and `read`, so it is a lower bound on a naive strategy and not a measurement of competent agent behavior — that semantics and the measured units-read distribution are documented in [Local Benchmark Evidence](docs/LOCAL_BENCHMARK_EVIDENCE.md#cross-tool-efficiency-baseline-semantics). It measures how much cheaper archex localizes when it succeeds, not that it always succeeds. This is a benchmark-only number: it never enters the in-process ledger or `archex metrics summary`. The per-corpus table and method live in [LOCAL_METRICS](docs/LOCAL_METRICS.md).\n\nTurboQuant evidence is measured separately with `archex_query_hybrid_quantized_4bit` against `archex_query_hybrid`: 35 tasks, 7.07× mean vector `.npz` compression, 6.98× minimum compression, recall Δ +0.000, MRR Δ +0.000, F1 Δ +0.000, required-file recall Δ +0.000, and mean query latency Δ +110 ms. That passed the default gate, so 4-bit TurboQuant is now the default storage mode for vector indexes.\n\n| Lane | Recall | Required-file recall | Missed task rate | F1 | Token efficiency | Token efficiency after completion | Warm latency ms |\n| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| `archex` | 0.95 | 0.95 | 0.16 | 0.66 | 0.76 | 0.74 | 408 |\n| `ccc` | 0.32 | 0.32 | 0.79 | 0.31 | 0.48 | 0.41 | 521 |\n| `raw-ripgrep/read` | 1.00 | 1.00 | 0.00 | 0.05 | 0.00 | 0.00 | 773 |\n\n### What this means for your workflow\n\n- **Coverage stays close to raw search without paying raw-search token cost.** `raw-ripgrep/read` reaches `1.00` required-file recall, but it does so at `0.00` token efficiency. archex lands at `0.95` required-file recall with `0.76` token efficiency, so the returned bundle stays close to exhaustive file coverage without filling the prompt with every textual match.\n- **Missed-task failures drop sharply versus `ccc`.** archex's missed task rate is `0.16`; `ccc` lands at `0.79`. In the published C1 run, that is the difference between usually returning the files an agent needs and often requiring a second pass before the task can finish.\n- **Vector storage got much smaller without a measured retrieval-quality change.** The published 4-bit TurboQuant run reports `7.07×` mean vector `.npz` compression (`6.98×` minimum) with recall Δ `+0.000`, MRR Δ `+0.000`, and F1 Δ `+0.000`, so local vector indexes take far less disk without a measured quality regression in that benchmark.\n- **`--format toon` trims the bundle further, on request.** `--format json`/`--format scout json` already drop unset/empty chunk fields by default (`--full` restores them); `--format toon` (optional `archex[toon]` extra) measures ~17% smaller than that default JSON output on the representative bundle in `tests/serve/test_renderers.py::test_toon_smaller_than_json_for_realistic_bundle`. Both are opt-in — the CLI's default format stays `xml`, which was already minimal before either change.\n\n## Advanced workflows\n\n```bash\n# Repo-local lifecycle\narchex init\narchex index\narchex index --export-artifact .archex/index.archexidx\narchex init --from-artifact .archex/index.archexidx\narchex status --strict\narchex doctor --format json\n\n# Architecture and graph surfaces\narchex analyze --format markdown\narchex onboard\narchex graph export --output .archex/archgraph.json\narchex graph path src/archex/cli/query_cmd.py src/archex/serve/context.py --graph .archex/archgraph.json --format markdown\narchex impact --changed-file src/archex/serve/context.py\narchex impact --diff HEAD~1\n\n# Diff review — one versioned AnalysisArtifactV1, source-redacted by construction\narchex report diff --base origin/main --format json\narchex report diff --base origin/main --format markdown\narchex report diff --base origin/main --format html \u003e report.html\narchex report delta --base origin/main --format markdown\narchex report status-card --format markdown  # M9, opt-in: dimensioned doc/ADR/ownership + release evidence, disabled unless configured\narchex report release-artifact  # M9: per-release compatibility + benchmark evidence bundle (version, schema versions, status card)\n\n# Benchmarks and gates\narchex benchmark headtohead report --input .archex/headtohead --format markdown\narchex benchmark run --strategy archex_query_hybrid_quantized_4bit --output .archex/e2e-quantized --allow-remote-code\narchex benchmark report --input .archex/e2e-quantized --baseline .archex/e2e-baseline --format markdown\narchex benchmark gate --input .archex/e2e --baseline .archex/e2e-baseline --warn-latency-ms 3000\narchex benchmark bundle-eval --tasks-dir benchmarks/tasks --evaluator-command ./local-evaluator\narchex dogfood --all --baseline benchmarks/dogfood_baseline.json --format dogfood-delta\n```\n\n## Installation details\n\n```bash\nuv tool install archex                    # CLI, system-wide\nuv add archex                             # project dependency\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOptional extras and integrations\u003c/summary\u003e\n\n```bash\n# Agent integrations\nuv tool install \"archex[mcp]\"             # MCP server\nuv add \"archex[langchain]\"                # LangChain retriever\nuv add \"archex[llamaindex]\"               # LlamaIndex retriever\nuv add \"archex[lsap]\"                     # LSP type enrichment\nuv add \"archex[toon]\"                     # TOON output format (token-lean encoding)\n\n# Local retrieval extras\nuv add \"archex[vector-fast]\"              # FastEmbed (ONNX-backed, ~50MB)\nuv add \"archex[vector-torch]\"             # sentence-transformers / torch\nuv add \"archex[splade]\"                   # SPLADE sparse retrieval\nuv add \"archex[graph]\"                    # Leiden graph clustering\n# Bundles every extra: vector-fast, graph, vector-torch, splade, mcp, langchain, llamaindex, lsap, toon\nuv add \"archex[all]\"\n```\n\n\u003c/details\u003e\n\nFor the full trust contract, including exact MCP JSON, Docker commands, cache locations, network behavior, and uninstall steps, see [Installation and Trust Contract](docs/INSTALLATION_TRUST_CONTRACT.md).\n\n## Language support\n\n| Tier | Languages | Extraction |\n| --- | --- | --- |\n| `full` | Python, JavaScript, TypeScript/TSX, Go, Rust, Java, Kotlin, C#, Swift, PHP, Ruby, Scala, C, C++ | Symbols, imports, graph edges |\n| `structured` | HTML, XML, YAML, Markdown, CSS | Outline + native cross-file reference edges (script/link/img/a for HTML; anchors/aliases for YAML; links/section-anchors for Markdown; `@import`/`url()` for CSS); no programming-symbol claim |\n| `chunk-only` | Lua, Bash/Shell, SQL, TOML, JSON, Solidity | AST chunking + retrieval; no symbol/import graph claim |\n| `unknown` | any other text file | line-window chunks for BM25 visibility |\n\nNeed another language? Register an adapter via Python entry points. See [System Design](docs/SYSTEM_DESIGN.md) for the extension contract.\n\n## What archex is not\n\n- **Not a chatbot** — it emits context bundles; another agent or LLM does the explaining.\n- **Not a hosted RAG service** — indexing and retrieval run locally unless you explicitly query a remote Git URL.\n- **Not a vector database** — vector search is optional; BM25 and structural signals are first-class.\n- **Not an LSP replacement** — use LSAP/LSP where compiler-backed type resolution matters; archex packages repository-scale context for agents.\n- **Not a prompt template library** — output is structured retrieval evidence, not prompt prose.\n- **Not a multimodal knowledge-graph builder** — no LLM-driven concept extraction over PDFs, images, or notes, and no persistent cross-session graph artifact; archex indexes source code deterministically to assemble token-budgeted retrieval context, not a browsable knowledge base.\n\n## Development\n\n```bash\ngit clone https://github.com/Mathews-Tom/archex.git\ncd archex\nuv sync --all-extras\n\nuv run ruff check \u0026\u0026 uv run ruff format --check .\nuv run pyright\nuv run pytest\n```\n\n## Documentation map\n\nAuthority chain: README → [System Design](docs/SYSTEM_DESIGN.md) / [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) → [Roadmap completion record](docs/ROADMAP.md#2026-unified-roadmap-completion) → [Retrieval Default Decisions](docs/RETRIEVAL_DEFAULT_DECISIONS.md).\n\n- [Why archex](docs/WHY_ARCHEX.md) — the agent token problem this solves\n- [System Overview](docs/OVERVIEW.md) — current product overview and boundaries\n- [System Design](docs/SYSTEM_DESIGN.md) — shipped architecture, graph query, scout, language tiers, and distribution surfaces\n- [archex vs. cocoindex-code](docs/ARCHEX_VS_COCOINDEX.md) — evidence-backed C1 comparison\n- [Retrieval Default Decisions](docs/RETRIEVAL_DEFAULT_DECISIONS.md) — default-strategy and TurboQuant evidence gates\n- [Context Receipts](docs/CONTEXT_RECEIPTS.md) — receipt field contract and safe-to-act semantics\n- [Local Metrics](docs/LOCAL_METRICS.md) — token-savings math, privacy boundary, and default-off versus opt-in behavior\n- [Portable Index Artifact](docs/PORTABLE_INDEX_ARTIFACT.md) — export/import format, compression, staleness fallback, and `.gitattributes` handling for team-shared index bootstrap\n- [Language Promotion Gate](docs/LANGUAGE_PROMOTION_GATE.md) — the recall/ranking-stability regression gate every language-tier promotion runs against\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/chart?repos=Mathews-Tom/archex\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=Mathews-Tom%2Farchex\u0026type=date\u0026legend=top-left)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMathews-Tom%2Farchex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMathews-Tom%2Farchex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMathews-Tom%2Farchex/lists"}