{"id":51551313,"url":"https://github.com/Barnett-Studios/cxpak","last_synced_at":"2026-07-12T14:01:14.371Z","repository":{"id":343446480,"uuid":"1173491365","full_name":"Barnett-Studios/cxpak","owner":"Barnett-Studios","description":"Spends CPU cycles so you don't spend tokens. The LLM gets a briefing packet instead of a flashlight in a dark room.","archived":false,"fork":false,"pushed_at":"2026-06-17T07:20:14.000Z","size":3172,"stargazers_count":11,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T08:25:00.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Barnett-Studios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T12:29:37.000Z","updated_at":"2026-06-17T06:50:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Barnett-Studios/cxpak","commit_stats":null,"previous_names":["lyubomir-bozhinov/cxpak","barnett-studios/cxpak"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/Barnett-Studios/cxpak","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Barnett-Studios%2Fcxpak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Barnett-Studios%2Fcxpak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Barnett-Studios%2Fcxpak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Barnett-Studios%2Fcxpak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Barnett-Studios","download_url":"https://codeload.github.com/Barnett-Studios/cxpak/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Barnett-Studios%2Fcxpak/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"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-07-12T02:00:06.386Z","response_time":87,"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":[],"created_at":"2026-07-10T00:00:52.211Z","updated_at":"2026-07-12T14:01:14.365Z","avatar_url":"https://github.com/Barnett-Studios.png","language":"Rust","funding_links":[],"categories":["Documentation, Knowledge \u0026 Learning"],"sub_categories":[],"readme":"# cxpak\n\n![Rust](https://img.shields.io/badge/Rust-1.91+-orange.svg)\n![CI](https://github.com/Barnett-Studios/cxpak/actions/workflows/ci.yml/badge.svg)\n![Crates.io](https://img.shields.io/crates/v/cxpak)\n![Downloads](https://img.shields.io/crates/d/cxpak)\n![License](https://img.shields.io/badge/License-MIT-green.svg)\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\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/images/dashboard.png\" alt=\"Dashboard\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eArchitecture Explorer -- directed dependency graph with risk coloring\u003c/summary\u003e\n\u003cimg src=\"docs/images/architecture.png\" alt=\"Architecture Explorer\" width=\"100%\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eArchitecture -- tooltip with PageRank and metadata on hover\u003c/summary\u003e\n\u003cimg src=\"docs/images/architecture-tooltip.png\" alt=\"Architecture Tooltip\" width=\"100%\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRisk Heatmap -- treemap sized by token count, colored by risk score\u003c/summary\u003e\n\u003cimg src=\"docs/images/risk.png\" alt=\"Risk Heatmap\" width=\"100%\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFlow Diagram -- call graph with directional arrows\u003c/summary\u003e\n\u003cimg src=\"docs/images/flow.png\" alt=\"Flow Diagram\" width=\"100%\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDiff View -- before/after with blast radius overlay\u003c/summary\u003e\n\u003cimg src=\"docs/images/diff.png\" alt=\"Diff View\" width=\"100%\"\u003e\n\u003c/details\u003e\n\n## Install\n\n```bash\nbrew tap Barnett-Studios/tap \u0026\u0026 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:2.2.1 overview .\ndocker run --rm -v \"$(pwd):/repo\" ghcr.io/barnett-studios/cxpak@sha256:\u003cdigest\u003e 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:2.2.1 \\\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\ndocker build -f Dockerfile.standalone \\\n  --build-arg VERSION=2.3.0 \\\n  --build-arg SHA256_AMD64=c98d142aec62a70bb5ecccdf44120aaa55641a26b27d5a52821a093c79dd8cac \\\n  --build-arg SHA256_ARM64=2f7cc078446a65bdb8f2cbcc81b2e1932431b066d560fe99e90519c7afd3d580 \\\n  -t cxpak:2.3.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\u003e **HTTP vs MCP:** These are two separate transports — you cannot use the HTTP server as an MCP endpoint.\n\u003e\n\u003e **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` (`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\nThe v2.x per-tool names (`cxpak_auto_context`, `cxpak_health`, ...) remain callable as deprecated aliases for one release. 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_auto_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 \u003e Trimmed \u003e Documented \u003e Signature \u003e 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 \u003e= 90%, Trend \u003e= 70%, Mixed).\n\n`cxpak_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 -- four primitives (`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.\n\n```bash\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 SDK\n\nExtend cxpak with custom analyzers and detectors:\n\n- Plugin manifest with SHA-256 checksum verification before WASM compilation\n- wasmtime sandbox: epoch interruption (CPU), 64 MB memory cap, capability enforcement\n- File pattern scoping and content access control\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## 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 -\u003e v2.2.1; 0163 onward are written at decision time, now through 0190 (v3.0.0). Start with [the index](docs/adrs/INDEX.md).\n\n## License\n\nMIT\n\n---\n\nBuilt by [Barnett Studios](https://barnett-studios.com/) -- building products, teams, and systems that last.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBarnett-Studios%2Fcxpak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBarnett-Studios%2Fcxpak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBarnett-Studios%2Fcxpak/lists"}