Context your agent can explain.
repoctx indexes your repository and hands an AI coding agent exactly the files that matter — with a machine-readable reason for every one, and a hard token budget per answer.
Built for agents that have to be trusted.
Three constraints, enforced — not aspirations. They are what make the output safe to feed a model and safe to run on a private codebase.
Nothing leaves the machine
No network calls, no telemetry, no embedding or LLM requests — ever. The ban is verified at compile time and re-checked in CI with networking switched off.
A reason for every hit
Each result carries machine-readable reasons — fts, symbol:loginUser, imported-by:…, test-of:… — so an agent (and you) can see why a file was chosen.
Byte-identical output
The same index and the same query always produce the same bytes. Stable sort, no timestamps in results, no randomness. Diff-friendly and cache-friendly.
Four ways in.
Simplest route: npm install — it ships a self-contained binary, so no .NET runtime is involved. Already on .NET 10? Install the global tool. Prefer no package manager at all? Take a binary from Releases. Tool installs blocked by policy? Add it as a plain NuGet package.
npm new
No .NET runtime required — the package ships a self-contained binary. The natural route for a TypeScript / JavaScript repository. The package is repocontext-tool; the command it installs is repoctx.
# globally — puts repoctx on your PATH npm install -g repocontext-tool repoctx --version # or pinned per repository, so the whole team gets the same version npm install --save-dev repocontext-tool npx repoctx --version
Prebuilt for Linux x64/arm64, macOS arm64/x64 and Windows x64/arm64. The platform payloads are optional dependencies, so npm downloads only the one matching your machine. Alpine and other musl-based distributions are not covered by the prebuilt binaries — use the .NET tool there.
.NET global tool
Needs the .NET 10 runtime. Puts repoctx on your PATH.
# from NuGet.org dotnet tool install --global RepoContext.Tool repoctx --version
Self-contained binary
No runtime. From GitHub Releases: linux-x64, win-x64, osx-arm64.
# download for your platform, then tar -xzf repoctx-linux-x64.tar.gz ./repoctx --version
Plain NuGet PackageReference
dotnet tool install blocked by company policy? RepoContext.MSBuild delivers the same CLI through the NuGet restore your build already runs — a development-only dependency, nothing ships with your app.
# in exactly one project of the repository dotnet add src/YourProject package RepoContext.MSBuild # sets up init, index, local CLI payload, wrappers, and portable MCP config dotnet build ./.repoctx/bin/repoctx context "change the login logic"
Index once, then ask.
A genuine three-step flow. After the first build, indexing is incremental — it diffs by content hash and re-reads only what changed.
Set up the repo
repoctx init writes .repoctx/ and a config, and can add usage notes to your CLAUDE.md / AGENTS.md.
Build the index
repoctx index scans the tree into a local SQLite store — files, symbols and the import/dependent graph.
Ask for what matters
repoctx context "add logout" returns a ranked, explained, budgeted bundle — ready to hand to an agent.
Twelve commands, one contract.
Every command speaks --format text, json or md. The JSON is stable, snake_case and always carries schema_version.
| Command | What it does | Key options |
|---|---|---|
init | Create .repoctx/ and config; optionally wire up agent instructions. | --agents |
index | Build or incrementally update the index (hash diff). | --full |
search | BM25 full-text search over content and symbols. | --symbols · --top |
related | A file's imports, dependents and linked tests. | --format |
context | Ranked, explained bundle under exact response and read budgets. | --response-budget-tokens · --detail |
outline | A compact symbol skeleton before a full-file read. | --format |
changed | Working-tree changes, impacted files, and optional delta hunks. | --patch |
architecture | LOC tree, language mix, centrality, entrypoints. | --format |
prime | A cache-stable repository primer for unfamiliar work. | --files · --format |
memory | Store and recall short agent-authored notes, decisions, and constraints. | add · search · rm |
stats | Local token-savings and optional cost dashboard. | --format · --open |
mcp | Serve the same deterministic tools over stdio. | — |
Or skip the shell entirely.
GitHub Copilot, Claude Code, Cursor — anything that speaks MCP can call RepoContext directly. repoctx mcp runs a local, non-destructive server over stdio and exposes seven compact tools. Query calls may append aggregate counts to the local usage ledger.
- repoctx.search — full-text and symbol search
- repoctx.get_context — the ranked, budgeted bundle
- repoctx.get_related_files — imports, dependents, tests
- repoctx.get_outline — compact symbol skeleton
- repoctx.get_changes — changes, impact, delta hunks
- repoctx.memory_add — retain a durable finding
- repoctx.memory_search — recall local knowledge
Register it
# Claude Code — run inside your repo claude mcp add repoctx -- repoctx mcp # GitHub Copilot (VS Code) — .vscode/mcp.json { "servers": { "repoctx": { "type": "stdio", "command": "repoctx", "args": ["mcp"] } } }