Natural-language search that works like grep. Fast, local, and built for coding agents.

• Semantic: Finds concepts ("where do transactions get created?"), not just strings.
• Call Graph Tracing: Map dependencies with trace, find tests with test, measure blast radius with impact.
• Role Detection: Distinguishes ORCHESTRATION (high-level logic) from DEFINITION (types/classes).
• Local & Private: 100% local embeddings via ONNX (CPU) or MLX (Apple Silicon GPU).
• Centralized Index: One database at ~/.gmax/ — index once, search from anywhere.
• Agent-Ready: --agent flag returns compact one-line output — ~89% fewer tokens than default.

Quick Start

npm install -g grepmax        # 1. Install
cd my-repo && gmax add        # 2. Add + index
gmax "where do we handle auth?" --agent  # 3. Search

No setup required — gmax auto-detects your platform (GPU on Apple Silicon, CPU elsewhere) and downloads models on first use.

Setup & Config

gmax setup                    # Interactive wizard (models, embedding mode, plugins)
gmax config                   # View current settings
gmax config --embed-mode gpu  # Switch to GPU (Apple Silicon)
gmax doctor                   # Health check
gmax doctor --fix             # Auto-repair (compact, prune, remove stale locks)

Core Commands

gmax "where do we handle auth?" --agent  # Semantic search (compact output)
gmax extract handleAuth                  # Full function body with line numbers
gmax peek handleAuth                     # Signature + callers + callees
gmax trace handleAuth -d 2              # Call graph (2-hop)
gmax skeleton src/lib/auth.ts           # File structure (bodies collapsed)
gmax symbols auth                       # List indexed symbols

Analysis Commands

gmax log src/lib/auth.ts                 # Git commit history for a path or symbol
gmax test handleAuth                     # Find tests via reverse call graph
gmax impact handleAuth                   # Dependents + affected tests
gmax similar handleAuth                  # Find similar code patterns
gmax audit --top 10                      # God nodes, hub files, file cycles, dead candidates
gmax surprises --experimental --agent    # Experimental: similar but graph-disconnected file pairs
gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
gmax context "auth system" --budget 4000 # Token-budgeted topic summary
gmax context src/lib/auth.ts --budget 4000 # Deterministic file/path context

Project Commands

gmax project                  # Languages, structure, key symbols
gmax related src/lib/auth.ts  # Dependencies + dependents
gmax status                   # All indexed projects + chunk counts

In our public benchmarks, grepmax can save about 20% of your LLM tokens and deliver a 30% speedup.

Agent Plugins

gmax integrates with Claude Code, OpenCode, Codex, and Factory Droid. Install all detected clients at once:

gmax plugin add               # Install all detected clients
gmax plugin                   # Show plugin status
gmax plugin remove             # Remove all plugins

Or manage individually:

gmax plugin add claude         # Claude Code only
gmax plugin add opencode       # OpenCode only
gmax plugin add codex          # Codex only
gmax plugin add droid          # Factory Droid only
gmax plugin remove claude      # Remove specific plugin

Plugins auto-update when you run npm install -g grepmax@latest — no need to re-run gmax plugin add.

How it works per client

• Claude Code: Plugin with hooks (SessionStart, CwdChanged, SubagentStart, PreToolUse). Model uses CLI via Bash(gmax ... --agent).
• OpenCode: Tool shim with dynamic SKILL + session plugin for daemon startup. Model calls gmax tool directly.
• Codex: MCP server registration + AGENTS.md skill instructions.
• Factory Droid: Skills + SessionStart/SessionEnd hooks for daemon lifecycle.

MCP Server

gmax mcp starts a stdio-based MCP server for clients that support MCP but can't run shell commands (Cursor, Windsurf, custom agents).

Tool	Description
semantic_search	Search by meaning. Pointer mode matches CLI --agent output; detail=code/full returns snippets.
code_skeleton	File structure with bodies collapsed (~4x fewer tokens).
trace_calls	Call graph: importers, callers (multi-hop), callees with file:line.
extract_symbol	Complete function/class body by symbol name.
peek_symbol	Compact overview: signature + callers + callees.
dead	Unused-symbol check via call graph. Returns DEAD, PUBLIC EXPORT, or LIVE with caller count.
audit	Graph summary: god nodes, hub files, symbol-derived file dependency cycles, and dead-code candidates.
surprising_connections	Experimental orientation signal: embedding-similar file pairs with no direct indexed static file edge. Requires experimental:true.
get_neighbors	Graph primitive: symbols reachable from a node along call edges within N hops.
find_paths	Graph primitive: shortest call-graph path between two symbols.
subgraph_for_files	Graph primitive: local dependency subgraph for a set of files.
list_symbols	Indexed symbols with role and export status.
list_projects	List every indexed project (name, root, status, chunks) to pick a search scope.
index_status	Index health: chunks, files, projects, watcher status.
summarize_project	Project overview: languages, structure, key symbols, entry points.
summarize_directory	Generate LLM summaries for indexed chunks.
related_files	Dependencies and dependents by shared symbols.
recent_changes	Recently modified indexed files.
diff_changes	Search scoped to git changes.
find_tests	Find tests via reverse call graph.
impact_analysis	Dependents + affected tests for a symbol or file.
find_similar	Vector similarity search.
build_context	Token-budgeted topic summary.
investigate	Agentic codebase Q&A using local LLM + gmax tools.
review_commit	Review a git commit for bugs, security issues, and breaking changes.
review_report	Get accumulated code review findings for the current project.
review_risk	Deterministic risk ranking of symbols a commit touches (blast radius × tests × churn). No LLM.

Search Options

gmax "query" [options]

Flag	Description	Default
--agent	Compact one-line output for AI agents.	false
-m <n>	Max results.	5
--per-file <n>	Max matches per file.	3
--role <role>	Filter: ORCHESTRATION, DEFINITION, IMPLEMENTATION.	—
--lang <ext>	Filter by extension (e.g. ts, py).	—
--file <name>	Filter by filename.	—
--exclude <prefix>	Exclude path prefix.	—
--symbol	Append call graph after results.	false
--imports	Prepend file imports per result.	false
--name <regex>	Filter by symbol name.	—
--in <subpath>	Restrict to a sub-path of the project (repeatable).	—
--seed-file <path>	Bias results toward files in your working context (repeatable).	—
--seed-symbol <name>	Bias results toward an identifier you're working with (repeatable).	—
--skeleton	Show file skeletons for top matches.	false
--context-for-llm	Full function bodies + imports per result.	false

Experimental Orientation

gmax surprises --experimental finds file pairs that are semantically similar but not already connected by the indexed static graph. Use it for architecture orientation, duplicate-logic sweeps, and cross-package drift checks, not as proof that two files are unrelated.

gmax surprises --experimental --agent
gmax surprises --experimental --in packages/app/src --dir-depth 4 --agent
gmax surprises --experimental --exclude generated --top 10

The CLI and MCP output include score, max similarity, pair count, representative symbols, directory buckets, top similarities, applied penalties, and gmax skeleton follow-up hints. On large monorepos, prefer --in/--exclude; the default scan is capped at 50,000 rows and user-provided --max-rows is capped at 100,000. If a narrow --in scope returns no findings, increase --dir-depth so subdirectories are compared inside the scope. | --budget <tokens> | Cap output tokens (for --context-for-llm). | 8000 | | --explain | Show scoring breakdown per result. | false | | --scores | Show relevance scores. | false | | --compact | Compact hits view (paths + line ranges + role/preview). | false | | --plain | Disable ANSI colors and use simpler formatting. | false | | -c, --content | Show full chunk content instead of snippets. | false | | -C <n> | Context lines before/after. | 0 | | -s, --sync | Sync local files to the store before searching. | false | | --root <dir> | Search a different project. | cwd | | --all-projects | Search every indexed project; results grouped by project. | false | | --projects <list> | Search only these projects (comma-separated names). | — | | --exclude-projects <list> | With --all-projects, skip these projects. | — | | --min-score <n> | Minimum relevance score. | 0 |

Background Daemon

A single daemon watches all registered projects via native OS file events (FSEvents/inotify). Changes are detected in sub-second and incrementally reindexed. All writes to LanceDB are routed through the daemon via IPC, eliminating lock contention.

gmax watch --daemon -b        # Start daemon manually
gmax watch stop               # Stop daemon
gmax status                   # See all projects + watcher status

The daemon auto-starts when you run gmax add, gmax index, gmax remove, or gmax summarize. It shuts down after 30 minutes of inactivity.

Local LLM (optional)

gmax can use a local LLM (via llama-server) for agentic codebase investigation. This is entirely opt-in and disabled by default — gmax works fine without it.

gmax llm on                   # Enable LLM features (persists to config)
gmax llm start                # Start llama-server (auto-starts daemon too)
gmax llm status               # Check server status
gmax llm stop                 # Stop llama-server
gmax llm off                  # Disable LLM + stop server

Investigate

Ask questions about your codebase — the LLM autonomously uses gmax tools (search, trace, peek, impact, related) to gather evidence and synthesize an answer.

gmax investigate "how does authentication work?"
gmax investigate "what would break if I changed VectorDB?" -v
gmax investigate "where are API routes defined?" --root ~/project

Review

Automatic code review on git commits. Extracts the diff, gathers codebase context (callers, dependents, related files), and prompts the LLM for structured findings.

gmax review                           # Review HEAD
gmax review --commit abc1234          # Review specific commit
gmax review --commit HEAD~3 -v        # Verbose — shows context gathering + LLM progress
gmax review report                    # Show accumulated findings
gmax review report --json             # Raw JSON output
gmax review clear                     # Clear report

Post-commit hook

Install a git hook that automatically reviews every commit in the background via the daemon:

gmax review install                   # Install in current repo
gmax review install ~/other-repo      # Install in another repo

The hook sends an IPC message to the daemon and returns instantly — it never blocks git commit. Findings accumulate in the report.

LLM Configuration

Variable	Description	Default
GMAX_LLM_MODEL	Path to GGUF model file	(none)
GMAX_LLM_BINARY	llama-server binary	llama-server
GMAX_LLM_PORT	Server port	8079
GMAX_LLM_IDLE_TIMEOUT	Minutes before auto-stop	30

Architecture

All data lives in ~/.gmax/:

• lancedb/ — LanceDB vector store (centralized, all projects)
• cache/meta.lmdb — file metadata cache (hashes, mtimes)
• cache/watchers.lmdb — watcher/daemon registry (LMDB, crash-safe)
• daemon.sock — Unix domain socket for daemon IPC
• daemon.pid — PID file for daemon dedup
• logs/ — daemon and server logs (5MB rotation)
• config.json — global config (model tier, embed mode)
• models/ — embedding models
• grammars/ — Tree-sitter grammars
• projects.json — registry of indexed directories

Pipeline: Walk (gitignore-aware) → Chunk (Tree-sitter) → Embed (384-dim Granite via ONNX/MLX) → Store (LanceDB + LMDB) → Search (vector + FTS + RRF fusion + ColBERT rerank)

Supported Languages:

• Structure-aware (Tree-sitter chunking + call graph): TypeScript, JavaScript/JSX, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP, Swift, Kotlin, Scala, Lua, Bash, JSON.
• Text-indexed (semantic search only, no call graph): Markdown, YAML, CSS, HTML, SQL, TOML, XML, and other common formats.

Configuration

// ~/.gmax/config.json
{
  "modelTier": "small",
  "vectorDim": 384,
  "embedMode": "gpu"
}

Model Tier

gmax embeds with IBM's Granite r2 code-embedding models. Two tiers are available:

Tier	Model	Dim	Params
small (default)	granite-embedding-small-english-r2	384	47M
standard	granite-embedding-english-r2	768	149M

384d is the default — and benchmarking says keep it. On gmax's own 97-case retrieval eval (pnpm bench:recall), the larger 768d model scored ~10 points worse on Recall@10 than 384d, consistently on both the MLX GPU and ONNX CPU embedding paths, with and without ColBERT rerank:

Model	Recall@10	MRR@10
small / 384d	0.72	0.51
standard / 768d	0.62	0.44

_{gmax repo, 97 cases, MLX GPU, rerank off (the shipped default). The CPU/q4 path and the rerank-on path show the same ~0.10 Recall@10 gap, so it isn't a quantization artifact — the bigger model just retrieves worse on code here.}

Bigger isn't better for this workload: 768d roughly doubles embedding compute, worker RAM, and dense-vector storage while lowering recall on code search. Unless you have a measured reason to switch (e.g. a recall complaint on a very large repo — benchmark it first), stay on 384d.

The model tier is part of the persisted embedding generation. You can change the desired configuration, but existing indexes remain on their built generation until you explicitly run the guarded whole-corpus rebuild:

gmax config --model-tier standard   # changes desired configuration only
gmax config                         # shows configured vs built identity
gmax status                         # reports current / legacy / stale / unbuilt per project
gmax repair --rebuild               # guarded whole-corpus rebuild through the daemon

legacy means the existing index is compatible but its exact model fingerprint was inferred from the previous registry shape. Run gmax index in that project to persist exact identity; no reset or re-embedding is required when the cached files are unchanged.

Cache metadata migrations are lazy and do not require a reset. Catchup stamps compatible legacy entries in place, hashes Markdown and MDX by exact bytes, and reprocesses only legacy Markdown or paths whose declared vector state disagrees with LanceDB. Files that intentionally produce no vectors remain valid cached entries.

A model change cannot be applied by a per-project gmax index --reset, even when vector widths match: one query embedding cannot safely search rows from another embedding space. Stale-generation search and sync fail before mutation, preserving the existing index. Run gmax repair --rebuild to replace the whole corpus, or restore the prior model tier as the non-destructive alternative.

Ignoring Files

gmax respects .gitignore and .gmaxignore:

# .gmaxignore
docs/generated/
*.test.ts
fixtures/

Environment Variables

Variable	Description	Default
GMAX_EMBED_MODE	Force cpu or gpu	Auto-detect
GMAX_WORKER_THREADS	Worker threads for embedding	50% of cores
GMAX_DEBUG	Debug logging	Off
GMAX_SUMMARIZER	Enable summarizer auto-start (1)	Off
GMAX_RERANK	Enable ColBERT rerank (1) — off by default since v0.17.1 (why)	Off

Troubleshooting

gmax doctor                   # Check health
gmax doctor --fix             # Auto-repair (compact, prune, fix locks)
gmax doctor --agent           # Machine-readable health output
gmax index                    # Reindex (auto-detects and repairs cache/vector mismatches)
gmax index --reset            # Full reindex from scratch
gmax watch stop && gmax watch --daemon -b  # Restart daemon

Contributing

See CLAUDE.md for development setup, commands, and architecture details.

Benchmarks

Two evaluation harnesses live in the repo. Both emit stable JSON via :json variants.

pnpm bench:recall          # 97-case internal eval against gmax's own repo
pnpm bench:recall:json
pnpm bench:oss             # P1 definition-lookup across express, lodash, platform (sverklo-bench fixtures)
pnpm bench:oss:json
GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank

The OSS bench requires the fixture repos to be indexed first — see docs/known-limitations.md for the most recent rerank-on-vs-off comparison across 4 datasets / 131 cases.

pnpm bench:recall also drives the model-tier comparison behind the 384d default — see Model Tier for why the larger 768d model is not the default.

Attribution

grepmax is built upon the foundation of mgrep by MixedBread. See the NOTICE file for details.

License

Licensed under the Apache License, Version 2.0. See LICENSE.