Quickstart

1. Install

curl -fsSL https://greppy.xyz/install.sh | sh

In a terminal, the installer opens a small menu. When you choose to install, it first shows the coding agents it can set up, with the ones it found already ticked, and asks which of them should use greppy (see step 3). It then checks your platform (macOS on Apple Silicon or Linux x86_64; on Linux it warns if the NVIDIA driver is missing), downloads the release from GitHub, verifies its SHA-256, unpacks it under ~/.local/share/greppy/versions/ and links ~/.local/bin/greppy to it. You don't need sudo for this.

You append options after sh -s --, for example for a specific version:

curl -fsSL https://greppy.xyz/install.sh | sh -s -- --version v0.3.2

Every option, the exact files the installer touches and the three uninstall stages are in the installer reference.

Prefer to do it by hand? Download the package for your platform (.pkg for macOS, .deb or .rpm for Linux) and SHA256SUMS from the releases page, check it with shasum -a 256 --ignore-missing -c SHA256SUMS and install it with your platform's package manager (installer -pkg, dpkg -i, rpm -U). Install the binary as greppy, never as grep. You check signatures and provenance as described in Security and verification.

Build from source

To build, you need Rust ≥ 1.95, a C toolchain, jq and curl. fetch_model_assets.sh downloads four model files totaling 814 MB:

git clone https://github.com/metric-space-ai/greppy && cd greppy
git checkout v0.4.1
./tools/fetch_model_assets.sh
cargo build --locked --release --bin greppy
install -m 0755 target/release/greppy "$HOME/.local/bin/greppy"

The build enables your platform's GPU backend automatically: Metal on Apple Silicon, CUDA on Linux x86_64 (with nvcc). cargo build stops if a model file is missing or its SHA-256 does not match. fetch_model_assets.sh is idempotent: it checks existing files and downloads again as soon as a checksum differs.

2. Run the first query

Any repository works. The output here comes from serde 1.0.229:

git clone --branch v1.0.229 https://github.com/serde-rs/serde && cd serde
greppy --version
greppy index .                       # build the graph and embeddings for this repository
greppy doctor --root . --json        # check the index and inference backend end to end
greppy who-calls visit_content_map   # your first graph query

greppy index immediately reports its first phase, its PID and the status command on stderr, for example (phase=preparing_base, pid=3293); progress: `greppy index status --json`. At the end it prints one summary for the graph and one for the embeddings. greppy doctor --root . --json returns the full health report (443 lines of JSON for serde) and exits 0 when the index and the backend are ready.

$ greppy --version
greppy 0.4.1
$ greppy index .
…
indexed 219 files (120 unsupported, 0 unreadable, 0 oversize, 0 file-limit, 0 time-budget); 4571 nodes extracted; generation 1 (project: serde)
embedded 2443 code spans (0 local-store reused, 2443 global-cache hits, 0 inference misses, 4573 considered, 2150 non-definition skipped, 0 missing-file, 0 invalid-span, 0 oversize, 0 failed, 0 stale pruned)
$ greppy who-calls visit_content_map
serde/src/private/de.rs:1152  ContentDeserializer::deserialize_any
serde/src/private/de.rs:1399  ContentDeserializer::deserialize_map
serde/src/private/de.rs:1415  ContentDeserializer::deserialize_struct

The second line of greppy index shows where the embeddings come from: from this repository's store (local-store reused), from the user-wide cache (global-cache hits) or freshly computed (inference misses). serde had been embedded on this machine before, so all 2,443 came from the cache. The graph is built once per repository and reused across sessions.

You can also skip greppy index: a first graph query such as who-calls builds the graph itself and answers as soon as it is published. The first search takes care of the embeddings for semantic search: it builds the missing embeddings and answers once they are complete, without partial hits.

Since 0.4.1, a first graph query that has to wait for the build reports its phases on stderr, for example who-calls — writing_graph: 154/219 files; phase ETA about 40s. If indexing cannot start, the query exits with the temporary code 75 and names the condition for the next attempt.

Check readiness in scripts

Scripts that need semantic search run greppy index . and then check:

greppy index status --json | jq '{status, healthy, embedding_complete, fresh}'

{
  "status": "ok",
  "healthy": true,
  "embedding_complete": true,
  "fresh": true
}

Start semantic work as soon as the command exits 0 and reports "healthy": true and "embedding_complete": true. The command never blocks, and the exit code tells you what to do:

3. Connect your agent

The installer does this for you. It saves the prompt that belongs to your installed version as ~/.greppy/AGENTS.md and adds it to the global instructions of every coding agent you tick:

Each entry sits between the markers <!-- greppy:begin … --> and <!-- greppy:end -->. The original file is kept as *.greppy-backup, and a second installer run replaces the block instead of appending another one. To change later which agents use greppy, run the installer and choose Set up coding agents only; --uninstall removes every block.

For any other agent, copy ~/.greppy/AGENTS.md into your project directory as AGENTS.md. That is the whole integration: no MCP server, no per-agent configuration, no API keys. The graph builds itself on the first query. Agent setup explains what the prompt tells your agent.

Next steps

• Navigate the graph and Search describe the commands your agent uses most.
• Edit transactionally shows how you change code on the same evidence.
• Run builds and tests keeps build logs out of your agent's context.
• If something doesn't work, run greppy doctor --json and attach its output (with private paths redacted) to a GitHub issue, together with greppy --version, your operating system, CPU, GPU and driver version.