Sverklo

Sverklo (Russian: сверкло, SVERK-lo) — archaic past tense of "сверкнуть," to flash or gleam. Code intelligence that illuminates your repo so your AI assistant stops guessing.

MIT Licensed — the only fully open-source code intelligence MCP. Free for commercial use, no restrictions. Compare with alternatives →

Stop re-explaining your codebase to your AI.

Sverklo is a local-first code intelligence MCP server that gives Claude Code, Cursor, Windsurf, VS Code, JetBrains, and Google Antigravity the same mental model of your repo that a senior engineer has. Hybrid semantic search, symbol-level blast-radius analysis, diff-aware PR review, and memory pinned to git state — running entirely on your laptop.

The problem

Your AI agent edits UserService.validate(). It doesn't know that 47 other functions call it. Breaking changes ship. Tests pass because they mock the dependency.

Sverklo gives your agent the dependency graph, the blast radius, and the risk score — before it writes a single line.

npm install -g sverklo
cd your-project && sverklo init

sverklo init auto-detects your installed AI coding agents, writes the right MCP config files, appends sverklo instructions to your CLAUDE.md, and runs sverklo doctor to verify the setup. MIT licensed. Zero config. No API keys.

Works with every MCP editor

First 5 minutes: see FIRST_RUN.md for three scripted prompts that demonstrate the tools sverklo adds that grep can't replace.

Grep vs Sverklo — the same question, side by side

Every one of these is a query a real engineer asked a real AI assistant last week. Grep gives you lines. Sverklo gives you a ranked answer.

If the answer to your question is "exact string X exists somewhere," grep wins. Use grep. If the answer is "which 5 files actually matter here, ranked by the graph," you need sverklo.

When to reach for sverklo — and when not to

We're honest about this. Sverklo isn't a magic 5× speedup and it doesn't replace grep. It's a sharper tool for specific jobs.

The two tools that earn their keep every time

If you only remember two, remember these. They deliver value that plain text search structurally cannot:

1. sverklo_refs — proves dead code with certainty (zero references across the whole symbol graph, not just the files grep happened to scan) and answers "is this actually used anywhere?" in one call.
2. sverklo_audit — one structural pass that surfaces god classes, hub files, and suspicious concentrations of complexity without you having to guess the right regex.

When grep is still the right tool

Sverklo shines when you don't know exactly what to search for. When you do, grep is fine and we'll tell you so:

• Exact string matching — "does this literal string exist anywhere?" → Grep is faster and more reliable.
• Reading file contents — only Read does this. Sverklo isn't a file reader.
• Build and test verification — only Bash runs npm test or gradle check.
• Focused single-file diffs — for a signature change in one file, git diff + Read is hard to beat.
• Small codebases (under ~50 source files) — the indexing and MCP roundtrip overhead doesn't pay off at that size. Just read everything. Sverklo starts earning its keep around 100+ files and really shines above 500.

If a launch post tells you a tool is great for everything, close the tab.

Twenty tools your agent actually uses

Grouped by job. Every tool runs locally, every tool is free.

Search — find code without knowing the literal string

Impact — refactor without the regression

Cross-repo impact analysis (v0.4.0+)

Link multiple projects into a workspace and trace symbol impact across repo boundaries:

# Link multiple projects into a workspace
sverklo workspace init myapp ./api ./frontend ./cms

# Index cross-repo relationships
sverklo workspace index myapp

Then ask your agent:

sverklo_impact symbol:"User.email" cross_repo:true

This walks the symbol graph across all linked repos and returns the full blast radius — which API routes, frontend components, and CMS templates touch User.email, ranked by depth. Currently GraphQL-first (schema stitching and federation are resolved automatically). REST/OpenAPI support is next.

Review — diff-aware MR review with risk scoring

Memory — bi-temporal, git-aware, never stale

Index health

Example prompts that showcase sverklo

Copy-paste these into Claude Code, Cursor, or Windsurf on any indexed project. Each one exercises a tool that plain text search can't replicate.

• "Find everything that would break if I rename UserRepository.findActive. Rank by depth, show me the riskiest 5 callers first."
• "Is parseFoo actually used anywhere in this repo, or is it dead code I can delete?"
• "What are the top 10 most structurally important files in this codebase? Don't count test files."
• "Review the current git diff. What should I read first? Which changes touch untested production code?"
• "I'm onboarding to this repo. Give me a 5-minute mental model: what are the god classes, what are the hub files, what's dead?"
• "Save a decision: we use Postgres advisory locks instead of Redis for cross-worker mutexes because of our existing operational familiarity. Pin it to the current SHA."
• "What did we decide about rate limiting the public API? Check saved memories first, then the actual code."

If your agent isn't reaching for sverklo tools on prompts like these, check sverklo doctor or verify your CLAUDE.md has the sverklo section (re-run sverklo init — it's safe).

Two ready-to-paste workflow prompts

For deeper hybrid workflows, sverklo ships two battle-tested prompt templates you can paste into any agent. They encode the "prefer sverklo for discovery, fall back to grep for exact patterns" approach that consistently produces the best results:

sverklo audit-prompt    # full codebase audit — 4-phase workflow
sverklo review-prompt   # pull/merge request review with blast-radius analysis

Pipe the output into pbcopy / xclip and paste into Claude Code, or save it to a file your agent can load.

How It Works

graph LR
    A[Your Code] --> B[Parse<br/>20+ languages]
    B --> C[Embed<br/>ONNX/Ollama]
    B --> D[Build Graph<br/>imports/exports]
    D --> E[PageRank<br/>importance]
    
    F[Agent Query] --> G[BM25]
    F --> H[Vector Search]
    E --> I[PageRank Boost]
    G --> J[RRF Fusion]
    H --> J
    I --> J
    J --> K[Token-Budgeted<br/>Response]

1. Parses your codebase into functions, classes, types (TS, JS, Python, Go, Rust, Java, C, C++, Ruby, PHP)
2. Embeds code using all-MiniLM-L6-v2 ONNX model (384d, fully local) — or any Ollama model via config
3. Builds a dependency graph and computes PageRank (structurally important files rank higher)
4. Searches using hybrid BM25 + vector similarity + PageRank, fused via Reciprocal Rank Fusion
5. Remembers decisions and patterns across sessions, linked to git state
6. Watches for file changes and updates incrementally

Quick Start

npm install -g sverklo
cd your-project
sverklo init

This creates .mcp.json at your project root (the only file Claude Code reads for project-scoped MCP servers) and appends sverklo instructions to your CLAUDE.md. Safe to re-run.

If sverklo doesn't appear in Claude Code's /mcp list after restart, run:

sverklo doctor

This diagnoses MCP setup issues — checks the binary, the model, the config file location, the handshake, and tells you exactly what's wrong.

Cursor / Windsurf / VS Code

These IDEs use their own MCP config locations. Use the full binary path to avoid PATH resolution issues in spawned subprocesses:

{
  "mcpServers": {
    "sverklo": {
      "command": "/full/path/to/sverklo",
      "args": ["."]
    }
  }
}

Find the path with which sverklo. Add to:

• Cursor: .cursor/mcp.json
• Windsurf: ~/.windsurf/mcp.json
• VS Code: .vscode/mcp.json
• JetBrains: Settings → Tools → MCP Servers

Google Antigravity

Antigravity uses a global MCP config file (no per-project config — known limitation, see Google forum). sverklo init writes it for you if Antigravity is installed, otherwise edit the file by hand:

~/.gemini/antigravity/mcp_config.json (Windows: C:\Users\<USER>\.gemini\antigravity\mcp_config.json)

{
  "mcpServers": {
    "sverklo": {
      "command": "/full/path/to/sverklo",
      "args": ["/absolute/path/to/your/project"]
    }
  }
}

Restart Antigravity after editing. To verify, open the side panel → MCP Servers → Manage MCP Servers — sverklo should appear in the list. Because the config is global, if you work on multiple projects you'll need to either re-run sverklo init from each (it rewrites the path) or run a separate sverklo instance per project under different keys (sverklo-projA, sverklo-projB).

Any MCP Client

npx sverklo /path/to/your/project

Dashboard

npx sverklo ui .

Opens a web dashboard at localhost:3847 — browse indexed files, search playground, memory viewer, dependency graph.

First run: The ONNX embedding model (~90MB) downloads automatically. Takes ~30 seconds on first launch, then instant.

The web dashboard (sverklo ui)

Sverklo ships with a local web dashboard that gives you a visual window into the index the MCP tools work against. It's the fastest way to verify the index looks right, explore the structural graph of an unfamiliar codebase, or audit saved memories.

sverklo ui .

Opens http://localhost:3847 in your browser. Everything runs locally — the dashboard reads straight from the SQLite index file at ~/.sverklo/<project-hash>/index.db. No cloud, no network calls, no server to stand up.

What you can see:

• Overview — PageRank-ranked file list, language breakdown, chunk count, memory health
• File browser — every indexed file with its chunks (functions, classes, types), import graph (both directions), and PageRank score
• Search playground — run sverklo_search queries interactively and see the ranked hits, scores, and PageRank contribution side-by-side. Faster than typing queries into your agent when you're debugging a failing search.
• Dependency graph — the whole repo's file-level dependency graph, nodes colored by language, sized by PageRank. Pan and zoom. The fastest way to find "the files that matter" in a repo you've never seen.
• Memory viewer — all saved memories, grouped by tier (core / archive), with their git SHAs, tags, and staleness flags
• Memory timeline — bi-temporal view showing invalidated memories alongside active ones, with the SHAs where each one was superseded. Click through to see which memory replaced which.

The dashboard is read-only — nothing you do here changes the index. Use the MCP tools from your AI agent for that. Think of the dashboard as the "inspect" view of the tools you're already using.

Keep it open in a tab alongside Claude Code or Cursor while you work. When a tool call returns a confusing result, click through to see exactly what the index thinks the codebase looks like.

Performance

Real measurements on real codebases. Every number below is reproducible with one command:

git clone https://github.com/sverklo/sverklo && cd sverklo
npm install && npm run build
npm run bench   # clones gin/nestjs/react, runs the full suite

Full methodology in BENCHMARKS.md. The detailed on-disk format is documented in docs/index-format.md.

• Search latency stays under 26 ms p95 even on a 4k-file React monorepo
• Impact analysis is sub-millisecond on every repo we tested — it's an indexed SQL join, not a string scan
• Cold-start indexing is linear in chunks (~7 ms/chunk on Apple Silicon). Pay it once per project; incremental refresh after that only re-processes changed files
• Steady-state RAM is ~200 MB after indexing finishes. Peak during indexing is 400–700 MB while the embedder batches chunks
• Languages: 10 (TS, JS, Python, Go, Rust, Java, C, C++, Ruby, PHP)
• Dependencies: zero config, zero API keys, zero cloud calls (after the one-time ~90 MB ONNX model download)

Troubleshooting

Most setup issues fall into one of five buckets. Run sverklo doctor first — it diagnoses 90 % of them automatically. If you still need to dig, here's the manual playbook:

Sverklo doesn't appear in Claude Code's /mcp list after restart.

1. Confirm the binary is on PATH: which sverklo (should print an absolute path)
2. Confirm .mcp.json exists at the project root: cat .mcp.json
3. Fully quit and restart Claude Code (not just reload the window) — MCP configs are read once on startup
4. Check the sverklo MCP log in Claude Code: View → Output → Model Context Protocol

sverklo init wrote a config but the agent still can't find it.

• Cursor / Windsurf / VS Code use their own MCP config paths. See Cursor / Windsurf / VS Code below — the config goes in .cursor/mcp.json, ~/.windsurf/mcp.json, or .vscode/mcp.json respectively, not .mcp.json.
• Antigravity uses a global config at ~/.gemini/antigravity/mcp_config.json. See Google Antigravity.

"Failed to start sverklo" / the handshake fails.

• Confirm Node ≥ 20: node --version
• Try running the server manually to see the error directly: sverklo .
• Enable debug logging: SVERKLO_DEBUG=1 sverklo .
• If the ONNX model download failed, re-run it: sverklo setup

Index feels wrong or stale.

• Check status: sverklo doctor or call sverklo_status in your agent
• Force a rescan: delete the index at ~/.sverklo/<project-hash>/ and restart the server
• Large binary files are skipped by default (>1 MB). If you need them indexed, override via .sverkloignore

Slow queries.

• npm run bench:latency runs the MCP roundtrip profiler against your current build and prints per-tool p50/p95. Use it to confirm whether the slowdown is in a specific tool or a system-wide cost.
• Large codebases take time to cold-index — but after that, incremental updates should be <10 ms per file event.

Still stuck? File an issue with the output of sverklo doctor attached. We triage within a couple days.

Why not... (as of 2026-04)

Sverklo is the only tool that combines hybrid code search + symbol graph + memory + diff-aware review in one local-first MCP server. GitNexus has the most stars (27.6k) but its PolyForm Noncommercial license prohibits commercial use — Sverklo is MIT, no restrictions.

Configuration

.sverklo.yaml (v0.3.0+)

Drop a .sverklo.yaml in your project root to tune indexing and search behavior per-repo:

# .sverklo.yaml — customize Sverklo's behavior
weights:
  - glob: "src/core/**"
    weight: 2.0          # boost core modules in search ranking
  - glob: "src/generated/**"
    weight: 0.1          # suppress generated code
  - glob: "vendor/**"
    weight: 0.2

ignore:
  - "*.generated.ts"
  - ".next/**"

search:
  defaultTokenBudget: 6000
  budgets:
    search: 8000
    audit: 5000

Weights are multiplicative on PageRank only — they don't affect BM25 or embedding scores. Range is 0.0 to 10.0, last matching glob wins. Use them to boost code you care about and suppress generated or vendored files without fully ignoring them.

Token budgets control how much context each tool returns per call. The defaults were raised in v0.3.0 (search: 8000, audit: 5000). Override them here or per-call via the budget parameter on any search tool.

Pluggable embeddings (v0.5.0+)

Swap the default MiniLM-L6-v2 for any Ollama embedding model:

# .sverklo.yaml
embeddings:
  provider: ollama
  ollama:
    model: nomic-embed-text
    baseUrl: http://localhost:11434

Dimensions auto-detected from the first response. Falls back to bundled ONNX if Ollama isn't running.

CLI tools (v0.5.0+)

sverklo review — CI-friendly diff review

sverklo review --ci --fail-on high

Risk-scored diff review from the terminal. Auto-detects PR ref in GitHub Actions (GITHUB_BASE_REF). Exit code 1 when the threshold is exceeded — use as a CI quality gate.

sverklo audit — codebase health report

sverklo audit --format html --open

Generates a self-contained HTML report: god nodes, hub files, orphan detection, coupling analysis, language distribution. Dark theme, shareable artifact.

Formats: markdown (default), html, json.

sverklo audit --badge — add a health grade to your README

sverklo audit --badge

Outputs a shields.io badge with your project's A–F health grade. Paste the markdown into your README:

The grade combines four dimensions: dead code %, circular dependencies, coupling (max fan-in), and security issues. Learn more →

GitHub Action

Automated PR review on every pull request:

# .github/workflows/sverklo-review.yml
name: Sverklo Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: sverklo/sverklo/action@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on: high

Posts risk-scored review comments directly on PRs. Updates existing comments on subsequent pushes.

Telemetry

Off by default. Sverklo ships zero telemetry until you explicitly run sverklo telemetry enable. If you never run that command, sverklo never makes a network call beyond the one-time embedding model download on first run.

If you do opt in, we collect 9 fields per event: a random install ID (generated locally), sverklo version, OS, Node major version, the event type (one of 17 fixed enum values), the tool name when applicable, the outcome (ok/error/timeout), and the duration in ms. Server-side we add a Unix timestamp.

We never collect: code, queries, file paths, symbol names, memory contents, git SHAs, branches, repo URLs, IP addresses, hostnames, error messages, language breakdowns, or anything else that could identify you or your codebase.

Every event is mirrored to ~/.sverklo/telemetry.log before the network call so you can tail -f it and see exactly what gets sent. The endpoint is a Cloudflare Worker we own at t.sverklo.com, the source lives in telemetry-endpoint/, retention is 90 days, and the entire client implementation is one file under 250 lines at src/telemetry/index.ts.

Read TELEMETRY.md for the full schema, the 17 event types, what we deliberately don't collect, and how to verify it. The design rationale and locked decisions are in TELEMETRY_DESIGN.md.

sverklo telemetry status    # show current state
sverklo telemetry enable    # opt in (interactive, prints schema first)
sverklo telemetry disable   # opt out, permanent per machine
sverklo telemetry log       # show every event that was sent

Open Source, Open Core

The full MCP server is free and open source (MIT). All 20 tools, no limits, no telemetry, no "free tier" — that's not where the line is.

Sverklo Pro (later this year) adds smart auto-capture of decisions, cross-project pattern learning, and larger embedding models.

Sverklo Team (later this year) adds shared team memory and on-prem deployment.

The open-core line is "Pro adds new things, never gates current things." Anything in the OSS server today stays in the OSS server forever.

Links

• Website
• npm
• Issues

License

MIT