Mantic.sh: a local, structure-first code search engine for AI agents
A structural code search engine for Al agents.
At a glance
- What is it?
- Mantic.sh ranks files by path structure and metadata before reading content, and ships as a CLI plus an MCP server. It is fast enough for most repos but loses to ripgrep on raw scan speed, so the decision hinges on whether relevance ranking matters more than milliseconds.
- Who is it for?
- Adopt Mantic.sh if your agent or editor workflow keeps surfacing the wrong files and you want a local MCP server that ranks by path structure, with ripgrep left in place for exhaustive text matches. Skip it if you need the fastest possible scan on huge trees, since the README's own table shows ripgrep returning results in 0.022s on tensorflow where Mantic takes 0.550s.
- 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 64 days ago.
- What is it written in?
- Mainly TypeScript, 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 problem Mantic.sh targets: agents reading the wrong files
An agent asked to change a payment flow does not need every file containing the string "stripe". It needs the two or three files that actually implement the flow. Plain text search returns the first set. Mantic.sh is built for the second. The README describes it as a context-aware code search engine that prioritizes relevance over raw speed, and it is aimed at AI agents and the editors that host them, which is why the install badges point at Cursor and VS Code and why the package ships an MCP server mode alongside the CLI. The stated benefit is token efficiency: the README claims filtering irrelevant files before reading reduces token usage by up to 63%. That figure is the project's own claim and is not independently verified here. The audience is narrow on purpose. If you are a developer typing grep patterns into a terminal, the ranking layer mostly gets in your way. If you are wiring a retrieval step into an agent loop, ranking is the whole point.
How ranking works: path structure and metadata before file content
The design choice that separates Mantic.sh from grep-family tools is the order of operations. The README states it infers intent from file structure and metadata rather than brute-force reading content. In practice that means a query is matched against file paths and directory names first, and content is read only for the candidates that survive. The README's own examples make the mechanism concrete. Searching "router server" in next.js surfaced packages/next/src/server/lib/router-server.ts with a score of 220, while ripgrep returned files mentioning the two words separately. Searching "ScriptController" in chromium found script_controller.h and script_controller.cc, because the tool splits CamelCase without the user writing a regex. Searching "gpu" in tensorflow prioritized files under tensorflow/lite/delegates/gpu/, and the query "blink renderer core dom" resolved to third_party/blink/renderer/core/dom/README.md. Those are path-sequence matches, not semantic ones. The neural layer is opt-in: v1.0.25 added semantic reranking that uses local embeddings through transformers.js, invoked with the --semantic flag, to catch conceptually related code with no keyword overlap. Tree-sitter is used for structural queries, exposed as mantic goto UserService for a definition line and mantic references handleLogin for usages that respect .gitignore. Everything runs locally, which the README frames as zero data egress.
Installing the CLI and wiring the MCP server into an editor
The package is published to npm as mantic.sh, and the README's editor badges encode the MCP configuration directly. The Cursor and VS Code install links both resolve to a stdio server launched with npx, with the command npx and the arguments -y, mantic.sh@latest, server. If you are writing the config by hand, that is the shape to reproduce: type stdio, command npx, args ["-y", "mantic.sh@latest", "server"]. The README also links a separate setup guide for Claude Desktop and an AGENT_RULES.md file described as a copy-config resource for agent rules. Once the server is registered, queries run through the agent rather than the terminal. The semantic path costs more than the default: mantic "verify user" --semantic is the documented form, and because it loads a local embedding model through transformers.js, the first invocation has to fetch model weights before it can rank anything. Nothing in the supplied material states the size of that download, so treat the first-run latency as unmeasured here. Learned context is stored on disk at .mantic/search-patterns.json, recording which files solved previous queries. The README notes this file can be committed to git so a team shares the same patterns, which also means it is a file you should decide about deliberately rather than discover in a diff.
Where Mantic.sh is slower than ripgrep, by its own numbers
The README's benchmark table is unusually candid, and it should be read before anything else. On cal.com (9.7K files) Mantic took 0.288s against ripgrep's 0.121s. On next.js (25K files) it was 0.440s against 0.034s. On tensorflow (35K files) it was 0.550s against 0.022s. On chromium (481K files) it was 1.961s against 0.380s. Mantic wins on none of these rows on raw speed, and the README says so directly: slower than ripgrep and fzf on raw speed but prioritizes ranking. Caching helps, with the README reporting 4 to 17 percent improvement on a second run for most repos and modest improvement on chromium. The v1.0.25 release notes claim roughly 2x speedup over previous versions and sub-2-second scans of chromium's 481K files. Two caveats belong here. First, these are the maintainer's measurements on the maintainer's machine; no methodology, hardware or corpus is given in the supplied material. Second, if your task is exhaustive matching, such as finding every call site of a symbol across a monorepo, ranking is irrelevant and a slower tool is simply a slower tool. That is the clearest case where Mantic.sh is the wrong choice. Keep ripgrep for it.
Team memories, .gitignore handling and the non-git fallback
Two operational details matter more than they first appear. The first is .mantic/search-patterns.json. Because the README suggests committing it to share learned patterns across a team, the file becomes shared state with the same review questions as any other committed artifact: who wrote it, what queries it encodes, and whether stale patterns from a deleted module keep boosting paths that no longer exist. Nothing in the supplied material describes an eviction or expiry mechanism for those patterns, so treat growth of that file as unmanaged. The second is the fallback path for non-git directories. The v1.0.25 notes describe a safe fallback that scans allow-listed extensions when no repository is detected. That is a reasonable guard, but it also means behaviour differs between a git checkout and a plain directory: reference lookups that respect .gitignore have nothing to respect outside a repo. The release notes also list regex DoS protection for user inputs and command injection mitigations for the VS Code extension, which tells you the project treats untrusted query strings as a real input surface. Those are mitigations, not a security audit, and none of the supplied material includes an external review.
What you give up compared with an embedding-based retrieval stack
The obvious alternative for agent context retrieval is a vector index built over chunked source files, using a managed store or a self-hosted one. The difference in approach is worth stating plainly. A vector index embeds file contents, so it can match a query to code that shares no tokens with it, and it pays for that with an ingestion pipeline, a store to run, and a re-embedding pass every time the code changes. Mantic.sh reads structure and metadata first and only reaches for embeddings when you pass --semantic, which keeps the index-free default path cheap and means there is no separate store to keep in sync with the working tree. The README's cost table frames this as a privacy and spend argument, listing Mantic at $0 against estimated ranges of $1,680 to $10,950 for a do-it-yourself vector setup and $46,800 or more for SaaS alternatives, for a team of 100 developers running 100 searches a day. Those competitor figures are the project's estimates, not measured costs, and the comparison assumes the local compute is free. The honest trade is that a vector index answers conceptual queries better on the first try, while Mantic.sh answers structural queries without any ingestion step at all. If your queries are mostly "where is this symbol defined" and "which files implement this feature", the structure-first path is the shorter route.
Licence, maintenance and what a version bump costs you
Mantic.sh moved to MIT at v1.0.26, released 2026-07-13, with the release title stating the change explicitly. Earlier versions carried a different licence, so if you vendored or pinned anything before v1.0.26, check which terms applied to the version you actually installed. This is a factual note about the version history, not legal advice; if the licence change matters to your organisation, read the LICENSE file at the tag you depend on. Maintenance cost is low by construction. There is no server to operate and no index to rebuild, because the default path scans the working tree on each query. The recurring cost is the dependency surface: npx pulls the package and its transitive dependencies, and the semantic path pulls embedding model weights on first use. The README's install links use mantic.sh@latest, which means an editor config written that way will silently track new releases. Pinning the version in your MCP config is the one change that turns an unpredictable upgrade into a deliberate one. The changelog is linked from the README and is where the v1.0.21, v1.0.25 and v1.0.26 changes are documented.
Editorial conclusion
Adopt Mantic.sh if your agent or editor workflow keeps surfacing the wrong files and you want a local MCP server that ranks by path structure, with ripgrep left in place for exhaustive text matches. Skip it if you need the fastest possible scan on huge trees, since the README's own table shows ripgrep returning results in 0.022s on tensorflow where Mantic takes 0.550s. Before rolling it out, verify three things on your own repository: that .mantic/search-patterns.json is either committed deliberately or added to .gitignore, that the semantic flag has already pulled the transformers.js model so the first query is not stalled by a download, and that the MCP entry in your editor config points at a pinned version rather than mantic.sh@latest.
Community notes