Mantic.sh: a structural code search engine for AI agents

The problem Mantic.sh targets: agents reading too much code

A coding agent asked to change how a router handles a request usually starts by grepping. Grep returns every line containing the word, and the agent reads them. On a repository with 25,000 files, that is a lot of irrelevant context, and context is what the agent pays for. Mantic.sh's stated goal is to sit in front of that step and hand back a ranked list of files rather than a wall of matching lines.

The README frames this as an infrastructure layer: "Mantic is a context-aware code search engine that prioritizes relevance over raw speed." The audience is narrower than "developers who search code". It is teams running agents through the Model Context Protocol, plus developers who want the same ranking from a terminal. The repository ships both: a CLI binary and an MCP server, and the README links one-click install badges for Cursor and VS Code.

The project is TypeScript, licensed MIT as of v1.0.26, and published on npm as mantic.sh. The last push to the default branch was on 2026-07-13, the same day as the v1.0.26 release, so this is not a dormant repository, but the release cadence visible in the changelog is uneven: v1.0.21 in January 2026, v1.0.25 in January 2026, then v1.0.26 in July 2026.

How Mantic.sh ranks files: path structure, CamelCase and directory hints

The mechanism is scoring, not embedding search by default. Mantic walks the file tree, filters by allow-listed extensions when there is no git repository, and scores candidates on signals the README enumerates. A query term that matches a file path exactly scores highest: for "router server" in next.js, the README reports Mantic returning packages/next/src/server/lib/router-server.ts with a score of 220, where ripgrep returned files mentioning the two words separately. CamelCase queries are split, so "ScriptController" matches script_controller.h and script_controller.cc in Chromium without a hand-written regex. Acronym queries get directory boosting, which is why "gpu" in tensorflow surfaces files under tensorflow/lite/delegates/gpu/. Multi-term queries match path sequences, which is how "blink renderer core dom" lands on third_party/blink/renderer/core/dom/README.md.

Semantic reranking is opt-in. The README describes it as combining heuristic speed with local embeddings through transformers.js, invoked with mantic "verify user" --semantic. Nothing leaves the machine in either mode; the README states the tool runs entirely locally with zero data egress, and the dependency list backs that up with @xenova/transformers rather than a hosted embedding API.

Two features go beyond search. Code intelligence uses Tree-sitter to answer mantic goto UserService and mantic references handleLogin, with the README claiming goto returns "the exact line number across your entire monorepo". Learned context writes which files solved previous queries into .mantic/search-patterns.json, a local file the README says can be committed so a team shares the same patterns.

Installing Mantic.sh and running a first query

The package is on npm as mantic.sh, and package.json declares three binaries: mantic, mantic.sh and mantic-server. The README's MCP install badges invoke it through npx rather than a global install, which is the path of least resistance for an editor.

The global install gives you the CLI:

npm install -g mantic.sh

After that, mantic should be on your PATH. Run a query against the repository you are already standing in:

mantic "router server"

You get a ranked list of files with scores, not matching lines. The README's worked example is next.js, where the top hit is packages/next/src/server/lib/router-server.ts. If your query is conceptual rather than literal, add the semantic flag:

mantic "verify user" --semantic

The README does not document a --json output mode or a result-count flag, so if you need machine-readable output for a script, check mantic --help rather than assuming.

For an editor, the MCP server is the more useful entry point. The Cursor and VS Code badges encode a stdio server launched as npx -y mantic.sh@latest server, and the Claude Desktop setup guide is linked from the README under MCP Server Installation. If you are wiring it by hand, that is the shape to copy: command npx, args ["-y", "mantic.sh@latest", "server"]. The README does not spell out a manual JSON block for every client, so treat the badge config as the reference.

Where Mantic.sh is slower than ripgrep, and when that matters

The README publishes its own losing numbers, which is worth crediting. On next.js with 25,000 files and the query "router server", ripgrep finishes in 0.034s and Mantic in 0.440s. On tensorflow with 35,000 files and the query "gpu", ripgrep is 0.022s against 0.550s. That is roughly an order of magnitude on raw scan time, and the README says so plainly: "Mantic is slower than ripgrep/fzf on raw speed but prioritizes ranking."

The gap narrows in absolute terms on huge repositories, where both tools take long enough that the difference stops being perceptible: on Chromium with 481,000 files, Mantic reports 1.961s against ripgrep's 0.380s. The README's own assessment is 4/5 overall, with the caveat that the project "needs speed optimization for 100K+ file repos".

So the honest framing is that Mantic is the wrong tool when you want to know whether a string exists anywhere in a tree, when you are searching a repository of a few hundred files where ranking adds nothing, or when you are in a loop that runs search hundreds of times and every 400ms compounds. It is also the wrong tool if your agent already has good retrieval: adding a second ranking layer on top of an existing index is more moving parts for a marginal gain.

A second limitation is documentation depth. The README documents the scoring signals and the two code-intelligence commands, but it does not document rollback behaviour for the learned-context file, what happens when .mantic/search-patterns.json is committed and then diverges between branches, or how to disable the feature. The CHANGELOG is linked but its contents are not reproduced in the README.

Mantic.sh compared with ripgrep and hosted code-search services

The README's comparison table sets Mantic against ripgrep, ag and fzf. The difference is not speed but what the tool returns. Ripgrep is a line-oriented text matcher with no relevance ranking; if a file contains the term, ripgrep reports it, and ordering is a function of directory traversal. Mantic scores files on path shape, so a query like "router server" prefers a file literally named router-server.ts over a file that happens to contain both words in a comment. If you already use ripgrep with a hand-tuned glob and you know your repository well, Mantic is solving a problem you have already solved.

The second comparison is against hosted retrieval. The README's cost table contrasts Mantic at $0 per search against vector-embedding setups estimated at $1,680 to $10,950 per year and SaaS alternatives at $46,800 or more for a team of 100 developers doing 100 searches a day. Those competitor figures are the project's own estimates, not measured costs, and the README labels them as estimates based on managed infrastructure pricing. What is verifiable is the architectural difference: Mantic runs locally with no data egress, while a hosted index requires shipping code or embeddings to a third party. For teams that cannot send source to an external service, that is the deciding factor, and it holds regardless of whether the cost table is accurate.

Licence and upgrade cost after the MIT switch

v1.0.26 is titled "Now MIT Licensed", and package.json declares "license": "MIT", with a LICENSE file at the repository root. That matters if you evaluated an earlier version: anything before v1.0.26 shipped under different terms, so a dependency audit that pinned an older release will not match the current licence. The README does not reproduce the prior licence text, so if you need to know what changed, read the v1.0.26 release notes and the LICENSE file together.

Upgrade cost is low by construction. The package has seven runtime dependencies, all ordinary npm packages, and the CLI is a single TypeScript build (npm run build runs tsc). There is no database, no service to deploy and no migration step described in the README. The one piece of persistent state is .mantic/search-patterns.json, which the README says can be committed to git. That is the file to watch on upgrade: if the pattern format changes between versions, a committed file from an older release is the thing most likely to misbehave, and the README does not document a schema or a version field for it.

The semantic reranking path pulls in @xenova/transformers, which downloads model weights on first use. The README does not state where those weights are cached or how large they are, so if you are deploying into a network-restricted environment, verify that before relying on --semantic.

Editorial conclusion

Adopt Mantic.sh if you run an AI agent that currently burns tokens on grep output, or if you want path-structure ranking without sending code to a hosted index. Skip it if raw scan speed is your priority: the README's own table shows ripgrep returning results in 0.034s on next.js against 0.440s for Mantic on the same query. Before wiring it into an agent, run mantic "router server" on your largest repository and check the top result against what you would have opened by hand, then inspect .mantic/search-patterns.json to see what the learned-context feature recorded.

Frequently asked questions

Official sources

1. License: MIT
2. marcoaapfortes/Mantic.sh on GitHub
3. Project website
4. README
5. Releases