Skip to content
Back to search

Mantic.sh

A structural code search engine for Al agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marcoaapfortes--mantic-sh/badge.svg)](/listings/marcoaapfortes--mantic-sh)

HTML

<a href="/listings/marcoaapfortes--mantic-sh"><img src="/api/listings/marcoaapfortes--mantic-sh/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

CLI Installation

**Quick Start** (no installation required):

npx mantic.sh@latest "your search query"

**New Commands**:

# Semantic Search (Neural Reranking)
npx mantic.sh@latest "verify user identity" --semantic

# Go to Definition
npx mantic.sh@latest goto "UserService"

# Find References
npx mantic.sh@latest references "handleLogin"

**From Source**:

git clone https://github.com/marcoaapfortes/Mantic.sh.git
cd Mantic.sh
npm install
npm run build
npm link

MCP Server Installation

Mantic works as an MCP (Model Context Protocol) server for Claude Desktop, Cursor, VS Code, and other MCP-compatible tools.

**One-Click Install:** - [Install in Cursor](https://cursor.com/en/install-mcp?name=mantic&config=eyJ0eXBlIjogInN0ZGlvIiwgImNvbW1hbmQiOiAibnB4IiwgImFyZ3MiOiBbIi15IiwgIm1hbnRpYy5zaEBsYXRlc3QiLCAic2VydmVyIl19) - [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=mantic&config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22mantic.sh%40latest%22%2C%20%22server%22%5D%7D)

**Manual Configuration** (for Claude Desktop or other MCP clients):

Add this to your MCP settings file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "mantic": {
      "command": "npx",
      "args": ["-y", "mantic.sh@latest", "server"]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 364 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Mantic.sh
  2. [![npm version](https://img.shields.io/npm/v/mantic.sh.svg?style=flat-square&color=CB3837)](https://www.npmjs.com/package/mantic.sh)
  3. [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=mantic&config=eyJ0eXBlIjogInN0ZGlvIiwgImNvbW1hbmQiOiAibnB4IiwgImFyZ3MiOiBbIi15IiwgIm1hbnRpYy5zaEBsYXRlc3QiLCAic2VydmVyIl19)
  4. [![Install in VS Code](https://img.shields.io/badge/VS%20Code-Install-007ACC?style=flat-square&logo=visual-studio-code&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mantic&config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22mantic.sh%40latest%22%2C%20%22server%22%5D%7D)
  5. [![Agent Rules](https://img.shields.io/badge/Agent%20Rules-Copy%20Config-8A2BE2?style=flat-square&logo=robot&logoColor=white)](https://github.com/marcoaapfortes/Mantic.sh/blob/main/AGENT_RULES.md)
  6. [![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-Setup%20Guide-D94F30?style=flat-square&logo=anthropic&logoColor=white)](#mcp-server-installation)
  7. ## Summary
  8. Mantic is a **context-aware code search engine** that prioritizes **relevance over raw speed**. After testing across 5 repositories (cal.com, next.js, tensorflow, supabase, chromium), it demonstrates **superior result quality** compared to grep/ripgrep, despite some trade-offs in speed for very large codebases.
  9. **Overall Assessment**: 4/5 - Excellent for AI agents, good for developers, needs speed optimization for 100K+ file repos.
  10. ## What's New in v1.0.25
  11. **Enterprise-Grade Context Infrastructure**
  12. - **Semantic Reranking (Hybrid Intelligence)**: Combines heuristic speed with neural understanding. Uses local embeddings (`transformers.js`) to find "conceptually relevant" code even without exact keyword matches.
  13. - Usage: `mantic "verify user" --semantic`
  14. - **Code Intelligence**: Deep understanding of your codebase structure using Tree-sitter.
  15. - **Go to Definition**: `mantic goto UserService` returns the exact line number across your entire monorepo.
  16. - **Find References**: `mantic references handleLogin` finds every usage, respecting `.gitignore`.
  17. - **Learned Context (Team Memories)**: Mantic now remembers which files solved previous queries. These patterns are saved locally (`.mantic/search-patterns.json`) and can be committed to git to share knowledge across your team.
  18. - **Python Support**: Now includes first-class support for Python imports in the dependency graph.
  19. - **Security & Stability**:
  20. - Regex DoS protection for user inputs.
  21. - Command injection mitigations for VS Code extension.
  22. - Safe fallback for non-git directories (scans allow-listed extensions).
  23. **Performance Update**: v1.0.25 is **~2x faster** than previous versions, scanning Chromium (481K files) in <2 seconds.
  24. **Tested on 481K files (Chromium) with 100% multi-repo accuracy.**
  25. See the [CHANGELOG](https://github.com/marcoaapfortes/Mantic.sh/blob/main/CHANGELOG.md) for detailed release notes.
  26. ## Table of Contents
  27. - [About the Project](#about-the-project)
  28. - [Proprietary vs Mantic](#proprietary-vs-mantic-cost-analysis)
  29. - [Performance Benchmarks](#performance-benchmarks)
  30. - [Accuracy & Relevance](#accuracy--relevance-analysis)
  31. - [Feature Comparison](#feature-comparison-matrix)
  32. - [Use Case Recommendations](#use-case-recommendations)
  33. - [Installation](#installation)
  34. - [CLI Installation](#cli-installation)
  35. - [MCP Server Installation](#mcp-server-installation)
  36. - [Usage](#usage)
  37. - [Agent Rules](#agent-rules-auto-pilot)
  38. - [How It Works](#how-it-works)
  39. - [License](#license)
  40. ## About the Project
  41. Mantic is an infrastructure layer designed to remove unnecessary context retrieval overhead for AI agents. It infers intent from file structure and metadata rather than brute-force reading content, enabling retrieval speeds faster than human reaction time.
  42. ### Key Benefits
  43. - **Speed**: Retrieval is consistently under 500ms for most repos, under 4s for massive monorepos (Chromium).
  44. - **Efficiency**: Reduces token usage by up to 63% by filtering irrelevant files before reading.
  45. - **Privacy**: Runs entirely locally with zero data egress.
  46. ### Proprietary vs Mantic (Cost Analysis)
  47. For a team of 100 developers performing 100 searches per day (approx. 3M searches/year):
  48. | Tool | Annual Cost (Est.) | Per-Search Cost | Privacy |
  49. |------|---|---|---|
  50. | **Mantic** | **$0** | **$0** | **Local-First** |
  51. | Vector Embeddings (DIY) | $1,680 - $10,950* | $0.0005 - $0.003 | Cloud |
  52. | SaaS Alternatives | $46,800+ | $0.015+ | Cloud |
  53. **Note**: *Mantic costs are zero. Vector/SaaS costs are estimates based on standard managed infrastructure (e.g. Pinecone/Weaviate managed pods + compute) or per-seat Enterprise licensing (e.g. GitHub Copilot Enterprise).*
  54. ## Performance Benchmarks
  55. ### Speed Comparison (Real-world queries)
  56. | Repository | Files | Query | Mantic v1.0.25 | ripgrep | fzf | Verdict |
  57. |------------|-------|-------|-----------------|---------|-----|--------|
  58. | **cal.com** | 9.7K | "stripe payment" | **0.288s** | 0.121s | 0.534s | Fast |
  59. | **next.js** | 25K | "router server" | **0.440s** | 0.034s | 0.049s | Fast |
  60. | **tensorflow** | 35K | "gpu" | **0.550s** | 0.022s | N/A | Fast |
  61. | **chromium** | 481K | "ScriptController" | **1.961s** | 0.380s | 0.336s | <2s (Massive) |
  62. **Speed Verdict**:
  63. - **Caching works well** for most repos (4-17% improvement on second run).
  64. - **Large repos (Chromium)** show modest but consistent improvements.
  65. - **Mantic is slower** than ripgrep/fzf on raw speed but prioritizes ranking.
  66. ## Accuracy & Relevance Analysis
  67. ### Major Strengths
  68. #### 1. Exact Path Matching
  69. - **Query**: `"router server"` in next.js
  70. - **Mantic**: Found `packages/next/src/server/lib/router-server.ts` (Score: 220)
  71. - **ripgrep**: Found files mentioning "router" and "server" separately (many false positives)
  72. - **Verdict**: Mantic found the **exact file** that matches the intent.
  73. #### 2. CamelCase Detection
  74. - **Query**: `"ScriptController"` in chromium
  75. - **Mantic**: Found `script_controller.h`, `script_controller.cc` (Score: 200)
  76. - **ripgrep**: Requires manual regex `script.*controller`
  77. - **Verdict**: Mantic's CamelCase detection is **production-ready**.
  78. #### 3. Directory Boosting for Acronyms
  79. - **Query**: `"gpu"` in tensorflow
  80. - **Mantic**: Prioritized files in `tensorflow/lite/delegates/gpu/`
  81. - **Verdict**: Mantic correctly prioritizes **structural relevance**.
  82. #### 4. Path Sequence Matching
  83. - **Query**: `"blink renderer core dom"` in chromium
  84. - **Mantic**: Found `third_party/blink/renderer/core/dom/README.md`
  85. - **Verdict**: Mantic matches multi-term path queries perfectly.
  86. ## Feature Comparison Matrix
  87. | Feature | Mantic | ripgrep | ag | fzf |
  88. |---------|--------|---------|----|-----|
  89. | **Text Search Speed** | 2-10x slower | Fastest | Slow (large repos) | Very Fast |
  90. | **Relevance Ranking** | **Excellent** | None | None | Basic |
  91. | **Path Structure Awareness** | **Perfect** | None | None | Partial |
  92. | **CamelCase Detection** | **Yes** | No | No | No |
  93. | **Exact Filename Matching** | **Yes** | No | No | Yes |
  94. | **Multi-Word Queries** | **Semantic** | Regex needed | Regex needed | AND logic |
  95. | **Go to Definition** | **Yes (Cross-Repo)** | No | No | No |
  96. | **Find References** | **Yes** | No | No | No |
  97. | **Impact Analysis** | **Yes** | No | No | No |
  98. | **Zero-Query Mode** | **Yes** | No | No | No |
  99. ## Use Case Recommendations
  100. ### Best For
  101. 1. **AI Agents** (Context-aware search with metadata)
  102. 2. **Finding Files by Intent** ("Where is payment code?")
  103. 3. **Understanding Code Structure** (Path sequence queries)
  104. 4. **Code Reviews** (Impact analysis shows blast radius)
  105. ### Not Ideal For
  106. 1. **Quick Text Searches** ("Find all TODOs" -> Use ripgrep)
  107. 2. **Very Large Repos (100K+)** (Speed tradeoff: 4s vs 0.3s)
  108. 3. **Exact String Matching** (Use ripgrep with -F)
  109. 4. **Interactive File Browsing** (Use fzf)
  110. ## Installation
  111. ### CLI Installation
  112. **Quick Start** (no installation required):
  113. ```bash
  114. npx mantic.sh@latest "your search query"
  115. ```
  116. **New Commands**:
  117. ```bash
  118. # Semantic Search (Neural Reranking)
  119. npx mantic.sh@latest "verify user identity" --semantic
  120. # Go to Definition
  121. npx mantic.sh@latest goto "UserService"
  122. # Find References
  123. npx mantic.sh@latest references "handleLogin"
  124. ```
  125. **From Source**:
  126. ```bash
  127. git clone https://github.com/marcoaapfortes/Mantic.sh.git
  128. cd Mantic.sh
  129. npm install
  130. npm run build
  131. npm link
  132. ```
  133. ### MCP Server Installation
  134. Mantic works as an MCP (Model Context Protocol) server for Claude Desktop, Cursor, VS Code, and other MCP-compatible tools.
  135. **One-Click Install:**
  136. - [Install in Cursor](https://cursor.com/en/install-mcp?name=mantic&config=eyJ0eXBlIjogInN0ZGlvIiwgImNvbW1hbmQiOiAibnB4IiwgImFyZ3MiOiBbIi15IiwgIm1hbnRpYy5zaEBsYXRlc3QiLCAic2VydmVyIl19)
  137. - [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=mantic&config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22mantic.sh%40latest%22%2C%20%22server%22%5D%7D)
  138. **Manual Configuration** (for Claude Desktop or other MCP clients):
  139. Add this to your MCP settings file:
  140. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  141. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  142. ```json
  143. {
  144. "mcpServers": {
  145. "mantic": {
  146. "command": "npx",
  147. "args": ["-y", "mantic.sh@latest", "server"]
  148. }
  149. }
  150. }
  151. ```
  152. ## Usage
  153. ### Basic Search
  154. Find files matching your intent:
  155. ```bash
  156. mantic "stripe payment integration"
  157. ```
  158. *Returns JSON with ranked files, confidence scores, and token estimates.*
  159. ### Advanced Usage
  160. **Zero-Query Mode** (proactive context):
  161. ```bash
  162. mantic ""
  163. # Shows modified files, related dependencies, impact analysis
  164. ```
  165. **Context Carryover** (session mode):
  166. ```bash
  167. mantic "auth logic" --session my-task
  168. # Previously viewed files get +150 boost
  169. ```
  170. **Impact Analysis**:
  171. ```bash
  172. mantic "payment processing" --impact
  173. # Shows blast radius and dependents
  174. ### Session Management (CLI)
  175. You can manage sessions directly from the terminal to persist context across multiple runs:
  176. ```bash
  177. # Start a named session with an intent
  178. mantic session start my-feature --intent "implement payment webhook"
  179. # List all active sessions
  180. mantic session list
  181. # Get detailed info (viewed files, query history)
  182. mantic session info <sessionId>
  183. # End a session
  184. mantic session end <sessionId>
  185. ```
  186. ```
  187. ### CLI Options
  188. ```bash
  189. mantic <query> [options]
  190. Options:
  191. --code Only search code files (.ts, .js, etc)
  192. --config Only search config files
  193. --test Only search test files
  194. --json Output as JSON (default, includes metadata)
  195. --files Output as newline-separated file paths
  196. --markdown Pretty terminal output
  197. --impact Include dependency analysis and blast radius
  198. --session <id> Use session for context carryover
  199. --path <dir> Restrict search to specific directory
  200. --include-generated Include generated files (.lock, dist/, etc)
  201. --quiet, -q Minimal output mode
  202. --semantic Enable neural reranking (slower, but "smarter")
  203. ```
  204. **Code Intelligence Commands**:
  205. ```bash
  206. mantic goto <symbol> # Find definition of a symbol
  207. mantic references <symbol> # Find all usages of a symbol
  208. ```
  209. ### MCP Tools
  210. When using Mantic through MCP (Claude Desktop, Cursor):
  211. - `search_files` - Primary search (supports `semantic: true` for neural reranking)
  212. - `get_definition` - Go to definition of a symbol
  213. - `find_references` - Find usages of a symbol
  214. - `get_context` - Zero-query mode for proactive context
  215. - `session_start/end` - Manage coding sessions
  216. - `session_record_view` - Track viewed files
  217. - `session_list/info` - View session history
  218. - `analyze_intent` - Understand query intent
  219. ## Agent Rules (Auto-Pilot)
  220. Want Cursor or Claude to use Mantic automatically?
  221. 1. Copy the [Agent Rules](AGENT_RULES.md).
  222. 2. Paste them into your AI tool's system prompt or "Rules for AI" section.
  223. 3. The Agent will now automatically use `mantic` to find context before writing code.
  224. ## How It Works
  225. ### Architecture Overview
  226. ```
  227. User Query
  228. ↓
  229. Intent Analyzer (categorizes: UI/backend/auth/etc)
  230. ↓
  231. Brain Scorer (ranks files using metadata)
  232. ↓
  233. File Classifier (filters by type: code/config/test)
  234. ↓
  235. Impact Analyzer (calculates blast radius)
  236. ↓
  237. Output (JSON/Files/Markdown/MCP)
  238. ```
  239. ### Core Algorithm (v1.0.21)
  240. 1. **Intent Recognition**: Analyzes query to determine code category (e.g., "auth", "ui")
  241. 2. **File Enumeration**: Uses `git ls-files` for tracked files (significantly faster than traversals)
  242. 3. **Normalization & Matching**:
  243. - **CamelCase detection**: "ScriptController" -> "script controller" for matching
  244. - **Word-boundary matching**: "script" won't match "javascript"
  245. - **Path sequence matching**: Multi-term queries match consecutive path components
  246. - **Directory boosting**: Single-term queries prioritize files in matching directories
  247. 4. **Structural Scoring**: Ranks files based on:
  248. - **Exact filename match**: +10,000 points for perfect matches
  249. - **Path relevance**: `packages/features/payments` indicates high signal
  250. - **Filename matching**: `stripe.service.ts` > `stripe.txt`
  251. - **Business logic awareness**: `.service.ts` boosted over `.test.ts`
  252. - **Boilerplate penalties**: `index.ts` or `page.tsx` ranked lower
  253. 5. **Progressive Disclosure**: Calculates metadata (size, tokens, confidence, timestamps)
  254. 6. **Context Carryover**: Applies +150 boost to session-viewed files
  255. 7. **Learning**: Caches successful patterns for future queries
  256. ## Configuration
  257. Mantic works out of the box with zero configuration for most projects.
  258. ### Environment Variables
  259. ```bash
  260. MANTIC_MAX_FILES=5000 # Maximum files to scan
  261. MANTIC_TIMEOUT=30000 # Search timeout in ms (default: 30000)
  262. MANTIC_IGNORE_PATTERNS=... # Custom glob patterns to ignore
  263. MANTIC_FUNCTION_SCAN_LIMIT=30 # Top files to scan for function names (default: dynamic, max 50)
  264. ```
  265. ## License
  266. Mantic.sh is released under the MIT License.
  267. You can use, copy, modify, merge, publish, distribute, sublicense, and sell
  268. copies of the software as long as the copyright notice and license text are
  269. included.
  270. See [LICENSE](LICENSE) for the full MIT terms.
  271. Note: earlier releases published under AGPL-3.0 remain available under the
  272. terms they were originally shipped with. The repository is MIT-licensed going
  273. forward.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.