cxpak

Spends CPU cycles so you don't spend tokens. The LLM gets a briefing packet instead of a flashlight in a dark room.

A Rust CLI that indexes codebases using tree-sitter and produces token-budgeted context bundles for LLMs.

Installation

# Via Homebrew (macOS/Linux)
brew tap Barnett-Studios/tap
brew install cxpak

# Via cargo
cargo install cxpak

Claude Code Plugin

cxpak ships as a Claude Code plugin — skills auto-trigger when you ask about codebase structure or changes, and slash commands give you direct control.

Install the plugin:

/plugin marketplace add Barnett-Studios/cxpak
/plugin install cxpak

Skills (auto-invoked):

Commands (user-invoked):

The plugin auto-downloads the cxpak binary if it's not already installed.

Usage

# Structured repo summary within a token budget
cxpak overview --tokens 50k .

# Write output to a file
cxpak overview --tokens 50k --out context.md .

# Focus on a specific directory (boosts ranking)
cxpak overview --tokens 50k --focus src/api .

# Trace from a function/error, pack relevant code paths
cxpak trace --tokens 50k "handle_request" .

# Trace with full dependency graph traversal
cxpak trace --tokens 50k --all "MyError" /path/to/repo

# Different output formats
cxpak overview --tokens 50k --format json .
cxpak overview --tokens 50k --format xml .

# Show changes with dependency context (vs working tree)
cxpak diff --tokens 50k .

# Diff against a specific ref
cxpak diff --tokens 50k --git-ref main .

# Diff by time range
cxpak diff --tokens 50k --since "1 week" .

# Full dependency graph context
cxpak diff --tokens 50k --all .

# Print pipeline timing info
cxpak overview --tokens 50k --timing .

# Clean cache and output files
cxpak clean .

Daemon Mode

With the daemon feature flag, cxpak can run as a persistent server with a hot index that updates on file changes.

# Install with daemon support
cargo install cxpak --features daemon

# Watch for file changes and keep index hot
cxpak watch .

# Start HTTP server (default port 3000)
cxpak serve .
cxpak serve --port 8080 .

# Start as MCP server over stdio
cxpak serve --mcp .

HTTP API

When running cxpak serve, these endpoints are available:

MCP Server

When running cxpak serve --mcp, cxpak speaks Model Context Protocol over stdin/stdout. It exposes seven tools (all support a focus path prefix parameter):

What You Get

The overview command produces a structured briefing with these sections:

• Project Metadata — file counts, languages, estimated tokens
• Directory Tree — full file listing
• Module / Component Map — files with their public symbols
• Dependency Graph — import relationships between files
• Key Files — full content of README, config files, manifests
• Function / Type Signatures — every public symbol's signature
• Git Context — recent commits, file churn, contributors

Each section has a budget allocation. When content exceeds its budget, it's truncated with the most important items preserved first.

Context Quality

cxpak applies intelligent context management to maximize the usefulness of every token:

Progressive Degradation — When content exceeds the budget, symbols are progressively reduced through 5 detail levels (Full → Trimmed → Documented → Signature → Stub). High-relevance files keep full detail while low-relevance dependencies are summarized. Selected files never degrade below Documented; dependencies can be dropped entirely as a last resort.

Concept Priority — Symbols are ranked by type: functions/methods (1.0) > structs/classes (0.86) > API surface (0.71) > configuration (0.57) > documentation (0.43) > constants (0.29). This determines degradation order — functions survive longest.

Query Expansion — When using context_for_task, queries are expanded with ~30 core synonym mappings (e.g., "auth" → authentication, login, jwt, oauth) plus 8 domain-specific maps (Web, Database, Auth, Infra, Testing, API, Mobile, ML) activated automatically by detecting file patterns in the repo.

Context Annotations — Each packed file gets a language-aware comment header showing its relevance score, role (selected/dependency), signal breakdown, and detail level. The LLM knows exactly why each file was included and how much detail it's seeing.

Chunk Splitting — Symbols exceeding 4000 tokens are split into labeled chunks (e.g., handler [1/3]) that degrade independently. Each chunk carries the parent signature for context.

Pack Mode

When a repo exceeds the token budget, cxpak automatically switches to pack mode:

• The overview stays within budget (one file, fits in one LLM prompt)
• A .cxpak/ directory is created with full untruncated detail files
• Truncated sections in the overview get pointers to their detail files

repo/
  .cxpak/
    tree.md          # complete directory tree
    modules.md       # every file, every symbol
    dependencies.md  # full import graph
    signatures.md    # every public signature
    key-files.md     # full key file contents
    git.md           # full git history

Detail file extensions match --format: .md for markdown, .json for json, .xml for xml.

The overview tells the LLM what exists. The detail files let it drill in on demand. .cxpak/ is automatically added to .gitignore.

If the repo fits within budget, you get a single file with everything — no .cxpak/ directory needed.

Caching

cxpak caches parse results in .cxpak/cache/ to speed up re-runs. The cache is keyed on file modification time and size — when a file changes, it's automatically re-parsed.

To clear the cache and all output files:

cxpak clean .

Supported Languages (42)

Tier 1 — 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

Tier 2 — Structural extraction (selectors, headings, keys, blocks, targets, etc.): CSS, SCSS, Markdown, JSON, YAML, TOML, Dockerfile, HCL/Terraform, Protobuf, Svelte, Makefile, HTML, GraphQL, XML

Database DSLs: SQL, Prisma

Tree-sitter grammars are compiled in. All 42 languages are enabled by default. Language features can be toggled:

# Only Rust and Python support
cargo install cxpak --no-default-features --features lang-rust,lang-python

License

MIT

About

Built and maintained by Barnett Studios — building products, teams, and systems that last. Part-time technical leadership for startups and scale-ups.