Girder

# Girder

<!-- mcp-name: io.github.dhishwasher/girder -->

**Girder gives coding agents exactly the code they need, instead of whole
files.** It parses your repository into a living semantic graph — functions,
definitions, call edges — and answers questions against that graph: exact
function source, callers and callees, impact analysis, minimal test selection,
and verified graph-addressed edits. It is one static Rust binary that any agent
can drive over MCP, plus an optional native IDE.

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

**Languages:** Rust, Python, TypeScript, and Go. Rust and Python are the most
mature; TypeScript and Go are measured and gated, with their limits written
down ([TypeScript](./docs/typescript-support.md), [Go](./docs/go-support.md)).

**Tiers:** the free tier is permanent and needs no account — `get_source`,
`find_definition`, `search_code`, `ask_codebase`, and `review_changes` on a
single repository. The `orient` and `impacted_tests` tools need a
[paid license](#license). Keys are verified offline; the binary never phones
home.

On this repository's committed ten-node measurement, `girder context
--source-only` returned 8,765 bytes where full-file reads returned 408,137 — a
[97.85% reduction](./docs/context-vs-read-cost-observation.json). That counts
bytes, not tokens.

## Install

A prebuilt binary, no Rust toolchain needed:

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

Or from source:

```bash
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 — the default AI provider is an offline `MockProvider`. The GUI
and live AI providers are opt-in Cargo features not included in a plain
install; see [The GUI](#the-gui) and [Local-first AI](#local-first-ai) below.

### Windows installer

Each Windows release also includes `Girder-<version>-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.

## Search accuracy

Exact-symbol lookup is Girder's strongest search path. Natural-language intent
search is experimental: it reached **41.9% top-1** and **77.4% top-5** accuracy
on the committed 31-item corpus, below the precommitted 75% and 90% thresholds.
See the [observation](./docs/description-search-accuracy-observation.json) and
[policy](./docs/description-search-accuracy-policy.json).

## Use it from an AI coding agent

`girder mcp` serves the read-only graph commands over the
[Model Context Protocol](https://modelcontextprotocol.io), so an agent can ask
about your codebase instead of reading files into its context window.

Claude Code:

```bash
claude mcp add girder -- npx -y girder-mcp .
```

Any MCP client config:

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

With a binary already installed, `"command": "girder", "args": ["mcp", "."]`
skips npm entirely.

Seven tools, all read-only:

| Tool | What it answers |
|---|---|
| `get_source` | The source of specific functions, without the file around them. |
| `find_definition` | Where an exact identifier is declared. Not a substring search. |
| `search_code` | Which functions match a description, when you don't know the name. |
| `ask_codebase` | Callers, callees, and blast radius, by graph traversal. |
| `impacted_tests` | Only the tests that can reach what changed. |
| `review_changes` | What changed in the working tree, as semantics rather than text. |
| `orient` | Source, callers, callees, tests, and impact for one node, in one call. |

### What that saves, and what it doesn't

Two precommitted measurements, both counting **bytes of command output rather
than tokens** (no tokenizer was run):

- `get_source` against reading the whole file: **97.85% fewer bytes** across ten
  functions sampled by source-size decile, cheaper on all ten
  ([`docs/context-vs-read-cost.md`](./docs/context-vs-read-cost.md)).
- `find_definition` against `grep`: **97.98% fewer bytes** across ten
  identifiers ([`docs/names-cost.md`](./docs/names-cost.md)).

Both are single-repository measurements. The direction is structural — files
are much larger than the functions in them, and grep returns every mention
where `find_definition` returns only declarations — but the exact percentages
are not portable.

`impacted_tests` is **advisory**. It over-selects unrelated tests, and it
misses tests reached only through dynamic dispatch (measured: recall 0.000 on a
polymorphic-dispatch case, [`docs/core-representative-mutations.md`](./docs/core-representative-mutations.md)).
A full test run remains the authority before calling a change safe.

`orient` bundles what `get_source` + `ask_codebase` (callers, callees, and
impact) + `impacted_tests` otherwise answer across 5-6 separate calls into
one. On a 15-task corpus spanning ten pinned repositories, that one call used
**fewer aggregate bytes than the chain it replaces** (48,814 vs 101,302,
a 0.48 ratio) while cutting 78 round trips to 15 — one per task — and, after
two disclosed defects were fixed, **37 of 37 gated checks pass**. The first
run found `impacted_tests --quiet` silently dropping non-Rust/Python test
names (`orient`'s own test-coverage section did not share the bug, which is
how it was found); that filter is now removed. Its natural-language `intent`
input still inherits `search_code`'s accuracy — all three intent tasks in
this corpus resolved to the wrong node, unchanged and out of scope for this
fix — but `orient`'s confidence heuristic, which originally caught none of
the three, now flags all three `"confidence": "low"` with candidate scores
attached, at the cost of also flagging some correct resolutions when a
runner-up is close. See [`docs/orient-tool.md`](./docs/orient-tool.md) and
the committed [policy](./docs/orient-tool-policy.json) /
[original observation](./docs/orient-tool-observation.json) /
[post-fix observation](./docs/orient-tool-observation-post-fix.json).

The project root is fixed when the server starts, so no tool call can reach
another directory. `GIRDER_MCP_TIMEOUT_SECONDS` (default 120) bounds each
call; raise it for a very large repository.

Everything below assumes `girder` is on your `PATH`. Building from a source
checkout without installing works the same way with `cargo run -p aether-app --`
in place of `girder`.

## Quickstart

```bash
# Full end-to-end demo — no GPU, display, or API key required:
girder

# Run the test suite (graph, builder, AI router, agent swarm, debugger):
cargo test --workspace

# Optional: compile live providers and run the real debugpy adapter test:
cargo check -p aether-ai --features live-providers
python3 -m pip install debugpy
cargo test -p aether-dap --test debugpy -- --ignored
```

### Use it on a real project

Girder is also a CLI that operates on actual directories:

```bash
# Build the semantic graph from a project and save it as <dir>/project.aether:
girder analyze sample-project

# Inspect a saved graph and a node's impact set:
girder inspect sample-project/project.aether crate::lib::add

# Concept search: rank functions by relevance to a natural-language query:
girder search sample-project "sum numbers in a list"

# Graph-semantic rename — follows Calls edges (not text search) and rewrites
# only the real callers, then saves the updated graph:
girder refactor sample-project rename crate::lib::add plus

# Preview what the swarm would build — graph-aware Planner only, no code written:
girder swarm-plan sample-project "add user authentication"

# Dispatch the agent swarm on a project with a natural-language intent:
girder forge sample-project "add a subtract function"

# Author a single graph-addressed plan step via a wired-in model (the
# offline MockProvider by default) and execute it through the same
# verified plan executor as `plan run` below, repairing from check
# failures automatically. Never point this — or `plan run --authored` —
# at sample-project/: it is a pinned measurement fixture, not a demo
# target, and both refuse it outright (see "Demo target" below):
girder do demo-project "add an exclamation mark to the farewell"

# Emit graph context, a real Plan Format v2 authoring schema, and a plan
# skeleton as one JSON object — for pasting into any external chat model
# that isn't wired in as a provider. See "External authoring" below for
# the full loop from here to a verified, applied edit:
girder context demo-project --nodes crate::greeter::farewell "add an exclamation mark to the farewell" --json

# Validate/inspect/execute a plan file directly. `--authored` is for a plan
# an external model wrote by hand (see "External authoring" below); without
# it, `run` executes a plan exactly as authored (used internally by `do`):
girder plan validate my-plan.json
girder plan explain my-plan.json
girder plan run my-plan.json --dry

# Semantic code review vs HEAD (typed mutations, not text diffs):
girder review sample-project --since HEAD~1

# Minimal test selection: find every test reachable from changed functions:
girder test-impact sample-project --run

# Knowledg