prx (Praxis)

AI coding agents burn most of their context window re-discovering code they've already seen. prx fixes that at the source.

prx is a single Rust binary that replaces the Unix tools coding agents lean on most — grep, cat, find, sed, diff — with structured JSON output, hard token budgets, and an embedded semantic search model. One call returns a ranked, budgeted answer instead of a wall of text the agent has to read, parse, and re-read. No shell spawning, no post-hoc compression, no model server.

The problem

Every coding agent runs some version of this loop:

1. grep "authenticate" src/          → file paths, line numbers
2. cat src/auth/handler.ts           → entire file (thousands of tokens)
3. grep "authenticate" src/ -A 5     → same noise, wider context

Most of those tokens are waste: whole files read to use ten lines, the same file loaded twice in a session, test logs dumped in full to find one failure. The tools aren't broken — they were built for humans reading a terminal, not for an agent paying for every token and working inside a fixed context window. That mismatch is the tax prx removes.

The token-waste figures previously cited here are being re-sourced. Rather than quote a number we can't currently point you to a verifiable reference for, we let the per-command savings table below — measured on real sessions — speak for itself.

The fix

prx search "authenticate" src/

{
  "tokens": 487,
  "data": {
    "matches": [
      {
        "file": "src/auth/handler.ts",
        "line": 42,
        "context_name": "handleLogin",
        "snippet": "async handleLogin(req: Request)...",
        "relevance": 0.94
      }
    ],
    "total_matches": 23,
    "returned": 3,
    "budget_used": 487
  }
}

Ranked results, metadata included, under a token budget you control. The agent gets the answer, not the haystack.

What makes prx different

It replaces the tools, it doesn't wrap them. Compression tools shell out to grep/cat and squeeze the output afterward. prx does the search, reading, and diffing itself — no subprocess, no re-parsing, no lossy post-processing.

It covers the whole loop, not just search. Retrieval-only tools still leave your agent to read, edit, diff, and run tests with the old noisy tools. prx handles search, structured reads, safe edits, semantic diffs, and parsed test/build output behind one consistent JSON envelope.

It has no runtime dependencies. One static binary, ~49 MB, no Python, no package manager, no network at runtime. It runs in containers and sandboxes as-is.

The semantic model is built in. A 32M-parameter retrieval-optimized embedding model (potion-retrieval-32M, stored as float16) is compiled directly into the binary. Semantic search runs on CPU in milliseconds — no model server, no vector database, no setup step.

It's fast. Indexing runs on all CPU cores in parallel (~17x total speedup on 10 cores: v0.5.5: 7.6x parallel stages, v0.5.14: 2.2x parallel embeddings + hot-path optimizations). Embeddings are memory-mapped with zero-copy access — no heap allocation, no deserialization. A 50-query benchmark suite runs in 0.23 seconds.

Token savings

Measured across real agent sessions on production codebases. Run the numbers on your own repo with prx stats --compare and prx bench ..

Performance

Indexing: ~17x parallel speedup

prx index builds a persistent search index — BM25, semantic embeddings, import graph, and symbol definitions — in a single parallel pass. All five stages run on all available CPU cores via rayon (v0.5.5). v0.5.14 added parallel embedding computation via par_iter across chunks, O(n) top-k selection, precomputed newline offsets, HashSet-based BM25 df, and per-chunk word sets for symbol refs.

Measured on 10-core Apple Silicon with rayon parallelism (944% CPU utilization). On CI runners (4 cores), expect ~3-4x speedup over sequential. Incremental rebuilds skip unchanged files entirely.

Times above are from the v0.5.7 baseline. v0.5.14 added parallel embedding computation and hot-path optimizations, reducing the 11K-file benchmark from 55s to 24s (2.2x additional speedup).

find --tree: 47x faster at scale

prx find --tree on an 11K-file codebase dropped from 33s to 0.7s after replacing the O(n²) JSON tree builder with a native nested map that serializes once.

Search: zero-copy memory-mapped embeddings

Embedding vectors are memory-mapped directly from disk via memmap2 and cast to &[f32] with zero allocation using bytemuck. The OS page cache keeps the index warm across queries — no heap allocation, no deserialization, no repeated file reads.

On an 11K-file codebase with 54 MB of embeddings, this means:

• Zero bytes allocated for embedding data (OS manages the pages)
• Queries after the first hit warm cache — sub-millisecond embedding access
• Falls back to owned allocation automatically if mmap isn't available (network FS, etc.)

Benchmarking: 55x speedup with load-once

prx bench-ndcg measures search quality (NDCG@10) against labeled datasets. It loads the index once and runs all queries against cached data:

Use --plain for human-readable output in the terminal.

The commands agents actually orchestrate around

Most tools stop at "better grep." The two commands below are why prx is useful for agents working inside a tight context window — they answer questions that would otherwise take a dozen grep/cat calls to reconstruct.

prx context — understand a module in one call

prx context src/auth/

Returns a single structured package for a directory: summary stats, doc/README content, entrypoints, per-file skeletons (signatures without bodies), and the import edges connecting the files. Instead of the agent running find, then cat README, then outline on each file, then chasing imports by hand, it gets the whole mental model of a module in one budgeted response — ideal for the "load just enough to start a task" step in an agent loop.

prx impact — know what breaks before you touch it

prx impact src/auth.ts

Reverse-dependency analysis built on prx's import graph: it answers "what depends on this file?" so an agent (or a human) can scope a refactor before making it. Edges are extracted from the AST (see How search works); when an import name is ambiguous across many files, resolution falls back to a directory-proximity heuristic and returns the most likely candidates rather than guessing blindly. Treat its output as a high-quality map, not a formal proof of completeness.

All commands

17 commands total. Full reference with examples in the documentation site.

Quick start

# Search by meaning, not just text
prx search "authentication flow" src/

# Get a module's whole shape in one call
prx context src/auth/

# See what depends on a file before refactoring it
prx impact src/auth.ts

# File structure without the bodies (~10% of the tokens)
prx read src/auth.ts --skeleton

# Read just the function you need
prx read src/auth.ts --lines 42 --snap function

# Skip re-reading a file that hasn't changed
prx read src/auth.ts --if-changed a3f9b2c1

# Safe edit with a preview before applying
prx edit src/auth.ts --find "old_api()" --replace "new_api()"

# Run tests, get only failures and a summary
prx run cargo test

How search works

prx fuses three retrieval methods into one ranked result:

• Literal — regex matching at ripgrep speed.
• Semantic — the embedded potion-retrieval-32M Model2Vec model (PCA-reduced to 256 dims, float16); runs on CPU in milliseconds, no server.
• Structural — AST pattern matching via tree-sitter, e.g. fn $NAME($$$) { $$$ } to match all function definitions.

Results are combined with Reciprocal Rank Fusion and reranked through a multi-stage pipeline: definition boost, identifier-stem matching, file coherence, import-graph proximity (favoring files in the dependency neighborhood of strong hits), noise penalties, and saturation decay.

prx search "authentication flow" src/                  # semantic (auto-detected)
prx search --literal "authenticate(" src/              # exact match, ripgrep speed
prx search --structural 'fn $NAME($$$) { $$$ }' src/   # AST pattern matching

The import graph is extracted from the AST (tree-sitter) across 20 language families that have an import concept. Search quality is tracked with NDCG@10 on labeled datasets — see Search quality for the honest numbers and methodology.

prx run — structured command output

Test runners emit thousands of tokens an agent doesn't need:

running 164 tests
test test_one ... ok
test test_two ... ok
[... 162 more lines ...]
test result: ok. 164 passed; 0 failed

prx run parses that and returns only the signal:

{ "passed": 164, "failed": 0, "duration_ms": 2341, "failures": [] }

22 parsers cover Rust, Python, Go, JavaScript/TypeScript, Java, .NET, Docker, Terraform, kubectl, Maven, Gradle, npm, mypy, git, common coverage tools, and a generic fallback for unrecognized commands.

Agent integration

MCP server

{
  "mcpServers": {
    "prx": { "command": "prx", "args": ["mcp"] }
  }
}

Exposes prx over stdio to any MCP-compatible agent. (prx also works equally well as a plain CLI on PATH — see the tiers below.)

Config generation

prx init                      # detect frameworks, generate configs
prx init --agents-md          # append a usage snippet to AGENTS.md
prx init --agent claude-code  # generate a dedicated Claude Code sub-agent

Integration tiers

Skills guide (for AI agents)

prx ships with a machine-readable skill guide at skills/agents.md — a complete reference written for AI agents, not humans. It covers:

• When to use prx instead of grep, cat, find, sed (decision table)
• Core workflow — the 12-step sequence from existence check to test run
• Per-command examples with expected JSON output
• Measured token savings per command (99% on cache hits, 95% on test runs)
• Conditional reads, budgets, and search modes with concrete usage

Load it into your agent's context with prx init --agents-md, or read it directly. It's 210 lines — designed to fit in a single context load.

Reliability

If an internal operation fails, prx falls back to the equivalent Unix command and returns results in the same JSON envelope, flagged so the caller can tell a fallback occurred. Errors are logged to ~/.prx/errors.jsonl. The intent is that prx never hard-breaks an agent's workflow — but because a fallback silently trades semantic search for plain matching, agents that depend on retrieval quality should check the flag rather than assume every result is a full-quality prx result.

Install

# Homebrew (macOS / Linux)
brew install civitas-io/tap/prx

# Cargo (Rust developers)
cargo install prx

# Prebuilt binary (any platform)
curl -L https://github.com/civitas-io/prx/releases/latest/download/prx-aarch64-apple-darwin.tar.gz | tar xz
sudo mv prx /usr/local/bin/

Prebuilt binaries for all platforms on GitHub Releases:

The binary contains the embedded model — no downloads at runtime, works offline.

Build from source

git clone https://github.com/civitas-io/prx.git && cd prx
cargo build --release    # model downloaded automatically by build.rs

See the Contributing guide for the full developer setup.

Platform support

Single static binary. No runtime dependencies. No network required after build.

Current status

See the Roadmap for what's planned next.

Parsing = tree-sitter AST (chunking, --skeleton, --mode aggressive). Imports = dependency graph extraction. Outline = symbol table (prx outline). Snap = structural snapping (--snap function/class).

Search quality

NDCG@10 measured on 200 labeled queries across 8 public repositories (6 languages, 3 size tiers). All repos pinned by commit SHA. Ground truth in benchmarks/repos/. Methodology in docs/design/SEARCH-QUALITY.md.

Symbol search is consistently strong (avg 0.681) across all sizes. Semantic search degrades at scale — the 32M embedded model works best on codebases under 3K files. For larger repos, code-specific model tiers are planned (see Roadmap).

These are honest numbers on codebases we didn't write and don't tune for.

Contributing

See the Contributing guide for setup, workflow, and how to add commands, languages, and run parsers.

License

Apache 2.0

Part of the Civitas ecosystem — open infrastructure for AI agent tooling.