grepai: semantic code search and call graphs that stay on your machine

The problem grepai targets: agents reading whole files to answer small questions

A coding agent asked to change authentication behaviour usually starts by grepping for a string it guessed. If the function is named handleUserSession and the agent searched for "login", the first pass returns nothing useful, so the agent reads files until it finds the right one. Every one of those files enters the context window and is billed. The README frames this as the core motivation: grepai "drastically reduces AI agent input tokens by providing relevant context instead of raw search results."

The tool is aimed at developers running Claude Code, Cursor or Windsurf against a codebase where naming conventions are inconsistent or where the concept you want does not appear as a literal string. It is less useful for the opposite case. If you know the exact identifier, grep and ripgrep are faster and need no index, no daemon and no embedding model. The README's own comparison table puts regex queries such as "func.*Login" on the ripgrep side and "user authentication flow" on the grepai side. That split is honest, and it is the right way to decide whether you need this at all.

How the index is built: tree-sitter chunks, embeddings, and a pluggable vector store

The repository layout separates the pipeline into distinct packages: watcher/, indexer/, embedder/, store/, search/, trace/ and mcp/. The dependency list in go.mod confirms the mechanism. github.com/smacker/go-tree-sitter handles parsing, so files are split into syntactic units rather than fixed-size text windows. github.com/fsnotify/fsnotify drives the file watcher. github.com/pgvector/pgvector-go and github.com/qdrant/go-client are both present, which matches the two storage backends exposed in compose.yaml.

Embeddings are not computed in-process. The embedder/ package talks to an external provider, and the README names three: Ollama (the default), LM Studio, and OpenAI. That choice is the whole privacy story. With Ollama or LM Studio the code and the vectors stay on the machine; with OpenAI the chunks leave it, so "100% local" is a property of the configuration, not of the binary. The README states it as a feature without qualification, and that is the one place where the copy runs ahead of the architecture.

The trace/ package is the second capability and the more distinctive one. grepai trace callers "Login" answers who calls a function, which is the question you want answered before renaming or changing a signature. It depends on the same tree-sitter parsing that feeds the index, so call graph accuracy is bounded by how well the grammar handles your language.

Installing grepai and running a first semantic search

Four install paths are documented. On macOS the Homebrew tap is the shortest. On Linux and macOS there is a shell installer, and Windows has a PowerShell equivalent.

brew install yoanbernabeu/tap/grepai

An embedding provider is required before any of this is useful. The README recommends Ollama and gives the model to pull.

ollama pull nomic-embed-text

With the binary and the model in place, the quick start is three commands run from the root of the project you want to search. The first writes the configuration, the second starts the indexing daemon, and the third issues a natural language query.

grepai init
grepai watch
grepai search "error handling"

Expect the first indexing pass to take noticeable time on a large repository, since every chunk needs an embedding round trip to the local model. After that, the watcher keeps the index current. The call graph query uses the same index.

grepai trace callers "Login"

If you want your agent to call grepai directly rather than shelling out, the project ships an MCP server in the mcp/ directory, built on github.com/mark3labs/mcp-go. The README points to the documentation site for MCP setup rather than spelling out the configuration inline, so that is where to look. Shell completion is available for zsh, bash, fish and PowerShell through grepai completion, including dynamic values such as workspace and provider names.

Where grepai is the wrong tool

Semantic search has no notion of exhaustiveness. A vector query returns the nearest neighbours, not every match. If you are auditing for a deprecated API call, hunting a hardcoded credential, or checking that a symbol appears nowhere else, grepai will silently miss instances that fall outside the top results. Use ripgrep for anything where a miss is a bug.

The daemon is a second constraint. grepai watch has to be running for the index to stay fresh, and a stale index is worse than no index because the results look plausible. The README does not document what the watcher does when it drops an event, nor is there a documented rollback path for a corrupted index. The store/ package and the updater/ package exist in the tree, but the README does not describe recovery behaviour.

There is also a hard dependency on an embedding provider. No Ollama, no LM Studio, no OpenAI key means no search. That rules out locked-down build machines and CI containers where you cannot pull a model or reach an endpoint.

Finally, the project is C and Go in equal measure by topic and language metadata, but go.mod pins go 1.25.5 and the build path is Go throughout. The Makefile shows a golangci-lint v2.13.2 container for linting and go test -race for the test suite, so contributing requires a Go toolchain and, for the full pre-commit target, Docker.

grepai versus ripgrep and versus a hosted code search index

Against ripgrep the difference is query shape, not speed. ripgrep matches bytes and returns every hit; grepai embeds chunks and returns ranked neighbours. ripgrep never needs a model, a daemon or a database. grepai needs all three. The README's table is the clearest statement of this trade-off in the project's own words.

Against a hosted code search product, the difference is where the vectors live. grepai defaults to a local store and a local model, which is why the privacy claim holds in the default configuration. A hosted index gives you cross-repository search and no local compute cost, at the price of uploading your source. The compose.yaml file shows grepai can also run against Postgres with pgvector on port 5432 or Qdrant on ports 6333 and 6334, both behind optional Compose profiles, so the storage layer can be centralised if you want it. That is a deployment choice the project leaves open rather than a default.

The MCP server is the third axis. Instead of you running searches and pasting results, the agent calls grepai as a tool. That is the intended integration with Claude Code, Cursor and Windsurf, and it is the reason the token-reduction claim is plausible: the agent retrieves a few relevant chunks instead of reading files.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-09-10, and v0.37.0 was released the same day. The release cadence visible in the repository is roughly weekly across late August and early September 2026, with v0.36.0 on 2026-08-30, v0.36.1 on 2026-09-01 and v0.37.0 on 2026-09-10. The repository is not archived.

The version number is the thing to weigh. At 0.x, the CLI surface and the configuration format are not covered by a stability promise, and the CHANGELOG.md at the repository root is where breaking changes would appear. Pin a version if you wire grepai into an agent workflow, and read the changelog before moving.

The licence is MIT, held by Yoan Bernabeu. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are retained. That covers the binary. It does not cover the embedding model you pair with it, which carries its own licence from whichever provider you choose, and it does not cover the source code you index. Those are separate questions and this is not legal advice.

Editorial conclusion

Adopt grepai if you run a coding agent against a repository too large to paste into context and you already have Ollama or another embedding provider running locally. Skip it if your searches are regex-shaped, if you cannot run a background daemon, or if you have no embedding endpoint at all, since the CLI has nothing to query without one. Before committing, run grepai init and grepai watch on one repository and confirm the index actually refreshes when you save a file, because the README documents the watcher but not what happens when it misses a change.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. yoanbernabeu/grepai on GitHub