Getting started

On this page

Install

One line (Linux / macOS / Git Bash on Windows):

curl -fsSL https://raw.githubusercontent.com/KhaledSMQ/greplm/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/KhaledSMQ/greplm/main/install.ps1 | iex

With Rust installed:

cargo install --locked --git https://github.com/KhaledSMQ/greplm greplm-cli greplm-mcp

This installs greplm and greplm-mcp into ~/.cargo/bin (or ~/.local/bin). Prebuilt binaries are also published on GitHub Releases.

Quick start

First time in a project — one command sets up the index, warm daemon, and agent files:

cd your-project
greplm setup

Then connect your AI editor:

greplm mcp config    # copy the JSON into Cursor / Claude / VS Code MCP settings
greplm agent add     # auto-detects your editor (.cursor/, .claude/, etc.)

Run greplm welcome anytime to see the checklist again.

Manual workflow (same result, step by step):

greplm index                    # build the index
greplm search "SegmentWriter"   # search file contents
greplm symbols Searcher         # look up a definition
greplm refs SegmentWriter       # find references

Each query prints compact, ready-to-jump locations:

$ greplm search "SegmentWriter" --path segment.rs --limit 4
crates/greplm-core/src/segment.rs:107:12: pub struct SegmentWriter {
crates/greplm-core/src/segment.rs:114:6: impl SegmentWriter {

$ greplm symbols Searcher --limit 4
function   searcher                 crates/greplm-core/src/lib.rs:204-206
struct     Searcher                 crates/greplm-core/src/search.rs:351-355
function   swap_searcher            crates/greplm-core/src/daemon.rs:85-88
function   read_searcher            crates/greplm-core/src/daemon.rs:81-83

$ greplm refs SegmentWriter --limit 4
crates/greplm-core/src/segment.rs:107:12: pub struct SegmentWriter {
README.md:49:16: greplm search "SegmentWriter"   # search file contents
README.md:51:13: greplm refs SegmentWriter       # find references
bench/README.md:39:2: `SegmentWriter` is judged on the source, not on the `queries.json` that defines it.

Definitions rank first in refs; without --path, doc files that mention the identifier also appear.

Re-run greplm index after changes (it’s incremental), or keep it automatic with greplm watch.

Add the agent files

greplm agent add installs two things per tool, both baked into the binary (fully offline):

A subagent (.../greplm-search.md) — a delegated code-search agent the main loop can call.
Main-loop guidance — a short, greplm-first block written into the tool’s always-on memory file (CLAUDE.md, AGENTS.md, .cursor/rules/greplm.mdc, …). This is what makes the primary agent prefer greplm over raw grep by default; the subagent alone only runs when the main agent chooses to delegate to it.

greplm agent add cursor          # subagent + .cursor/rules/greplm.mdc for this project
greplm agent add claude --global # ~/.claude/agents + ~/.claude/CLAUDE.md for every project
greplm agent add                 # auto-detect the editor (dot-dir or memory file)
greplm agent list                # show every tool, its subagent, and its rules destination

Supported tools (project scope; pass --global for the home directory):

Tool	`agent add` key	Subagent	Main-loop guidance
Claude Code	`claude`	`.claude/agents/greplm-search.md`	`CLAUDE.md`
Cursor	`cursor`	`.cursor/agents/greplm-search.md`	`.cursor/rules/greplm.mdc`
Gemini CLI	`gemini`	`.gemini/agents/greplm-search.md`	`GEMINI.md`
GitHub Copilot	`copilot`	`.github/agents/greplm-search.agent.md`	`.github/copilot-instructions.md`
opencode	`opencode`	`.opencode/agent/greplm-search.md`	`AGENTS.md`
Kiro	`kiro`	`.kiro/agents/greplm-search.md`	`.kiro/steering/greplm.md`
Pi	`pi`	`.pi/agents/greplm-search.md`	`AGENTS.md`
Reasonix	`reasonix`	`.reasonix/agents/greplm-search.md`	`AGENTS.md`

Auto-detection keys off either the tool’s dot-directory (.cursor/, .claude/, …) or an unambiguous root memory file (CLAUDE.md, GEMINI.md). If nothing is detected, greplm agent add falls back to the cross-tool AGENTS.md so the project is still configured.

The guidance is wrapped in / markers: re-running is idempotent, your own content is never clobbered, and --force refreshes just that block in place. The raw definitions also live in crates/greplm-cli/agents/ if you prefer to copy them manually. Restart the tool (or start a new session) so it picks up the changes.

Requirements

Platforms: Linux (x86_64, aarch64), macOS (Intel & Apple Silicon), and Windows (x86_64). Prebuilt binaries are published for all of these on GitHub Releases.
Building from source / cargo install: Rust 1.90+ (MSRV).
Runtime: none. No services, no network — the index lives entirely in .greplm/.
Semantic search is opt-in behind the semantic feature and builds a local vector index; it is otherwise not required.

Build from source

cargo build --release
# binaries: target/release/greplm  and  target/release/greplm-mcp