cxpak
About
Spends CPU cycles so you don't spend tokens. The LLM gets a briefing packet instead of a flashlight in a dark room.
Details
- Author
- barnett-studios
- Categories
- Developer Tools, AI
Jump to
Setup
Install cxpak in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/barnett-studios/cxpak
Follow the installation instructions in the repository README, then restart your MCP client.
Context plane · Active— under development; the surface still moves. See thecomponent mapfor how this fits the rest.
Spends CPU cycles so you don't spend tokens.
cxpak 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.
cxpak visualrenders 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.
Overview -- a needle health dial and genome bars, ranked top risks, a proven Signals feed, and the Repo-DNA fingerprint barcode.
brew tap Barnett-Studios/tap && brew install cxpak # macOS/Linux cargo install cxpak # any platform, incl. Windows
On Windows,cargo install cxpakworks, or download the prebuiltcxpak-x86_64-pc-windows-msvc.zipfrom thelatest release.
Docker 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.
Multi-arch (amd64/arm64) images are published to GitHub Container Registry on every release — no build, no Rust toolchain, no source checkout:
docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak overview .
Pin a tag or an immutable digest for reproducible deploys:
docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak:3.1.0 overview . docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak@sha256:<digest> overview .
Images are signed withcosign(keyless) and carry SBOM + build-provenance attestations. Verify before deploying:
cosign verify ghcr.io/barnett-studios/cxpak:3.1.0 \ --certificate-identity-regexp '^https://github.com/Barnett-Studios/cxpak/' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com
Builds the full default feature set from your local checkout. First build is slow (candle ML deps); subsequent builds reuse a cached dependency layer.
All three build-args arerequired— the build fails immediately if any is omitted, so you can never accidentally produce a stale or mismatched image. Checksums are available on thereleases page.
# SHA-256 values are per-release — copy the two for VERSION from the releases page. docker build -f Dockerfile.standalone \ --build-arg VERSION=3.1.0 \ --build-arg SHA256_AMD64=<cxpak-x86_64-unknown-linux-gnu checksum> \ --build-arg SHA256_ARM64=<cxpak-aarch64-unknown-linux-gnu checksum> \ -t cxpak:3.1.0 .
The 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.
# One-shot command docker run --rm -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak overview . # HTTP server (--bind 0.0.0.0 required to reach the container from the host; # --token is mandatory when binding to a non-loopback address) docker run -d -p 3000:3000 \ -v "$(pwd):/repo" \ -v cxpak-models:/home/cxpak/.cxpak \ ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret . # MCP — stdio only, one repo per instance (see note below) docker run --rm -i -v "$(pwd):/repo" ghcr.io/barnett-studios/cxpak serve --mcp .
# One-shot command docker run --rm -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak overview . # HTTP server docker run -d -p 3000:3000 -v ${PWD}:/repo -v cxpak-models:/home/cxpak/.cxpak ghcr.io/barnett-studios/cxpak serve --bind 0.0.0.0 --token mysecret . # Verify (use curl.exe — PowerShell's curl alias does not work here) curl.exe http://localhost:3000/health # MCP — stdio only, one repo per instance (see note below) docker run --rm -i -v ${PWD}:/repo ghcr.io/barnett-studios/cxpak serve --mcp .
Replacemysecretwith any non-empty secret of your choice./healthis 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):
curl http://localhost:3000/health # no auth required curl -X POST -H "Authorization: Bearer mysecret" http://localhost:3000/v1/conventions
HTTP vs MCP:These are two separate transports — you cannot use the HTTP server as an MCP endpoint.
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.
# See your codebase the way an LLM should cxpak overview . # Trace a symbol through the dependency graph cxpak trace "handle_request" . # Generate an interactive dashboard cxpak visual --visual-type dashboard . # Get a guided reading order for onboarding cxpak onboard .
{ "mcpServers": { "cxpak": { "command": "cxpak", "args": ["serve", "--mcp", "."] } } }
Your AI tool gets five intent-parameterized tools; each selects a capability via a requiredopargument.cxpak_context(op: "context") is the main entry point -- one call, optimal context:
The v2.x per-tool names (cxpak_auto_context,cxpak_health, ...) remain callable as deprecated aliases for one release. Seedocs/MIGRATION-3.0.md.
On large repositories,cxpak serve --mcpanswers the MCPinitializehandshake 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.
Auto-triggers on architecture questions and change reviews. Slash commands:/cxpak:overview,/cxpak:trace,/cxpak:diff,/cxpak:clean.
cxpak serve . # port 3000 cxpak serve --token my-secret . # with Bearer auth on /v1/ endpoints cxpak watch . # file watcher with hot index
cxpak lsp . # stdio, works with any LSP client
CodeLens, hover, diagnostics, workspace symbols, plus 16 customcxpak/methods. SupportsdidOpen/didChange/didClosefor in-editor reactivity.
cxpak_context(op: "context") is the primary entry point. Give it a task and token budget; it returns exactly what the LLM needs.
The pipeline: query expansion with domain-specific synonyms, relevance scoring over6 deterministic signals(keyword, symbol, path, domain, import proximity, PageRank) fused withReciprocal 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 (seeEmbeddings).
Every 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.
Six interactive views, self-contained HTML with D3.js. No build step, no CDN.
cxpak visual --visual-type dashboard . cxpak visual --visual-type architecture . cxpak visual --visual-type risk . cxpak visual --visual-type flow --symbol handle_request . cxpak visual --visual-type timeline . cxpak visual --visual-type diff --files "src/api.rs,src/db.rs" .
Export formats: HTML, Mermaid, SVG, PNG, C4 DSL, JSON.
Layout engine: Sugiyama method with SCC condensation, barycenter crossing minimization, Brandes-Kopf coordinate assignment, and 7+/-2 cognitive clustering.
Extracts 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).
cxpak_review(op: "verify") checks code changes against observed conventions -- only flags violations in changed lines.cxpak conventions export/diffenables CI drift detection with SHA256 checksums.
Generates 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.
Full extraction(functions, classes, methods, imports, exports): Rust, 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
Structural extraction(selectors, keys, blocks): CSS, SCSS, Markdown, JSON, YAML, TOML, Dockerfile, HCL/Terraform, Protobuf, Svelte, Makefile, HTML, GraphQL, XML
cxpak understands your data layer and uses it to build a richer dependency graph:
- Schema detection-- SQL DDL, Prisma, Django, SQLAlchemy, TypeORM, ActiveRecord
- Migration sequences-- Rails, Alembic, Flyway, Django, Knex, Prisma, Drizzle
- Embedded SQL linking-- inline SQL in application code creates edges to table definitions
- Column-level lineage-- impact traced at column granularity: "alterusers.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 filesdata-introspect
- 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 isnever logged or persisted. Off by default; enabled with thebuild feature
- 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
Query the typed dependency graph directly -- five primitives (nodes,node,neighbors,path,subgraph), identical across MCP, HTTP, LSP, and CLI. Edges carry a typededge_typeand a confidence marker; inferred (heuristic) edges are surfaced as such.nodesenumerates every valid id with no arguments -- the way to discover ids (they're repo-relative file paths) before calling the others;subgraphreports any seed that isn't a real node inunknown_seedsrather than echoing it back as one.
cxpak graph nodes . cxpak graph neighbors --id src/index/graph.rs . cxpak graph path --from src/main.rs --to src/output/mod.rs . cxpak graph subgraph --seeds src/scanner/mod.rs,src/parser/mod.rs --depth 2 .
Export the graph toCypher(Neo4j) orGraphML(Gephi, yEd, NetworkX) with the same honest typed edges and per-edge confidence:
cxpak visual --format cypher . cxpak visual --format graphml .
Semantic similarity is anoptional7th scoring signal,opt-invia.cxpak.json. Without that config the default 6 deterministic signals are used andno 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. Oncxpak serve --mcpthe 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.
{ "embeddings": { "provider": "local" } }
WASM plugin loader — a skeleton, not a working SDK
You cannot extend cxpak with a WASM plugin today.PluginLoader::load()verifies the module's checksum, compiles it, instantiates it, and then returnsguest function binding not yet implemented. The WIT bridge that would make a guest function callable does not exist, so no plugin code has ever run.
Thepluginsfeature is therefore excluded fromdefault— a stockcargo install cxpakdoes not build it, and the plugin management commands are behind the same gate. What is built out is the loading path: a manifest with SHA-256 verification before compilation, a 10 MiB module cap, a 64 MiB memory limiter, and a 10 s epoch deadline. Treat none of it as a security boundary until the bridge lands and the gaps inSECURITY.mdare closed —#42.
For monorepos:--workspace packages/apiscopes scanning to a subdirectory while keeping the full repo as the git root.
Parse 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.
Rust client (non-defaultclientfeature)
Rust callers can talk to a cxpak MCP server through the official client rather than hand-rolling an rmcp session. It isoff by default, socargo install cxpakstill builds an indexer and pulls no rmcp:
[dependencies] cxpak = { version = "3.1", features = ["client"] }
If you want the client without the 43 bundled grammars,default-features = false, features = ["client", "daemon"]builds the library —daemonis currently the floor, notclientalone.
CxpakClientis one method, and its return type is the contract:
use cxpak::client::{CxpakClient, RmcpCxpakClient}; use serde_json::json; let client = RmcpCxpakClient::new(std::env::current_dir()?); match client.call("cxpak_context", json!({"op": "overview"})).await { Some(bundle) => use_it(bundle), // NOT "the server looked and found nothing" — the tool was unavailable, errored, // or degraded. Map it to a skipped observation, never to a verdict. None => skip(), }
RmcpCxpakClientis lazy: no child process is spawned until the first call, spawns are backed off after repeated failures, and the child's stderr is nulled so a server banner can never contaminate a caller that must not write to stderr (a hook, for instance).
For your own tests,RecordedCxpakClientreplays aname → responsemap with no I/O, andfrom_dirloads a directory of committed<tool>.jsonrecordings. A missing directory is anerror, not an empty client — a mis-pathed fixture set reporting a clean run over nothing is the failure this constructor refuses to have.
use cxpak::client::RecordedCxpakClient; let client = RecordedCxpakClient::from_dir(std::path::Path::new("recordings/cxpak"))?;
The feature addsrmcp, and onlyrmcp, to what gets built (async-traitis already in the default tree transitively). CI asserts both directions — that the client compiles and its tests run, and thatrmcpstays out of the default dependency tree.
v2.0.0 establishes semver for the MCP API. Tool names, parameters, and response structures are stable across 2.x.
3.0.0consolidates 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 requiredopargument. This is the one breaking change in 3.0.0 and affectsMCP clients only-- the CLI, the HTTP/v1/API, and the LSPcxpak/*methods are unchanged. The 26 old tool names remain callable as deprecated, undiscoverable aliases for one release. Seedocs/MIGRATION-3.0.md.
Every architecturally significant decision is recorded as an ADR indocs/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 withthe index.
Licensed under either ofMITorApache-2.0at your option. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in the work shall be dual-licensed as above, without any additional terms.
Built byBarnett Studios-- building products, teams, and systems that last.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
next-devtools-mcp is a MCP server that provides Next.js development tools and utilities for AI coding assistants like Claude and Cursor.
Word search, crossword, and sudoku generator MCP server with printable PDF worksheets, themed word banks, and verifiable LLM evals. Local-first, from the makers of puzzletide.com.
A demonstration server for ActionKit, providing access to Slack actions via Claude Desktop.
MCP server that lets Claude Code agents delegate tasks to agents in other project directories, with parallel dispatch, sessions, and async jobs.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.




