Pasr

Provenance-Aware Span Recall — local, token-budgeted, source-traceable context for coding agents.

The problem

Agents need enough source to answer correctly, while every retrieved observation can be carried into later model requests. Native grep and bounded file reads already provide useful source and provenance. PASR must justify its additional retrieval, selection, and tool-catalog complexity against that baseline—not against dumping the entire repository.

What PASR does

Budgeted

Live select_context budgets the returned context, including labels, headings, separators, and redaction—not the MCP JSON envelope or cumulative conversation. Whole computed spans are admitted only when that final representation fits; spans are not necessarily complete functions. Lossless selection uses the exact rendered cost, and optional headers cannot displace source that already fits.

Traceable

Selection receipts record each span's file:line, token count, retrieval signals, and why it was kept or dropped. Receipts are saved under .pasr/receipts; persistence is best-effort, and the response reports whether a receipt was written. They cover PASR-delivered context, not everything an agent reads or does.

Honest

Receipts expose heuristic query classifications, keyword coverage, and routing advice. These are not calibrated correctness probabilities or proof that all necessary evidence was retrieved. Advice must not replace checking the source.

Local by default

No daemon, vector database, or manual index setup is required. Offline selection needs installed dependencies and cached tokenizer data; optional model weights are separate. The client can still forward returned source to a cloud model. Default redaction is a no-op, not automatic secret detection.

Install

Install version 0.4.0 from [PyPI](https://pypi.org/project/pasr-mcp/0.4.0/). Install uv and make uvx available on your PATH; use Python 3.10+ or allow uv to provision it. No PASR checkout is required. Replace /absolute/path/to/project with the repository to inspect, then choose the command for your client:

claude mcp add pasr -- uvx --from pasr-mcp==0.4.0 pasr-mcp --workspace /absolute/path/to/project

codex mcp add pasr -- uvx --from pasr-mcp==0.4.0 pasr-mcp --workspace /absolute/path/to/project

Alternatively, merge this MCP configuration into your client's config. Update any existing pasr entry rather than registering the same server twice:

{ "mcpServers": { "pasr": { "command": "uvx", "args": ["--from", "pasr-mcp==0.4.0", "pasr-mcp", "--workspace", "/absolute/path/to/project"] } } }

For the separate v0.4.0 GitHub release wheel instead, use:

python -m pip install https://github.com/Apheironn/pasr/releases/download/v0.4.0/pasr_mcp-0.4.0-py3-none-any.whl

After installing that wheel, configure your client to run the installed pasr-mcp executable with --workspace /absolute/path/to/project instead of the uvx launch.

Developers only — source checkout: replace pasr-mcp==0.4.0 after --from in your existing registration with /absolute/path/to/pasr. For example:

uvx --from /absolute/path/to/pasr pasr-mcp --workspace /absolute/path/to/project

Use this instead of the published-package launch, not a second pasr registration. It runs that checkout, which may differ from the release; editing it does not update an existing global installation.

After installation, PASR's tools are available alongside the agent's native tools. The model decides when to search, select context, or read files directly. Smaller selected context does not by itself establish cheaper or more accurate answers.

Per-client setup notes: Claude Code · Cursor · Windsurf.

Without an agent: run uvx --from pasr-mcp==0.4.0 pasr explain " " from the project to inspect to print a selection receipt. Five historical CLI examples against pinned public repos are in examples/.

0.4.0 diagnostics

Version 0.4.0 includes pasr doctor. To diagnose this package installation, use the same version as your registered server:

uvx --from pasr-mcp==0.4.0 pasr --workspace /absolute/path/to/project doctor --json --timeout 30

Omit --json for a readable report. Exit codes are 0 for success, 1 for a failed diagnostic, and 2 for invalid options. The protocol deadline must be a finite positive number; subprocess shutdown can take a few additional seconds. The command checks that the workspace is a directory, then starts a real MCP server in a disposable fixture to inspect its catalog and select known source. It never scans or writes the project or its .pasr/ state. Reports contain runtime versions and check outcomes, not source, absolute paths, environment values or raw exception messages. It makes no paid model call or automatic report upload; initial setup/tokenizer encoding downloads can require network access. A pass does not verify your client's registration, approval settings or answers.

Optional public reports: installation trouble or real-task feedback. Review before posting; do not include secrets, private source or raw transcripts. Doctor is optional; you can report without running it.

Verified Codex onboarding, with explicit limits

On 2026-10-04, Codex CLI 0.160.0 + GPT-6 Luna used an installed 0.3.0 wheel to answer a source-reading question in an isolated workspace containing one unmodified PASR source file. The final recipe used three model-selected PASR calls, 364 selected-context tokens, and source-checked relative line citations. This is a controlled integration smoke, not independent user adoption or evidence of lower total model cost. Setup failures and earlier model turns are retained in the integration record.

For interactive use, approve the known PASR server when the client prompts. In unattended Codex runs, approval_policy = "never" does not grant MCP tool permission: the initial model call was blocked. Only for a reviewed, trusted server/workspace, set default_tools_approval_mode = "approve" inside the existing [mcp_servers.pasr] table. This is explicit preapproval of that server, not a reason to disable global safeguards. PASR may write receipts/cache in its workspace; the host's read-only shell sandbox does not sandbox the MCP process.

Ask for workspace-relative `file:line` ranges copied from PASR output, as plain text rather than invented absolute links. The earlier answer added a nonexistent /workspace prefix; the revised citation instruction produced matching references. When scripting codex exec, close unused stdin; otherwise it can wait for additional prompt input. None of these observations proves another client/model will behave identically.

To repeat this controlled task, build a wheel and run the checked-in driver from the checkout root. Install Codex first and supply OPENAI_API_KEY through your normal secret mechanism; this makes paid API requests.

python -m build --outdir dist/demo

python scripts/demo_client.py --codex /absolute/path/to/codex --wheel dist/demo/pasr_mcp-0.4.0-py3-none-any.whl --output eval/agent_bench/results/client-demo

On Windows, pass the actual codex.exe, not its shell wrapper. The output directory must be new. The driver installs the wheel into a temporary environment, copies only src/pasr/source_text.py, isolates Codex configuration, and retains the answer, tool calls, usage, warnings and failures before cleanup. It does not grade answer correctness, and only the exact supplied API key is redacted: inspect evidence before sharing. The maintained driver was also exercised with a real model; see its repeat record.

In one call

One localized question — *"how are redirects resolved and followed"* — against psf/requests (verbatim transcript):

This is a source-selection illustration, not a native grep/read baseline, an answer-quality result, or the current MCP default cap of 1,500 context tokens.

Evidence and alternatives

Native grep and bounded reads are useful defaults. PASR adds explicit context budgets and selection receipts; that does not establish better answers or a lower total model bill. Aider RepoMap provides structural navigation, and Repomix packages source for a model. These are overlapping workflows, not interchangeable products.

Fresh workflow study (2026-10-05): no pipeline promotion. All 10 PASR methods were measured in 420 local calls. The answering study retained 664 trajectories, including a 400-attempt, 40-question comparison with actual Repomix and Serena components; actual Aider RepoMap also ran in development.

The selected prompt policy used 18.26% more cumulative provider tokens than unchanged split-4 on Luna (paired 95% ratio interval 1.04594–1.35231). Full rubric/source support rose from 3/4