greplm

https://greplm.com/docs
Admin
greplm is an offline codebase indexing and search tool designed for AI coding agents to provide...
Tokens:12,034
Snippets:102
Trust Score:2.1
Update:5 days ago
Show doc for...
Tokens:
Raw
### Setup greplm in a project

Source: https://greplm.com/docs

Run greplm setup in your project directory to index the codebase and configure agents. This is the second step after installation.

```bash
cd your-project && greplm setup
```

--------------------------------

### Install greplm via curl script

Source: https://greplm.com/docs

One-line installation command using curl to pipe the install script to sh. This is the first step in the setup process.

```bash
curl -fsSL …/install.sh | sh
```

--------------------------------

### First-time setup with greplm setup

Source: https://greplm.com/docs/getting-started

One command to set up the index, warm daemon, and agent files in a project. Run from the project directory.

```bash
cd your-project
greplm setup
```

--------------------------------

### Always-on daemon: install launchd service

Source: https://greplm.com/docs/usage

Installs a background service that starts at login and restarts if it dies. Use --global for one daemon for all projects (recommended) or specify a project path for a single project.

```bash
contrib/launchd/install-launchd.sh --global              # one daemon for all projects (recommended)
contrib/launchd/install-launchd.sh /abs/path/to/project  # or just one project
```

--------------------------------

### Common workflows: setup, indexing, search, symbols, refs, outline, snippet, repo info, health check

Source: https://greplm.com/docs/usage

Shows the main greplm commands for setup, indexing, searching, symbols, references, outlines, snippets, repo info, and health checks. Most query commands accept --json and -C/--root. --json is compact by default; add --pretty for indented output. Set GREPLM_LOG=debug for verbose logging.

```bash
# First-run (index + always-on global daemon service)
greplm setup

# Set up manually
greplm init             # scaffold .greplm/config.toml (no indexing yet)

# Indexing
greplm index            # incremental build/refresh
greplm index --force    # full rebuild
greplm watch            # re-index automatically on file changes
greplm clean            # remove .greplm/

# Search file contents
greplm search "tokio" --lang rust
greplm search -e 'fn .*candidates' --path crates/ --limit 20 --json
greplm search "get" --word --limit 20 --offset 20   # whole-identifier + pagination

# Symbols / definitions
greplm symbols Searcher --kind struct --exact
greplm symbols lc       # acronym match: loadConfig / load_config

# References, outlines, snippets
greplm refs SegmentWriter
greplm outline crates/greplm-core/src/trigram.rs
greplm snippet crates/greplm-core/src/trigram.rs 15 25 --context 3

# Repo info
greplm summary
greplm status

# Health check
greplm doctor           # diagnose index freshness, daemon, and version
greplm doctor --fix     # refresh a stale index and install the daemon service
greplm update --check   # see if a newer release is available
```

--------------------------------

### Example MCP client configuration output

Source: https://greplm.com/docs/mcp

Example output from greplm mcp config showing the mcpServers object with the greplm server command and args. The first args entry sets the project root.

```json
{
  "mcpServers": {
    "greplm": {
      "command": "/Users/you/.cargo/bin/greplm-mcp",
      "args": ["/Users/you/projects/my-app"]
    }
  }
}
```

--------------------------------

### Example .greplm/config.toml

Source: https://greplm.com/docs/configuration

Default configuration file created by `greplm init` or on first `greplm index`. Controls walk and indexing: include/exclude globs, max file size, gitignore respect, hidden/binary/empty file indexing, backend selection, and merge threshold.

```toml
include = []                       # glob whitelist (empty = all text files)
exclude = ["**/.git/**", "**/node_modules/**", "**/target/**", "**/.greplm/**"]
max_file_size = 4194304            # skip files larger than this (bytes); 0 = no limit
respect_gitignore = true
index_hidden = false
index_binary = false               # index NUL-containing (binary) files, like grep -a
index_empty = false                # index zero-byte files
backend = "auto"                   # auto | rayon (see note below)
merge_threshold = 16               # auto-compact once segments exceed this
```

--------------------------------

### Install greplm with cargo

Source: https://greplm.com/docs/getting-started

Installs greplm and greplm-mcp from the git repository using Cargo. Requires Rust to be installed.

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

--------------------------------

### Install greplm on Linux/macOS/Git Bash with curl

Source: https://greplm.com/docs/getting-started

One-line installation for Linux, macOS, and Git Bash on Windows. Downloads and runs the install script from the greplm repository.

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

--------------------------------

### greplm savings output example

Source: https://greplm.com/docs/token-efficiency

Example output from `greplm savings` showing a summary table with token savings percentages.

```text
  greplm Token Savings
  ================================================================
  Period          Calls   Savings
  ----------------------------------------------------------------
  Last 24h            4   [███████████████░]  ~95.6k tokens (96%)
  Last 7 days         4   [███████████████░]  ~95.6k tokens (96%)
  All time            4   [███████████████░]  ~95.6k tokens (96%)
```

--------------------------------

### Example output of greplm search, symbols, and refs

Source: https://greplm.com/docs/getting-started

Sample output showing compact, ready-to-jump locations for search, symbols, and refs commands. Definitions rank first in refs; without --path, doc files mentioning the identifier also appear.

```bash
$ 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.
```

--------------------------------

### Global daemon: greplm serve --global

Source: https://greplm.com/docs/usage

Starts a single background daemon that serves every project on the machine over one per-user socket. Loads each project lazily on first query and evicts idle projects. Queries and the MCP server auto-discover the project root and route to it.

```bash
greplm serve --global
```

--------------------------------

### Install greplm on Windows PowerShell with irm

Source: https://greplm.com/docs/getting-started

One-line installation for Windows PowerShell. Downloads and runs the install.ps1 script from the greplm repository.

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

--------------------------------

### greplm agent add commands for Cursor, Claude, auto-detect, and list

Source: https://greplm.com/docs/getting-started

Shows the `greplm agent add` command with the `cursor` and `claude` keys, the auto-detect form, and `greplm agent list`. The `--global` flag installs to the home directory; without it, project scope is used. Auto-detection keys off the tool's dot-directory or an unambiguous root memory file, falling back to `AGENTS.md` if nothing is detected.

```bash
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
```

--------------------------------

### Warm daemon: start greplm serve

Source: https://greplm.com/docs/usage

Runs a daemon to keep the index hot in memory with the watcher running, enabling sub-millisecond queries. While running, query commands and the MCP server automatically route to it. Pass --no-daemon to force an in-process query.

```bash
greplm serve
```

--------------------------------

### build_context

Source: https://greplm.com/docs/mcp

Builds a task-driven, token-budgeted context pack. Recommended to call first.

```APIDOC
## build_context

### Description
Task-driven, token-budgeted context pack (call this first).

### Tool Name
`build_context`

### Parameters
- **task** (string) - Required - The task description.
- **token_budget** (integer) - Optional - The maximum token budget.

### Response
Compact JSON with context items, each containing `snippet_start` and `code`.
```

--------------------------------

### greplm pack "how does incremental indexing work" --budget 4000

Source: https://greplm.com/docs/code-intelligence

Shows the `pack` command output for a natural language query with a token budget. The output includes a context pack header, item count, token usage, and a matched function.

```bash
$ greplm pack "how does incremental indexing work" --budget 4000
# context pack for: how does incremental indexing work
# 15 items, ~3489/4000 tokens
## function index_incremental (match)  crates/greplm-core/src/indexer.rs:265-454  [17.9]
  ...
```

--------------------------------

### Benchmark commands for token efficiency

Source: https://greplm.com/docs/token-efficiency

Commands to build and run benchmarks that measure search and context-pack efficiency against ripgrep and whole-file reading.

```bash
cargo build --release

# Search efficiency vs the ripgrep + read-whole-files baseline:
python3 bench/run_bench.py

# Context-pack efficiency (budgeted packs vs reading whole files):
python3 bench/context/pack_bench.py
```

--------------------------------

### Manual workflow commands for greplm

Source: https://greplm.com/docs/getting-started

Step-by-step manual workflow to build the index, search file contents, look up definitions, and find references.

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

--------------------------------

### Generate MCP client configuration with greplm mcp config

Source: https://greplm.com/docs/mcp

Run these commands in your project directory to generate copy-paste JSON configuration for the MCP client. The --pretty flag outputs indented JSON, and -q outputs JSON only for scripts. The first args entry sets the project root.

```bash
cd your-project
greplm mcp config          # JSON on stdout, paste hints on stderr
greplm mcp config --pretty # indented JSON (same content)
greplm mcp config -q       # JSON only (for scripts)
```

--------------------------------

### Semantic search: build with semantic feature and run commands

Source: https://greplm.com/docs/usage

Builds greplm with the optional semantic feature and runs semantic indexing and search. The semantic search is fully offline and meaning-based.

```bash
cargo build --release -p greplm-cli --features semantic
greplm semantic-index
greplm semantic-search "parse a regex into a trigram query" --limit 10
```

--------------------------------

### repo_summary

Source: https://greplm.com/docs/mcp

Provides language breakdown, file/symbol counts, and top directories.

```APIDOC
## repo_summary

### Description
Language breakdown, file/symbol counts, top directories.

### Tool Name
`repo_summary`

### Parameters
None.

### Response
Compact JSON with repository summary.
```

--------------------------------

### Build greplm from source with cargo build --release

Source: https://greplm.com/docs/getting-started

Builds greplm and greplm-mcp binaries in release mode. Requires Rust 1.90+ (MSRV). The binaries are output to target/release/.

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

--------------------------------

### Token savings comparison for SegmentWriter search

Source: https://greplm.com/docs/token-efficiency

Shows the token cost of grep + read whole files vs greplm search for the same query, demonstrating a 97.1% reduction.

```text
"Where is SegmentWriter used?"

  grep + read whole files →  20 files,  ~41,600 tokens
  greplm search           →  20 files,    1,201 tokens   ·  97.1% fewer
```

--------------------------------

### Connect AI editor with greplm mcp config and agent add

Source: https://greplm.com/docs/getting-started

Commands to configure MCP settings for Cursor, Claude, or VS Code, and to auto-detect your editor's agent files.

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

--------------------------------

### goto_definition

Source: https://greplm.com/docs/mcp

Provides typed go-to-definition for an identifier at a specific file:line:col location.

```APIDOC
## goto_definition

### Description
Typed go-to-definition for an identifier at file:line:col.

### Tool Name
`goto_definition`

### Parameters
- **file** (string) - Required - The file path.
- **line** (integer) - Required - The line number.
- **column** (integer) - Required - The column number.

### Response
Compact JSON with definition location.
```

--------------------------------

### greplm savings command usage

Source: https://greplm.com/docs/token-efficiency

Commands to view token savings summaries, with options for verbose breakdown and machine-readable JSON output.

```bash
greplm savings            # rolling 24h / 7d / all-time summary
greplm savings --verbose  # also break down by query kind
greplm savings --json     # machine-readable
```

--------------------------------

### index_project

Source: https://greplm.com/docs/mcp

Builds or refreshes the index. Supports incremental or force refresh.

```APIDOC
## index_project

### Description
Build or refresh the index (incremental or `force`).

### Tool Name
`index_project`

### Parameters
- **mode** (string) - Optional - `incremental` or `force`

### Response
Compact JSON with index status.
```

--------------------------------

### greplm def crates/greplm-cli/src/main.rs 896 57

Source: https://greplm.com/docs/code-intelligence

Shows the `def` command output for a definition at a specific file and position. The `*` marks an unambiguous resolution; otherwise candidates are ranked.

```bash
$ greplm def crates/greplm-cli/src/main.rs 896 57
* function   references               crates/greplm-core/src/search.rs:543-551
```

--------------------------------

### get_file_outline

Source: https://greplm.com/docs/mcp

Returns the symbol outline of one file.

```APIDOC
## get_file_outline

### Description
Symbol outline of one file.

### Tool Name
`get_file_outline`

### Parameters
- **file** (string) - Required - The file path.

### Response
Compact JSON with symbol outline.
```

--------------------------------

### greplm ast 'fn $NAME() {}' --lang rust --limit 1

Source: https://greplm.com/docs/code-intelligence

Shows the `ast` command output for a friendly `$NAME` query in Rust. The output includes the matched code snippet with the capture.

```bash
$ greplm ast 'fn $NAME() {}' --lang rust --limit 1
crates/greplm-cli/src/agent.rs:86-88:     fn dest(&self, scope_root: &Path) -> PathBuf { NAME=dest
```

--------------------------------

### greplm impact add_doc --depth 2 --limit 4

Source: https://greplm.com/docs/code-intelligence

Shows the `impact` command output for `add_doc` with depth 2 and limit 4. The output lists functions affected at different depths with file locations.

```bash
$ greplm impact add_doc --depth 2 --limit 4
d0  function   add_doc                  crates/greplm-core/src/segment.rs:132-165
d1  function   index_full               crates/greplm-core/src/indexer.rs:187-262
d1  function   index_incremental        crates/greplm-core/src/indexer.rs:265-454
d2  function   compact                  crates/greplm-core/src/indexer.rs:459-467
```

--------------------------------

### greplm callers references --limit 3

Source: https://greplm.com/docs/code-intelligence

Shows the `callers` command output for `references` with a limit of 3. The output lists caller references with file locations.

```bash
$ greplm callers references --limit 3
cmd_refs -> references  crates/greplm-cli/src/main.rs:896:17
dispatch -> references  crates/greplm-core/src/daemon.rs:263:32
definition -> references  crates/greplm-core/src/search.rs:874:24
```

--------------------------------

### references_at

Source: https://greplm.com/docs/mcp

Returns resolved references for an identifier at a specific file:line:col location.

```APIDOC
## references_at

### Description
Resolved references for an identifier at file:line:col.

### Tool Name
`references_at`

### Parameters
- **file** (string) - Required - The file path.
- **line** (integer) - Required - The line number.
- **column** (integer) - Required - The column number.

### Response
Compact JSON with resolved references.
```

--------------------------------

### read_snippet

Source: https://greplm.com/docs/mcp

Reads a file slice with surrounding context.

```APIDOC
## read_snippet

### Description
Read a file slice with surrounding context.

### Tool Name
`read_snippet`

### Parameters
- **path** (string) - Required - The file path.
- **start_line** (integer) - Required - The starting line number.
- **end_line** (integer) - Required - The ending line number.

### Response
Compact JSON with `path`, `start_line`, `end_line`, `total_lines`, and `text`.
```

--------------------------------

### changed_since

Source: https://greplm.com/docs/mcp

Returns files (with symbols) changed since a revision.

```APIDOC
## changed_since

### Description
Files (with symbols) changed since a revision.

### Tool Name
`changed_since`

### Parameters
- **revision** (string) - Required - The revision identifier.

### Response
Compact JSON with changed files and symbols.
```

--------------------------------

### index_status

Source: https://greplm.com/docs/mcp

Returns index statistics.

```APIDOC
## index_status

### Description
Index stats.

### Tool Name
`index_status`

### Parameters
None.

### Response
Compact JSON with index statistics.
```

--------------------------------

### impact_of

Source: https://greplm.com/docs/mcp

Calculates blast radius via the reverse call graph.

```APIDOC
## impact_of

### Description
Blast radius via the reverse call graph.

### Tool Name
`impact_of`

### Parameters
- **identifier** (string) - Required - The identifier to analyze.

### Response
Compact JSON with affected locations.
```

--------------------------------

### structural_search

Source: https://greplm.com/docs/mcp

Performs tree-sitter query or $NAME pattern (AST) search.

```APIDOC
## structural_search

### Description
Tree-sitter query / `$NAME` pattern (AST) search.

### Tool Name
`structural_search`

### Parameters
- **pattern** (string) - Required - The tree-sitter query or `$NAME` pattern.

### Response
Compact JSON with matching AST nodes.
```

--------------------------------

### search_code

Source: https://greplm.com/docs/mcp

Performs content search with options for literal, regex, whole-word, and filters.

```APIDOC
## search_code

### Description
Content search (literal / regex / whole-word / filters).

### Tool Name
`search_code`

### Parameters
- **query** (string) - Required - The search pattern.
- **mode** (string) - Optional - `literal`, `regex`, or `whole-word`.
- **filters** (object) - Optional - Additional filters.

### Response
Compact JSON with matching code snippets.
```

--------------------------------

### find_references

Source: https://greplm.com/docs/mcp

Finds occurrences of an identifier, with definitions listed first.

```APIDOC
## find_references

### Description
Occurrences of an identifier (definitions first).

### Tool Name
`find_references`

### Parameters
- **identifier** (string) - Required - The identifier to search for.

### Response
Compact JSON with reference locations.
```

--------------------------------

### find_symbol

Source: https://greplm.com/docs/mcp

Performs symbol lookup with exact, prefix, substring, or fuzzy matching.

```APIDOC
## find_symbol

### Description
Symbol lookup (exact / prefix / substring / fuzzy).

### Tool Name
`find_symbol`

### Parameters
- **name** (string) - Required - The symbol name to find.
- **match** (string) - Optional - `exact`, `prefix`, `substring`, or `fuzzy`.

### Response
Compact JSON with matching symbols.
```

--------------------------------

### resolved_references

Source: https://greplm.com/docs/mcp

Returns resolved references from the structural index, including definitions, calls, and imports.

```APIDOC
## resolved_references

### Description
Resolved refs from the structural index (defs + calls + imports).

### Tool Name
`resolved_references`

### Parameters
- **identifier** (string) - Required - The identifier to resolve.

### Response
Compact JSON with resolved references.
```

--------------------------------

### git_blame

Source: https://greplm.com/docs/mcp

Returns the commit and author that last changed a line.

```APIDOC
## git_blame

### Description
Commit/author that last changed a line.

### Tool Name
`git_blame`

### Parameters
- **file** (string) - Required - The file path.
- **line** (integer) - Required - The line number.

### Response
Compact JSON with commit and author info.
```

--------------------------------

### find_callers

Source: https://greplm.com/docs/mcp

Finds which functions or methods call a given function or method.

```APIDOC
## find_callers

### Description
Who calls a function/method.

### Tool Name
`find_callers`

### Parameters
- **function** (string) - Required - The function or method name.

### Response
Compact JSON with caller locations.
```

--------------------------------

### find_callees

Source: https://greplm.com/docs/mcp

Finds what a given function or method calls.

```APIDOC
## find_callees

### Description
What a function/method calls.

### Tool Name
`find_callees`

### Parameters
- **function** (string) - Required - The function or method name.

### Response
Compact JSON with callee locations.
```

--------------------------------

### symbol_history

Source: https://greplm.com/docs/mcp

Returns commits that touched a symbol.

```APIDOC
## symbol_history

### Description
Commits that touched a symbol.

### Tool Name
`symbol_history`

### Parameters
- **symbol** (string) - Required - The symbol name.

### Response
Compact JSON with commit history.
```
Tokens:
Raw