context-kit

context-kit is a PR context compiler for AI coding agents.

It is not a reviewer and it does not post comments. It reads a pull request through a provider, builds bounded context, and exposes the same read-only operations through the SDK, CLI, and MCP server.

Quickstart

pnpm install
pnpm run build
pnpm run smoke
pnpm run bench:cores
pnpm run bench:tiberriver-proxy

Run against the synthetic fixture:

pnpm exec pr-context-kit overview --fixture examples/fixtures/synthetic-auth-pr
pnpm exec pr-context-kit search --fixture examples/fixtures/synthetic-auth-pr --query SessionService
pnpm exec pr-context-kit render --fixture examples/fixtures/synthetic-auth-pr --budget standard --format md
pnpm exec pr-context-kit compare --fixture examples/fixtures/synthetic-auth-pr

Mine a public GitHub fixture for optional benchmark work:

pnpm run mine:github-fixture -- --owner owner --repo repo --pr 123 --out examples/fixtures/public-github/owner-repo-pr-123

Dynamic workflows

pr-context-kit is designed for dynamic workflows:

1. the host makes one bounded compile call up front
2. the agent starts from that structured context
3. follow-up reads use the same core only when needed
4. write-capable review actions stay on a separate path
5. rollout can fail open to the old read path while evidence is gathered

The intended steady-state is not "proxy everything through MCP." The intended steady-state is that pr-context-kit becomes the read-context brain, while the host keeps orchestration, retries, queueing, timeouts, and write operations.

CLI

pr-context-kit overview
pr-context-kit changed --format json|md
pr-context-kit symbols [--path src/foo.ts]
pr-context-kit list [--version head|base] [--glob "src/**/*.ts"]
pr-context-kit read --path src/foo.ts [--version head|base]
pr-context-kit around --path src/foo.ts --line 42 [--radius 40]
pr-context-kit search --query "AuthService" [--mode text|symbol|hybrid] [--limit 20]
pr-context-kit guidance
pr-context-kit comments
pr-context-kit checks --explicit
pr-context-kit blast-radius [--limit 20]
pr-context-kit render --budget tight|standard|deep --format json|md
pr-context-kit compare

Checks are explicit only. overview and render do not fetch checks by default.

Optional metadata-only CLI run telemetry is enabled with environment variables:

PR_CONTEXT_KIT_RUN_ID=review-pr-123 \
PR_CONTEXT_KIT_RUN_LOG_FILE=artifacts/pr-context-kit-run.jsonl \
pr-context-kit search --provider azdo --repo <repository-id> --pr <pull-request-id> --query "AuthService"

The command output is unchanged. Each CLI invocation appends one JSONL event with command name, input shape, provider metrics, output byte/token estimates, and status. It does not copy query values, file paths, or file contents into the log.

SDK

import { FixtureContextProvider, createPrContext, loadFixtureDirectory } from "pr-context-kit";

const fixture = await loadFixtureDirectory("examples/fixtures/synthetic-auth-pr");
const provider = await FixtureContextProvider.fromDirectory("examples/fixtures/synthetic-auth-pr");
const ctx = await createPrContext({ provider, prRef: fixture.prRef });

await ctx.getOverview();
await ctx.getChangedSymbols();
await ctx.searchCode({ query: "SessionService", mode: "hybrid" });
await ctx.renderContext({ budget: "standard", format: "markdown" });

Providers

Implemented provider surfaces:

• FixtureContextProvider
• InMemoryContextProvider
• FakeAzdoContextProvider
• GitHubRemoteProvider
• AzdoRestProvider for Azure DevOps Services cloud and Azure DevOps Server/on-prem REST

Remote providers are no-clone adapters. They fetch files through HTTP APIs and expose metrics. The AzDO adapter supports trusted Azure DevOps Services cloud and Azure DevOps Server/on-prem collection URLs. Live smoke runs are optional and require explicit safe configuration.

Optional live smoke commands:

pnpm run smoke:github
pnpm run smoke:azdo-server
pnpm run bench:github-provider

smoke:github uses GITHUB_SMOKE_REPO=owner/name and GITHUB_SMOKE_PR. bench:github-provider uses GITHUB_BENCH_REPO=owner/name and GITHUB_BENCH_PR, then writes docs/benchmarks/github-provider-benchmark.json. smoke:azdo-server uses AZDO_COLLECTION_URL, AZDO_PROJECT, AZDO_REPOSITORY_ID, AZDO_PR, and AZDO_PAT. It also accepts Tiberriver-compatible aliases: AZURE_DEVOPS_ORG_URL, AZURE_DEVOPS_DEFAULT_PROJECT, AZURE_DEVOPS_PAT, and AZURE_DEVOPS_AUTH_METHOD=pat. Set AZDO_API_VERSION or AZURE_DEVOPS_API_VERSION when a Server/on-prem target needs a REST version other than the default 7.1. The Azure DevOps smoke supports trusted Services cloud and Server/on-prem collection URLs.

For Azure DevOps CLI/MCP use, keep the collection URL and project in trusted process configuration. CLI flags for those values are only assertions and must match the environment. Prefer AZDO_* names for new installs; use the AZURE_DEVOPS_* aliases when integrating with an existing Tiberriver MCP environment.

When Codex or another OpenAI-function-calling client launches the MCP server, do not rely on inherited shell credentials. Codex starts MCP children with a scrubbed environment, so set the Azure DevOps values in that client's MCP server env block. The AzDO provider requires AZURE_DEVOPS_ORG_URL (or AZDO_COLLECTION_URL), AZURE_DEVOPS_DEFAULT_PROJECT (or AZDO_PROJECT), AZURE_DEVOPS_PAT (or AZDO_PAT), and AZURE_DEVOPS_AUTH_METHOD=pat.

The MCP server emits OpenAI-compatible strict object schemas: no top-level unions, no extra properties, and nullable optional fields with provider-specific validation enforced by handlers.

Tiberriver MCP proxy bridge

For an environment that already uses Tiberriver256/mcp-server-azure-devops, pr-context-kit also ships a proxy binary:

TIBERRIVER_MCP_COMMAND=pnpm \
TIBERRIVER_MCP_ARGS="dlx @tiberriver256/mcp-server-azure-devops" \
pr-context-kit-tiberriver-proxy

The proxy speaks MCP over stdio, launches the Tiberriver MCP upstream, filters retrieval tools, blocks mutation tools, requires explicit: true for checks, redacts sensitive fields, truncates large payloads, and returns raw-vs-optimized token metrics.

Use this when an existing Tiberriver MCP deployment already works and you need a temporary read-only bridge for validation, interoperability, or benchmark capture. Keep comment posting, PR updates, work-item writes, branch/commit operations, and pipeline triggers outside pr-context-kit.

Preferred production posture:

• pr-context-kit owns bounded read-context compilation
• the host owns compile timing and follow-up orchestration
• Tiberriver remains the write-capable path and rollback fallback
• the proxy stays as a bridge, not the primary read path

Benchmark the synthetic mixed-language proxy contract:

pnpm run bench:tiberriver-proxy

The public artifact is generated under docs/public/benchmarks/. It is an engineering note, not proof of private production behavior.

Symbol graph (opt-in)

Set KIT_GRAPH=1 to enable the local SQLite symbol graph at .kit/graph.db.

When a pnpm consumer enables graph mode from the packaged dependency, allow the optional native build for better-sqlite3 in that consumer workspace, for example with pnpm.onlyBuiltDependencies: ["better-sqlite3"]. Without the optional native binding, non-graph kit features still work, but graph initialization will fail clearly.

The graph is built incrementally: symbols are upserted on every PR compile (Seam A — changed symbols; Seam B — full repo index) and on every Read/Grep call via the Claude Code PostToolUse hook in .claude/hooks-graph/post-read.mjs.

To rebuild the full self-graph from source:

KIT_GRAPH=1 node scripts/export-self-graph.mjs

MCP tools kit_node, kit_neighbors, and kit_expand query the graph. See AGENTS.md for the graph-first retrieval contract and node id format.

The committed export at artifacts/kit-self-graph.jsonl is the deterministic team source of truth (sorted by id, signatures only — no body text).

Gates

pnpm run check
pnpm run build
pnpm test
pnpm run smoke
pnpm run smoke:github
pnpm run smoke:azdo-server
pnpm run bench:cores
pnpm run bench:github-provider
pnpm run bench:tiberriver-proxy
pnpm run test:fixtures
pnpm run test:mcp
pnpm run test:tiberriver-proxy
pnpm run test:providers
pnpm run test:benchmarks
pnpm run docs:public
pnpm run scan:secrets
pnpm run scan:ip
pnpm run scan:package
pnpm run audit:goal
pnpm run report:final