Mantic

A structural code search engine for AI agents. Provides sub-500ms file ranking across massive codebases without embeddings, vector databases, or external dependencies.

What's New in v1.0.20

Scoped Search: Added --path argument to restrict matching to subdirectories (e.g., mantic "query" --path src) (Fixed #7).
Improved Scanner Stability: Fixed crashes on empty search results or complex queries (e.g., Chinese characters) (Fixed #2).
Windows / VS Code Support: Resolved MCP server startup crashes by fixing CommonJS/ESM compatibility (Fixed #8, #1).

See the CHANGELOG for all the release notes.

About the Project
Proprietary vs Mantic
Features
Installation (CLI & MCP)
- CLI Installation
- MCP Server Installation
Usage
Agent Rules
Performance
How It Works
License

About the Project

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.

Key Benefits

Speed: Retrieval is consistently under 500ms, even for large repositories.
Efficiency: Reduces token usage by up to 63% by filtering irrelevant files before reading.
Privacy: Runs entirely locally with zero data egress.

Proprietary vs Mantic (Cost Analysis)

For a team of 100 developers performing 100 searches per day:

Tool	Annual Cost	Per-Search Cost	Privacy
Mantic	$0	$0	Local-First
Vector Embeddings	$10,950	$0.003	Cloud
SaaS Alternatives	$109,500	$0.003	Cloud

Features

Sub-500ms retrieval on large monorepos (Chromium: 480k files).
Zero external dependencies (no API keys, no databases).
Git-native file scanning (prioritizes tracked files).
Deterministic scoring (consistent, predictable results).
Native MCP support (works with Claude Desktop, Cursor).
Impact analysis (identifies potential blast radius of changes).

Installation

CLI Installation

Quick Start (no installation required):

# Run directly with npx
npx mantic.sh@latest "your search query"

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:

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"]
    }
  }
}

Restart Claude Desktop, and Mantic will be available as the search_codebase tool.

For IDE Users (Cursor/VS Code):

If you're using Mantic in an IDE rather than Claude Desktop, you can also add the Agent Rules to your IDE's system prompt or "Rules for AI" section. This teaches the AI to automatically use Mantic before writing code. (Note: Agent Rules are for IDEs only, not needed for Claude Desktop)

Usage

Basic Search

Find files matching your intent:

mantic "stripe payment integration"

Returns JSON with ranked files, confidence scores, and token estimates.

CLI Options

mantic <query> [options]

Options:
  --code          Only search code files (.ts, .js, etc)
  --config        Only search config files
  --test          Only search test files
  --json          Output as JSON (default)
  --files         Output as newline-separated file paths
  --impact        Include dependency analysis
  --session <id>  Use session for context carryover

Agent Rules (Auto-Pilot)

Want Cursor or Claude to use Mantic automatically?

Copy the Agent Rules.
Paste them into your AI tool's system prompt or "Rules for AI" section.
The Agent will now automatically use mantic to find context before writing code.

Performance

Latency Benchmarks (M1 Pro)

Codebase	Files	Size	Mantic	Vector Search	Improvement
Cal.com	9,621	~500MB	0.32s	0.85s	2.7x faster
Chromium	480,000	59GB	0.40s	5-10s	12-25x faster

How It Works

Architecture Overview

User Query
    ↓
Intent Analyzer (categorizes: UI/backend/auth/etc)
    ↓
Brain Scorer (ranks files using metadata)
    ↓
File Classifier (filters by type: code/config/test)
    ↓
Impact Analyzer (calculates blast radius)
    ↓
Output (JSON/Files/Markdown/MCP)

Core Algorithm

Intent Recognition: Analyzes query to determine code category (e.g., "auth", "ui").
File Enumeration: Uses git ls-files for tracked files (significantly faster than standard traversals).
Structural Scoring: Ranks files based on:
- Path relevance: packages/features/payments indicates high signal.
- Filename matching: stripe.service.ts > stripe.txt.
- Business logic awareness: .service.ts boosted over .test.ts.
- Boilerplate penalties: index.ts or page.tsx ranked lower to reduce noise.
Confidence Scoring: Assigns a relevance score to each result.

Configuration

Mantic works out of the box with zero configuration for most projects.

Environment Variables

MANTIC_MAX_FILES=5000         # Maximum files to scan
MANTIC_TIMEOUT=30000          # Search timeout in ms (default: 30000)
MANTIC_IGNORE_PATTERNS=...    # Custom glob patterns to ignore
MANTIC_FUNCTION_SCAN_LIMIT=30 # Top files to scan for function names (default: dynamic, max 50)

License

Mantic.sh is Dual Licensed to support both open access and sustainable development.

1. AGPL-3.0 (Open Source & Internal Use)

Ideal for: Individuals, Internal Business Tools, Open Source Projects.

Free for internal use (e.g., using Mantic.sh CLI in your company's dev team).
Free for open source (integrating into other AGPL/GPL projects).
Requirement: If you distribute Mantic.sh (or a modified version) as part of your own application (e.g., embedding it in a proprietary IDE or SaaS), you must open-source your entire application under AGPL-3.0. For hosted services, users must have access to the modified source code.

2. Commercial License (Proprietary & Embedding)

Ideal for: Commercial IDEs, SaaS Platforms, Proprietary Products.

Embed Mantic.sh in proprietary software (e.g., VS Code forks, AI Agents, SaaS tools).
No open-source requirement (keep your source code private).
Support & Indemnification: Priority email support and legal indemnification included.

Pricing:

Internal Use: Free (under AGPL-3.0).
Commercial Integration: Contact for pricing (starts at $500/year, based on usage).

Enforcement: All derivatives must comply with AGPL-3.0 unless under a commercial license. Unauthorized copying or rewrites may violate copyright laws.

Contributing: To maintain the dual-license model, all contributors must sign a Contributor License Agreement (CLA) granting relicensing rights.

Contact: license@mantic.sh

See LICENSE for the full AGPL-3.0 terms.

Mantic.sh