grepai: Local Semantic Code Search and Call Graphs for AI Agents
Semantic Search & Call Graphs for AI Agents (100% Local)
At a glance
- What is it?
- grepai is a Go CLI that indexes a repository with vector embeddings so agents can query code by intent instead of regex, and trace callers before editing a function. The trade-off is that it needs a running embedding provider and a background indexer, which plain grep does not.
- Who is it for?
- Adopt grepai if your agent sessions are burning tokens on regex searches and you can run Ollama locally with nomic-embed-text pulled. Skip it if your repository is small enough that ripgrep answers in one pass, or if you cannot keep a background daemon and an embedding server running.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The token bill that grepai is trying to cut
An agent asked to change authentication code usually starts by grepping. It runs a pattern, reads the hits, refines the pattern, reads again, and only then edits. Every one of those round trips is input tokens, and the README quotes a user on r/ClaudeAI who wrote that reading a codebase consumed 13% of a plan limit. That is the problem grepai targets: not search itself, but the number of search iterations an agent needs before it has enough context to act.
The tool is aimed at developers running coding agents such as Claude Code, Cursor, or Windsurf against a repository large enough that pattern search returns too much or too little. The README frames the pitch as search by meaning rather than text, with the example of querying "authentication logic" and landing on handleUserSession. If your codebase uses consistent naming and your queries are already exact, this solves a problem you do not have.
Embeddings, a file watcher, and an MCP surface
grepai builds a vector index of the codebase and answers queries against that index instead of scanning files. The README describes four moving parts. First, an embedding provider converts code into vectors; Ollama is the default, with LM Studio and OpenAI listed as alternatives. Second, an indexer walks the project and stores those vectors. Third, a file watcher keeps the index current, which the README advertises as always up-to-date. Fourth, an MCP server exposes the same capability as a tool an agent can call directly.
The call graph feature is separate from the semantic search. The README shows grepai trace callers "Login" as a way to find who calls a function before changing it. That is a structural query, not a similarity query, and it is the part most likely to matter to someone doing refactors. The README does not describe how the call graph is built, whether it parses each language's syntax or approximates from text, so the accuracy of trace results across languages is something you would have to check against your own code.
The privacy claim follows from the architecture: if embeddings come from a local Ollama instance, code does not leave the machine. That claim stops being true the moment you configure OpenAI as the provider, which the README lists without qualification.
Installing grepai and the provider it expects
The README gives four install paths. On macOS with Homebrew: brew install yoanbernabeu/tap/grepai. On Linux and macOS via script: curl -sSL https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.sh | sh. On Windows PowerShell: irm https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.ps1 | iex. Shell completion is a separate step, with per-shell instructions for zsh, bash, fish, and PowerShell, plus an Oh-My-Zsh plugin layout.
The binary alone is not enough. The README states it requires an embedding provider and recommends Ollama, with a single setup command: ollama pull nomic-embed-text. That model pull is the step people skip, and it is the one that determines whether the first search returns anything.
The quick start is four commands: grepai init to initialize in a project, grepai watch to start the indexing daemon, grepai search "error handling" to query, and grepai trace callers "Login" to walk the call graph. Note the shape of this workflow. watch is a daemon, not a one-shot command, so grepai expects to run continuously alongside your editor and your agent. The README does not document the configuration file format or the keys used to point grepai at a non-default provider, so plan on reading the linked documentation site for that rather than guessing.
Where the daemon model costs you
The always-up-to-date claim depends on the watcher noticing every change. Watchers fail in predictable places: generated directories, build output, dependency trees, and large binary assets. If the watcher ingests node_modules or a compiled target directory, your index fills with vectors that have nothing to do with your source, and search quality drops in a way that is hard to diagnose because the results still look plausible. The README does not list default ignore rules, so exclusion behavior is something to confirm before indexing a real repository.
The second cost is the second process. You now need Ollama or an equivalent running, plus grepai watch, plus your editor, plus your agent. On a laptop that is a meaningful amount of memory, and on a shared or constrained machine it may be the reason not to adopt this at all.
The third is staleness at the edges. A semantic index answers from what it has embedded. If a file changed seconds ago and the watcher has not caught up, the agent gets context from the previous version. With grep, that failure mode does not exist, because grep reads the file as it is right now. For a fast-moving branch during a rebase or a codegen step, that difference matters.
grepai against ripgrep, and against the hosted options
The README's own comparison table puts grep and ripgrep on the other side: exact text and regex matching, queries like "func.*Login", results that are pattern matches. That is the honest framing. ripgrep is faster to start, has no index to maintain, no provider to run, and no daemon, and it never returns a result that is semantically close but textually unrelated. grepai's advantage is recall on queries where you do not know the identifier. If you can name the symbol, ripgrep wins on every axis except the token count of the agent conversation around it.
The other alternative is a hosted code search or a cloud embedding service. The difference is not features, it is where the vectors and the source text live. grepai's default configuration keeps both on the machine through Ollama; a hosted service sends code or embeddings over the network and typically charges per query or per indexed byte. Choosing grepai means choosing to operate the embedding stack yourself, including model downloads, disk for the index, and the daemon. Choosing a hosted service means trading that operational work for a network dependency and a data boundary you no longer control. The README's privacy-first framing only holds on the first path.
Maintenance, versioning, and the MIT licence
The release cadence visible in the repository is tight: v0.37.0 on 2026-09-10, v0.36.1 on 2026-09-01, v0.36.0 on 2026-08-30. Three releases in under two weeks, all in the 0.3x series. That means the project is still pre-1.0 and moving. Expect command surface and configuration details to shift between minor versions, and expect to re-read the docs after an upgrade rather than assuming flags are stable. If you pin grepai in a team setup, pin the version too.
The licence is MIT, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it is worth noting what MIT does not cover here: the embedding model you pull has its own licence, separate from grepai's, and the README names nomic-embed-text without stating its terms. If you swap in OpenAI, you are bound by their terms and you have given up the local-only property. None of this is legal advice; check the model licence and your organization's policy before indexing proprietary code.
The README also does not describe an upgrade path for the index itself. If a new version changes the vector format or the embedding model, the existing index may need a rebuild. Budget for a full re-index after major upgrades rather than assuming it carries over.
Who should install this, and what to check first
grepai fits a specific situation: a repository large enough that agent-driven grep loops are expensive, a machine that can run Ollama comfortably, and a workflow where you are willing to keep a daemon alive. The MCP server is the piece that makes it more than a search CLI, because it lets the agent call grepai as a tool instead of shelling out to grep and parsing text. If your agent supports MCP, that is the integration to evaluate, not the standalone search command.
It does not fit small projects, machines without spare memory, or teams that cannot run a local model. It also does not fit anyone who needs guaranteed freshness on every query, because the watcher is asynchronous by design.
Before adopting, verify three things on your own repository. Run grepai init and grepai watch, then confirm that the index does not include build artifacts or vendored dependencies, since the README does not state default exclusions. Run a trace callers query on a function you already know the call sites for, and compare the output against what you know, because the README does not explain how the call graph is derived. Finally, confirm which provider grepai is actually using before you index anything proprietary, since the README lists OpenAI alongside the local options and the privacy claim depends on which one is configured.
Editorial conclusion
Adopt grepai if your agent sessions are burning tokens on regex searches and you can run Ollama locally with nomic-embed-text pulled. Skip it if your repository is small enough that ripgrep answers in one pass, or if you cannot keep a background daemon and an embedding server running. Before committing, verify that the index survives a fresh clone on your machine, that the file watcher keeps up with your build output, and that your chosen provider is the one grepai actually talks to.
Community notes