{
"markdown": "# cxpak\n\n\n\n\n\n\n\n**Context plane · Active** — under development; the surface still moves.\nSee the [component map](https://github.com/Barnett-Studios) for how this fits the rest.\n\n**Spends CPU cycles so you don't spend tokens.**\n\ncxpak indexes your codebase using tree-sitter across 43 languages, builds a typed dependency graph, and produces token-budgeted context bundles that give LLMs a briefing packet instead of a flashlight in a dark room. It understands your code's architecture, conventions, risk profile, and data layer -- then packs exactly what the LLM needs, nothing more.\n\n## What it looks like\n\n`cxpak visual` renders a self-contained single-page dashboard -- three modes, inlined D3, **zero external assets, works offline**. Nineteen built-in colour palettes and a Cmd+K command palette over every file, symbol, and view. Every number on the page traces to a real computation; click any risk to see its exact derivation.\n\n
\n\n
\n\n
Overview -- a needle health dial and genome bars, ranked top risks, a proven Signals feed, and the Repo-DNA fingerprint barcode.
\n\n\nExplore -- one spatial canvas, Dependencies and Risk lenses\n\n\n\n\nHistory -- the architecture timeline, scrubbed commit by commit\n\n\n\n## Install\n\n```bash\nbrew tap Barnett-Studios/tap && brew install cxpak # macOS/Linux\ncargo install cxpak # any platform, incl. Windows\n```\n\nOn Windows, `cargo install cxpak` works, or download the prebuilt\n`cxpak-x86_64-pc-windows-msvc.zip` from the [latest release](https://github.com/Barnett-Studios/cxpak/releases/latest).\n\n## Docker\n\nDocker is a first-class deployment option — useful anywhere you want a reproducible, isolated install without managing a Rust toolchain: CI pipelines, sandboxed servers, Windows machines, or air-gapped environments.\n\n### Official image (recommended)\n\nMulti-arch (`amd64` / `arm64`) images are published to GitHub Container Registry on every release — no build, no Rust toolchain, no source checkout:\n\n```bash\ndocker run --rm -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak overview .\n```\n\nPin a tag or an immutable digest for reproducible deploys:\n\n```bash\ndocker run --rm -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak:3.1.0 overview .\ndocker run --rm -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak@sha256: overview .\n```\n\nImages are signed with [cosign](https://github.com/sigstore/cosign) (keyless) and carry SBOM + build-provenance attestations. Verify before deploying:\n\n```bash\ncosign verify ghcr.io/barnett-studios/cxpak:3.1.0 \\\n --certificate-identity-regexp '^https://github.com/Barnett-Studios/cxpak/' \\\n --certificate-oidc-issuer https://token.actions.githubusercontent.com\n```\n\n### From source\n\n```bash\ndocker build -t cxpak .\n```\n\nBuilds the full default feature set from your local checkout. First build is slow (candle ML deps); subsequent builds reuse a cached dependency layer.\n\n### Self-hosted / air-gapped\n\n[`Dockerfile.standalone`](Dockerfile.standalone) fetches the pre-built release binary, verifies its SHA-256 checksum, and packages it into an `ubuntu:24.04` runtime — no source checkout or Rust toolchain required. All base images and the downloaded binary are digest-pinned for reproducible builds.\n\nAll three build-args are **required** — the build fails immediately if any is omitted, so you can never accidentally produce a stale or mismatched image. Checksums are available on the [releases page](https://github.com/Barnett-Studios/cxpak/releases).\n\n```bash\n# SHA-256 values are per-release — copy the two for VERSION from the releases page.\ndocker build -f Dockerfile.standalone \\\n --build-arg VERSION=3.1.0 \\\n --build-arg SHA256_AMD64= \\\n --build-arg SHA256_ARM64= \\\n -t cxpak:3.1.0 .\n```\n\n### Usage\n\nThe container runs as a non-root user; the embedding model weights (~30 MB, downloaded on first use) live under `/home/cxpak/.cxpak` — mount a named volume there to persist them across runs.\n\n**macOS / Linux:**\n```bash\n# One-shot command\ndocker run --rm -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak overview .\n\n# HTTP server (--bind 0.0.0.0 required to reach the container from the host;\n# --token is mandatory when binding to a non-loopback address)\ndocker run -d -p 3000:3000 \\\n -v \"$(pwd):/repo\" \\\n -v cxpak-models:/home/cxpak/.cxpak \\\n ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret .\n\n# MCP — stdio only, one repo per instance (see note below)\ndocker run --rm -i -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak serve --mcp .\n```\n\n**Windows (PowerShell):**\n```powershell\n# One-shot command\ndocker run --rm -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak overview .\n\n# HTTP server\ndocker run -d -p 3000:3000 `\n -v ${PWD}:/repo `\n -v cxpak-models:/home/cxpak/.cxpak `\n ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret .\n\n# Verify (use curl.exe — PowerShell's curl alias does not work here)\ncurl.exe http://localhost:3000/health\n\n# MCP — stdio only, one repo per instance (see note below)\ndocker run --rm -i -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak serve --mcp .\n```\n\nReplace `mysecret` with any non-empty secret of your choice. `/health` is open (GET) as a liveness probe; every other endpoint requires the bearer token when one is set (with no `--token`, on a loopback bind, all routes are open):\n```bash\ncurl http://localhost:3000/health # no auth required\ncurl -X POST -H \"Authorization: Bearer mysecret\" http://localhost:3000/v1/conventions\n```\n\n> **HTTP vs MCP:** These are two separate transports — you cannot use the HTTP server as an MCP endpoint.\n>\n> **MCP scope:** Each MCP instance indexes exactly one repository — the path passed at startup (`.` in the examples above, which maps to the mounted `/repo`). To serve multiple repos simultaneously, run one container per repo and register each in your MCP client config. The HTTP server has the same single-repo scope.\n\n## Quick start\n\n```bash\n# See your codebase the way an LLM should\ncxpak overview .\n\n# Trace a symbol through the dependency graph\ncxpak trace \"handle_request\" .\n\n# Generate an interactive dashboard\ncxpak visual --visual-type dashboard .\n\n# Get a guided reading order for onboarding\ncxpak onboard .\n```\n\n## Use with AI tools\n\n### Claude Code / Cursor (MCP)\n\nAdd to `.mcp.json` in your project root:\n\n```json\n{\n \"mcpServers\": {\n \"cxpak\": {\n \"command\": \"cxpak\",\n \"args\": [\"serve\", \"--mcp\", \".\"]\n }\n }\n}\n```\n\nYour AI tool gets five intent-parameterized tools; each selects a capability via a required `op` argument. `cxpak_context` (`op: \"context\"`) is the main entry point -- one call, optimal context:\n\n| Intent tool | Capabilities (via `op`) |\n|----------|-------|\n| **`cxpak_context`** | `context`, `retrieval`, `search`, `overview`, `stats`, `briefing`, `pack_context`, `context_for_task` |\n| **`cxpak_graph`** | `graph` (`nodes`/`node`/`neighbors`/`path`/`subgraph`), `trace`, `blast_radius`, `call_graph`, `dead_code`, `api_surface`, `data_flow`, `cross_lang`, `predict` |\n| **`cxpak_data`** | `data` (indexed / live schema) |\n| **`cxpak_review`** | `review`, `diff`, `verify` |\n| **`cxpak_insight`** | `health`, `risks`, `architecture`, `conventions`, `security_surface`, `drift`, `visual`, `onboard` |\n\n\nThe v2.x per-tool names (`cxpak_auto_context`, `cxpak_health`, ...) remain callable as deprecated aliases; **`tools/list` does not advertise them**, so a client that builds its callable set from the advertised surface will not find them. No removal release is set. See [`docs/MIGRATION-3.0.md`](docs/MIGRATION-3.0.md).\n\nOn large repositories, `cxpak serve --mcp` answers the MCP `initialize` handshake immediately and builds the index in the background -- fixing the startup timeout. Tool calls that arrive before the index is ready get a graceful retry status, then byte-identical results once it is built.\n\n### Claude Code Plugin\n\n```\n/plugin install cxpak\n```\n\nAuto-triggers on architecture questions and change reviews. Slash commands: `/cxpak:overview`, `/cxpak:trace`, `/cxpak:diff`, `/cxpak:clean`.\n\n### HTTP Server\n\n```bash\ncxpak serve . # port 3000\ncxpak serve --token my-secret . # with Bearer auth on /v1/ endpoints\ncxpak watch . # file watcher with hot index\n```\n\n### LSP\n\n```bash\ncxpak lsp . # stdio, works with any LSP client\n```\n\nCodeLens, hover, diagnostics, workspace symbols, plus 16 custom `cxpak/*` methods. Supports `didOpen`/`didChange`/`didClose` for in-editor reactivity.\n\n## Core capabilities\n\n### Auto Context\n\n`cxpak_context` (`op: \"context\"`) is the primary entry point. Give it a task and token budget; it returns exactly what the LLM needs.\n\nThe pipeline: query expansion with domain-specific synonyms, relevance scoring over **6 deterministic signals** (keyword, symbol, path, domain, import proximity, PageRank) fused with **Reciprocal Rank Fusion (RRF)** -- the default ranking as of 3.0.0, measured +164% recall over the prior weighted-sum on a 31-PR benchmark and deterministic across processes -- then seed selection, noise filtering, test/schema/blast-radius enrichment, progressive degradation (Full > Trimmed > Documented > Signature > Stub), and per-file annotations explaining why each file was included. Embeddings are an optional 7th signal (see [Embeddings](#embeddings)).\n\nEvery response starts with a Repository DNA section -- a ~1000 token convention summary so the LLM knows how your team writes code before it sees any.\n\n### Intelligence\n\n| Feature | What it does |\n|---------|-------------|\n| **Health Score** | Composite metric across conventions, test coverage, churn stability, coupling, cycles, dead code |\n| **Risk Ranking** | Files ranked by churn x blast radius x test gap -- the ones most likely to cause problems |\n| **Architecture** | Per-module coupling, cohesion, circular dependencies, boundary violations, god files |\n| **Blast Radius** | Change impact: direct dependents, transitive dependents, test files, schema dependents, each with risk scores |\n| **Change Prediction** | Structural + historical (180-day co-change) + call-graph signals, confidence 0.3--0.9 |\n| **Architecture Drift** | Compare against stored baselines; auto-saves snapshots for trend tracking |\n| **Dead Code** | Symbols with zero callers, ranked by importance (PageRank x visibility) |\n| **Call Graph** | Cross-file call edges with Exact/Approximate confidence levels |\n| **Security Surface** | Unprotected endpoints, secrets, SQL injection, validation gaps, exposure scores across 12 frameworks |\n| **Data Flow** | Trace values source-to-sink through the call graph; reports module/language/security boundary crossings |\n| **Cross-Language** | HTTP, FFI, gRPC, GraphQL, shared schema, and exec bridges between languages |\n\n### Visual Intelligence\n\nSix interactive views, self-contained HTML with D3.js. No build step, no CDN.\n\n```bash\ncxpak visual --visual-type dashboard .\ncxpak visual --visual-type architecture .\ncxpak visual --visual-type risk .\ncxpak visual --visual-type flow --symbol handle_request .\ncxpak visual --visual-type timeline .\ncxpak visual --visual-type diff --files \"src/api.rs,src/db.rs\" .\n```\n\nExport formats: HTML, Mermaid, SVG, PNG, C4 DSL, JSON.\n\nLayout engine: Sugiyama method with SCC condensation, barycenter crossing minimization, Brandes-Kopf coordinate assignment, and 7+/-2 cognitive clustering.\n\n### Conventions\n\nExtracts a quantified convention profile from what your team actually does: naming, imports, error handling, dependencies, testing, visibility, function length, git health. Each pattern has counts, percentages, and strength labels (Convention >= 90%, Trend >= 70%, Mixed).\n\n`cxpak_review` (`op: \"verify\"`) checks code changes against observed conventions -- only flags violations in changed lines. `cxpak conventions export/diff` enables CI drift detection with SHA256 checksums.\n\n### Onboarding\n\n```bash\ncxpak onboard .\n```\n\nGenerates a dependency-ordered reading guide: files topologically sorted, grouped into phases by module, ordered by PageRank. Each file lists key symbols to focus on and an estimated reading time.\n\n## Language support (43)\n\n**Full extraction** (functions, classes, methods, imports, exports):\nRust, TypeScript, JavaScript, Python, Java, Go, C, C++, Ruby, C#, Swift, Kotlin, Bash, PHP, Dart, Scala, Lua, Elixir, Zig, Haskell, Groovy, Objective-C, R, Julia, OCaml, MATLAB, Clojure\n\n**Structural extraction** (selectors, keys, blocks):\nCSS, SCSS, Markdown, JSON, YAML, TOML, Dockerfile, HCL/Terraform, Protobuf, Svelte, Makefile, HTML, GraphQL, XML\n\n**Database DSLs:** SQL, Prisma\n\n## Data layer awareness\n\ncxpak understands your data layer and uses it to build a richer dependency graph:\n\n- **Schema detection** -- SQL DDL, Prisma, Django, SQLAlchemy, TypeORM, ActiveRecord\n- **Migration sequences** -- Rails, Alembic, Flyway, Django, Knex, Prisma, Drizzle\n- **Embedded SQL linking** -- inline SQL in application code creates edges to table definitions\n- **Column-level lineage** -- impact traced at column granularity: \"alter `users.email`\" resolves to the specific queries, ORM models, endpoints, and tests that reference that column, and a different column's blast excludes the email-only files\n- **Live database introspection** -- connect to a running Postgres or MySQL and index the live schema, then compute drift against the schema the code declares. Pure-Rust rustls drivers (no OpenSSL), **read-only**, and the DSN is **never logged or persisted**. Off by default; enabled with the `data-introspect` build feature\n- **Typed edge types** -- Import, ForeignKey, ViewReference, EmbeddedSql, OrmModel, MigrationSequence, ColumnReference, CrossLanguage, and more. Each edge carries a confidence marker; heuristic (inferred) edges are labeled so a regex guess is never mistaken for a structurally proven dependency\n\n## Graph query and export\n\nQuery the typed dependency graph directly -- five primitives (`nodes`, `node`, `neighbors`, `path`, `subgraph`), identical across MCP, HTTP, LSP, and CLI. Edges carry a typed `edge_type` and a confidence marker; inferred (heuristic) edges are surfaced as such. `nodes` enumerates every valid id with no arguments -- the way to discover ids (they're repo-relative file paths) before calling the others; `subgraph` reports any seed that isn't a real node in `unknown_seeds` rather than echoing it back as one.\n\n```bash\ncxpak graph nodes .\ncxpak graph neighbors --id src/index/graph.rs .\ncxpak graph path --from src/main.rs --to src/output/mod.rs .\ncxpak graph subgraph --seeds src/scanner/mod.rs,src/parser/mod.rs --depth 2 .\n```\n\nExport the graph to **Cypher** (Neo4j) or **GraphML** (Gephi, yEd, NetworkX) with the same honest typed edges and per-edge confidence:\n\n```bash\ncxpak visual --format cypher .\ncxpak visual --format graphml .\n```\n\n## Embeddings\n\nSemantic similarity is an **optional** 7th scoring signal, **opt-in** via `.cxpak.json`. Without that config the default 6 deterministic signals are used and **no model is downloaded**. When configured, cxpak uses either local inference with all-MiniLM-L6-v2 (~30 MB, downloaded on first use) or a remote provider -- OpenAI, Voyage AI, or Cohere with your own key. On `cxpak serve --mcp` the embedding index is built in the background, off the startup path, so it never delays the MCP handshake; if it fails, cxpak falls back to the 6 deterministic signals.\n\nMinimal local config:\n\n```json\n{ \"embeddings\": { \"provider\": \"local\" } }\n```\n\n## WASM plugin loader — a skeleton, not a working SDK\n\n**You cannot extend cxpak with a WASM plugin today.** `PluginLoader::load()` verifies the module's\nchecksum, compiles it, instantiates it, and then returns `guest function binding not yet\nimplemented`. The WIT bridge that would make a guest function callable does not exist, so no plugin\ncode has ever run.\n\nThe `plugins` feature is therefore excluded from `default` — a stock `cargo install cxpak` does not\nbuild it, and the plugin management commands are behind the same gate. What is built out is the\nloading path: a manifest with SHA-256 verification before compilation, a 10 MiB module cap, a 64 MiB\nmemory limiter, and a 10 s epoch deadline. Treat none of it as a security boundary until the bridge\nlands and the gaps in [`SECURITY.md`](SECURITY.md#the-wasm-plugin-loader-does-not-run-plugins) are\nclosed — [#42](https://github.com/Barnett-Studios/cxpak/issues/42).\n\n## Workspace support\n\nFor monorepos: `--workspace packages/api` scopes scanning to a subdirectory while keeping the full repo as the git root.\n\n## Caching\n\nParse results cached in `.cxpak/cache/` keyed on file mtime and size. Cache invalidates automatically when tree-sitter grammar versions change. Atomic writes with advisory locking for concurrent process safety. `cxpak clean .` to reset.\n\n## Rust client (non-default `client` feature)\n\nRust callers can talk to a cxpak MCP server through the official client rather than\nhand-rolling an rmcp session. It is **off by default**, so `cargo install cxpak` still builds\nan indexer and pulls no rmcp:\n\n```toml\n[dependencies]\ncxpak = { version = \"3.1\", features = [\"client\"] }\n```\n\nIf you want the client without the 43 bundled grammars, `default-features = false, features =\n[\"client\", \"daemon\"]` builds the library — `daemon` is currently the floor, not `client` alone.\n\n`CxpakClient` is one method, and its return type is the contract:\n\n```rust\nuse cxpak::client::{CxpakClient, RmcpCxpakClient};\nuse serde_json::json;\n\nlet client = RmcpCxpakClient::new(std::env::current_dir()?);\nmatch client.call(\"cxpak_context\", json!({\"op\": \"overview\"})).await {\n Some(bundle) => use_it(bundle),\n // NOT \"the server looked and found nothing\" — the tool was unavailable, errored,\n // or degraded. Map it to a skipped observation, never to a verdict.\n None => skip(),\n}\n```\n\n`RmcpCxpakClient` is lazy: no child process is spawned until the first call, spawns are\nbacked off after repeated failures, and the child's stderr is nulled so a server banner can\nnever contaminate a caller that must not write to stderr (a hook, for instance).\n\nFor your own tests, `RecordedCxpakClient` replays a `name → response` map with no I/O, and\n`from_dir` loads a directory of committed `.json` recordings. A missing directory is an\n**error**, not an empty client — a mis-pathed fixture set reporting a clean run over nothing\nis the failure this constructor refuses to have.\n\n```rust\nuse cxpak::client::RecordedCxpakClient;\nlet client = RecordedCxpakClient::from_dir(std::path::Path::new(\"recordings/cxpak\"))?;\n```\n\nThe feature adds `rmcp`, and only `rmcp`, to what gets built (`async-trait` is already in the\ndefault tree transitively). CI asserts both directions — that the client compiles and its\ntests run, and that `rmcp` stays out of the default dependency tree.\n\n## Stable API\n\nv2.0.0 establishes semver for the MCP API. Tool names, parameters, and response structures are stable across 2.x.\n\n3.0.0 **consolidates the 26 MCP tools into 5 intent-parameterized tools** (`cxpak_context`, `cxpak_graph`, `cxpak_data`, `cxpak_review`, `cxpak_insight`), each selecting a capability via a required `op` argument. This is the one breaking change in 3.0.0 and affects **MCP clients only** -- the CLI, the HTTP `/v1/*` API, and the LSP `cxpak/*` methods are unchanged. The 26 old tool names remain callable as deprecated, undiscoverable aliases for one release. See [`docs/MIGRATION-3.0.md`](docs/MIGRATION-3.0.md).\n\n## Architecture decisions\n\nEvery architecturally significant decision is recorded as an ADR in [`docs/adrs/`](docs/adrs/) -- what was chosen, the options considered, and the conditions under which to revisit it. The records span parsing, the typed dependency graph, relevance scoring, token budgeting, the MCP/HTTP/LSP surfaces, and distribution. Records 0001-0162 were reconstructed across v0.1.0 -> v2.2.1; 0163 onward are written at decision time, now through 0199 (v3.1.0). Start with [the index](docs/adrs/INDEX.md).\n\n## License\n\nLicensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.\nUnless you explicitly state otherwise, any contribution you intentionally submit for\ninclusion in the work shall be dual-licensed as above, without any additional terms.\n\n---\n\nBuilt by [Barnett Studios](https://barnett-studios.com/) -- building products, teams, and systems that last.\n",
"bytes": 21401,
"sha": "580689a29d4241800eeb43779d13b7107fe52ff63e3646d1f1a199b212904d20",
"repo_slug": "barnett-studios/cxpak",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_barnett_studios_cxpak_cxpak_0d92033e/readme"
}
![\"Overview\"](\"docs/images/overview.png\")
\n![\"Explore](\"docs/images/explore.png\")
\n![\"History](\"docs/images/history.png\")
\n