Girder

Girder

Girder saves AI coding-agent context by giving the agent exactly the code it needs instead of whole files. It builds a local semantic graph of your repository so Claude Code, Codex, Cursor, and other agents can retrieve exact functions, definitions, callers, callees, and task context without filling their context window with irrelevant code. It runs as one static binary, with no account and no cloud dependency.

npx -y girder-mcp setup

That one command detects and configures Claude Code, Codex, and Cursor.

Latest stable release: v0.4.0 (Apache-2.0). Contributions: see CONTRIBUTING.md.

Measured output bytes, not tokens (no tokenizer was run):

• CLI stdout of girder context ... --json --source-only (MCP get_source) vs reading the whole file: 97.85% fewer bytes, across ten functions sampled by source-size decile (method and honest limits).
• CLI stdout of girder names ... --json (MCP find_definition) vs plain grep: 97.98% fewer bytes, across ten identifiers (method).
• orient (one bundled call: source, callers, callees, tests, and impact for one node) vs the equivalent chain of separate calls: 48,814 bytes vs 101,302, using 15 calls vs 78, on a 15-task corpus spanning ten pinned repositories (method).

The two percentages measure CLI output; MCP transport overhead was not measured.

Support Girder

Girder is independently developed to help coding agents consume less code: precise semantic context instead of whole-file reads and repeated repository greps. Sponsorship helps fund context efficiency, semantic graph correctness, agent integrations, reproducible benchmarks, and maintenance. Girder publishes its measurements, including failures and limitations. If Girder saves you context, compute, or development time, sponsor its continued development.

Funding goal: $1,000/month to fund ongoing maintenance, releases, benchmarks, and continued context-efficiency work on Girder. See what sponsorship supports.

Real, captured output (see docs/observations/release-prep/ for exact provenance):

$ girder context demo-project --nodes crate::greeter::shout_greeting --json --source-only

{ "nodes": [{ "language": "python", "path": "crate::greeter::shout_greeting", "source": "def shout_greeting(name):\n return format_greeting(name).upper()" }] }

One function's exact source returned, not the whole file around it — that is the core of what Girder gives an agent's context window.

Languages, stated plainly, not as parity: Rust and Python each have a completed 100-call-site audit across three pinned repositories, with no unsound answers in that sample. Each produced 1 Must and 99 Unknown answers; the precision evidence is limited (measurement). TypeScript is measured and gated but explicitly in progress — it still has a separate, disclosed node-identity collision mechanism (duplicate it()/describe() description strings can silently overwrite each other's graph node; see docs/observations/stage3-typescript-audit/). Go's Stage 3 audit is not complete. See docs/typescript-support.md and docs/go-support.md for the exact, measured limits of each.

Also included, as an additional capability built on the same graph — conservative change-impact and test selection: test-impact names the tests a change may affect, from the same semantic graph, erring toward including a test it can't rule out rather than silently dropping it. Real captured output:

$ girder test-impact . --quiet

test-impact: 82 unresolved call-evidence boundaries found; this selection is the conservative must∪may∪unknown union — pass --classified to see why each test is included test_farewell test_format_greeting test_shout_greeting_delegates_to_format_greeting

See Status for exactly what that selection does and doesn't prove.

Pricing and license: Girder is free and open source under the Apache License 2.0. There is no current paid tier, and no license key or account is required — see License.

Evidence, for a skeptical reader: docs/evidence-index.md points at every committed audit, measurement, and adversarial finding behind the claims above — including the bugs found and fixed along the way, not just a final number.

Install

A prebuilt binary, no Rust toolchain needed:

curl -fsSL https://raw.githubusercontent.com/dhishwasher/Girder/main/install.sh | sh

girder --version

Or from source:

cargo install --path crates/aether-app

girder --help

This builds the default headless profile and installs the girder binary to ~/.cargo/bin (make sure it's on your PATH). No GPU, display, network, or API key is required.

Windows installer

Each Windows release also includes Girder- -setup.exe. It installs for the current user under %LOCALAPPDATA%\Programs\Girder, adds Girder to the user PATH, creates a Start Menu shortcut, and does not request administrator access. Open a new terminal after installation so it sees the updated PATH. The installer includes the desktop GUI, and its Start Menu shortcut opens it. The archives and npm installation continue to provide the headless CLI.

The installer is not code-signed yet, so Windows SmartScreen will warn on first run. After downloading the installer from the GitHub release, double-click it, choose More info on the “Windows protected your PC” dialog, verify that the app is Girder and the publisher is shown as unknown, then choose Run anyway. If those details do not match, cancel instead.

Competitor benchmark

On the 20-task modest cross-language base set, Girder passed 5/20 versus Ripwire's 7/20 — a loss. But across the 60 attempts where both products passed, Girder returned 35,764 bytes versus Ripwire's 158,514 — 77.4% fewer — at identical call counts (120 each). GitNexus could not be scored: its install exceeded the frozen 1 GiB ceiling on this measurement machine, which is a fact about install footprint on a constrained host, not a claim about its quality.

No product in this benchmark reached full correctness, and the benchmark does not establish an overall best product. See the full report for methodology, per-language results, and everything the numbers above don't establish.

Use it from an AI coding agent

girder mcp serves the read-only graph commands over the Model Context Protocol, so an agent can ask about your codebase instead of reading files into its context window.

Preview the changes, then configure detected agents:

npx -y girder-mcp setup --dry-run

npx -y girder-mcp setup

setup detects Claude Code (~/.claude or an existing in-home project .mcp.json), Codex (~/.codex or an in-home CODEX_HOME), and Cursor (~/.cursor). It merges the girder MCP entry into each detected agent's documented config and installs nested PreToolUse and PostToolUse hooks for Claude Code and Codex. Pre hooks cover structured Read, read_file, and mcp__.*__read_file events; post hooks cover Claude's Edit|Write|NotebookEdit and Codex's apply_patch|Edit|Write edit names. Shell commands are intentionally not parsed. Cursor documents hooks, but no pre-read hook can add advisory context without blocking (preToolUse and beforeReadFile only allow, deny, or rewrite input; only postToolUse and sessionStart return additional_context, after the fact), so setup registers MCP and the project rule for Cursor but no hook. A generic MCP client has no universal config path and is reported as not detected. Setup never writes outside your home directory. Existing foreign girder entries remain untouched, including with --force; girder setup --uninstall removes only setup-owned changes.

The orient-first instruction. Besides MCP, setup installs one short shared instruction through each client's own mechanism, so the agent calls Girder's orient before broad reads or grep, says so when Girder is unsure, and falls back to reading source rather than guessing:

The block is marked and recorded in girder-setup-state.json: re-running setup changes nothing, --uninstall restores the file exactly, an edited block is left alone, and --no-instructions skips this step. The formats above were checked against each client's own documentation on 2026-10-06; sources and quotes are in docs/observations/stage4-clients/.

Which form installs what. girder setup from a built or installed binary installs MCP, hooks, and the instruction, and writes an MCP entry that launches that installed binary ( mcp .), so clients run local Girder with no package download at launch. npx -y girder-mcp setup runs the *published* package's setup, which installs the instruction only once a release that includes it ships; when setup runs from npx's transient cache there is no stable binary path, so the entry falls back to the npx -y girder-mcp . launcher form and setup says so (install Girder, then run girder setup, to switch to the local binary).

The packaged hook launcher forwards each event to the pinned native girder hook executable and fails open on errors. Only standalone PreToolUse JSON is forwarded on stdout; post-edit native diagnostics pass through stderr, and MCP continues to use JSON-RPC on its own stdout. The read advisory only gives guidance when project.aether already exists. The post-edit advisory uses that saved graph snapshot, does not scan or rebuild the project, and describes the last analyzed version of changed files. See the setup and client path guide for config paths, ownership, and the manual JSON fallback.

For clients setup cannot detect, or to do it by hand, add the entry to the client's documented MCP config. Placement per client:

JSON form:

{

"mcpServers": { "girder": { "command": "npx", "args": ["-y", "girder-mcp", "."] } } }

Codex uses a TOML table instead:

[mcp_servers.girder]

command = "npx" args = ["-y",