{"id":48589721,"url":"https://github.com/sverklo/sverklo","last_synced_at":"2026-04-14T20:00:49.659Z","repository":{"id":349597403,"uuid":"1203034717","full_name":"sverklo/sverklo","owner":"sverklo","description":"Sverklo — code intelligence for AI agents. Local-first semantic search, PageRank ranking, zero config.","archived":false,"fork":false,"pushed_at":"2026-04-08T18:25:59.000Z","size":333,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T19:27:07.186Z","etag":null,"topics":["ai-agents","ai-coding","antigravity","ast","bm25","claude-code","code-intelligence","code-search","cursor","developer-tools","embeddings","local-first","mcp","mcp-server","model-context-protocol","onnx","pagerank","rag","refactor","semantic-search"],"latest_commit_sha":null,"homepage":"https://sverklo.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sverklo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T16:51:31.000Z","updated_at":"2026-04-08T18:26:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sverklo/sverklo","commit_stats":null,"previous_names":["sverklo/sverklo"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/sverklo/sverklo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverklo%2Fsverklo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverklo%2Fsverklo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverklo%2Fsverklo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverklo%2Fsverklo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sverklo","download_url":"https://codeload.github.com/sverklo/sverklo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverklo%2Fsverklo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31812977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","antigravity","ast","bm25","claude-code","code-intelligence","code-search","cursor","developer-tools","embeddings","local-first","mcp","mcp-server","model-context-protocol","onnx","pagerank","rag","refactor","semantic-search"],"created_at":"2026-04-08T19:00:45.023Z","updated_at":"2026-04-14T20:00:49.653Z","avatar_url":"https://github.com/sverklo.png","language":"TypeScript","readme":"# Sverklo\n\n_Sverklo_ (Russian: **сверкло**, _SVERK-lo_) — archaic past tense of \"сверкнуть,\" to flash or gleam. Code intelligence that illuminates your repo so your AI assistant stops guessing.\n\n[![npm version](https://img.shields.io/npm/v/sverklo.svg?color=E85A2A)](https://www.npmjs.com/package/sverklo)\n[![npm downloads](https://img.shields.io/npm/dw/sverklo.svg?color=E85A2A)](https://www.npmjs.com/package/sverklo)\n[![GitHub stars](https://img.shields.io/github/stars/sverklo/sverklo?style=flat\u0026color=E85A2A)](https://github.com/sverklo/sverklo)\n[![License: MIT](https://img.shields.io/badge/license-MIT-E85A2A.svg)](LICENSE)\n[![Local-first](https://img.shields.io/badge/local--first-no%20cloud-E85A2A)](#)\n\n\u003e **MIT Licensed** — the only fully open-source code intelligence MCP. Free for commercial use, no restrictions. [Compare with alternatives →](#why-not-as-of-2026-04)\n\n[![Star History Chart](https://api.star-history.com/svg?repos=sverklo/sverklo\u0026type=Date)](https://star-history.com/#sverklo/sverklo\u0026Date)\n\n## Stop re-explaining your codebase to your AI.\n\nSverklo 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.\n\n### The problem\n\nYour 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.\n\nSverklo gives your agent the dependency graph, the blast radius, and the risk score — before it writes a single line.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003e20\u003c/b\u003e\u003cbr/\u003etools your agent actually uses\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003e\u0026lt; 2 s\u003c/b\u003e\u003cbr/\u003eto index a 1,700-file monorepo\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003e0 bytes\u003c/b\u003e\u003cbr/\u003eof your code leave your machine\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n```bash\nnpm install -g sverklo\ncd your-project \u0026\u0026 sverklo init\n```\n\n`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.\n\n### Works with every MCP editor\n\n| Editor | MCP | Skills | Hooks | Auto-setup |\n|--------|:---:|:------:|:-----:|:----------:|\n| Claude Code | ✓ | ✓ | ✓ | `sverklo init` |\n| Cursor | ✓ | — | — | `sverklo init` |\n| Windsurf | ✓ | — | — | `sverklo init` |\n| Zed | ✓ | — | — | `sverklo init` |\n| VS Code | ✓ | — | — | manual |\n| JetBrains | ✓ | — | — | manual |\n| Antigravity | ✓ | — | — | `sverklo init` |\n| OpenCode | ✓ | — | — | manual |\n\n\u003e **First 5 minutes:** see [`FIRST_RUN.md`](FIRST_RUN.md) for three scripted prompts that demonstrate the tools sverklo adds that grep can't replace.\n\n---\n\n## Grep vs Sverklo — the same question, side by side\n\nEvery 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.\n\n| The question | With Grep | With Sverklo |\n|---|---|---|\n| \"Where is auth handled in this repo?\" | `grep -r 'auth' .` → 847 matches across tests, comments, unrelated vars, and one 2021 TODO | `sverklo_search \"authentication flow\"` → top 5 files ranked by PageRank: middleware, JWT verifier, session store, login route, logout route |\n| \"Can I safely rename `BillingAccount.charge`?\" | `grep '\\.charge('` → 312 matches polluted by `recharge`, `discharge`, `Battery.charge` fixtures | `sverklo_impact BillingAccount.charge` → 14 real callers, depth-ranked, with file paths and line numbers |\n| \"Is this helper actually used anywhere?\" | `grep -r 'parseFoo' .` → 4 matches in 3 files. Are any real, or just string mentions? Read each one. | `sverklo_refs parseFoo` → 0 real callers. Zero. Walk the symbol graph, not the text. Delete the function. |\n| \"What's load-bearing in this codebase?\" | `find . -name '*.ts' \\| xargs wc -l \\| sort` → the biggest files. Not the most important ones. | `sverklo_overview` → PageRank over the dep graph. The files the rest of the repo depends on, not the ones someone wrote too much code in. |\n| \"Review this 40-file PR — what should I read first?\" | Read them in the order git diff printed them | `sverklo_review_diff` → risk-scored per file (touched-symbol importance × coverage × churn), prioritized order, flagged production files with no test changes |\n\nIf 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.\n\n---\n\n## When to reach for sverklo — and when not to\n\nWe'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.\n\n### The two tools that earn their keep every time\n\nIf you only remember two, remember these. They deliver value that plain text search structurally cannot:\n\n1. **`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.\n2. **`sverklo_audit`** — one structural pass that surfaces god classes, hub files, and suspicious concentrations of complexity without you having to guess the right regex.\n\n### When grep is still the right tool\n\nSverklo shines when **you don't know exactly what to search for**. When you do, grep is fine and we'll tell you so:\n\n- **Exact string matching** — \"does this literal string exist anywhere?\" → `Grep` is faster and more reliable.\n- **Reading file contents** — only `Read` does this. Sverklo isn't a file reader.\n- **Build and test verification** — only `Bash` runs `npm test` or `gradle check`.\n- **Focused single-file diffs** — for a signature change in one file, `git diff` + `Read` is hard to beat.\n- **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.\n\nIf a launch post tells you a tool is great for everything, close the tab.\n\n---\n\n## Twenty tools your agent actually uses\n\nGrouped by job. Every tool runs locally, every tool is free.\n\n### Search — find code without knowing the literal string\n| Tool | What |\n|------|------|\n| `sverklo_search` | Hybrid BM25 + ONNX vector + PageRank, fused with Reciprocal Rank Fusion |\n| `sverklo_overview` | Structural codebase map ranked by PageRank importance |\n| `sverklo_lookup` | Find any function, class, or type by name (typo-tolerant) |\n| `sverklo_context` | One-call onboarding — combines overview, code, and saved memories |\n| `sverklo_ast_grep` | Structural pattern matching across the AST, not just text |\n\n### Impact — refactor without the regression\n| Tool | What |\n|------|------|\n| `sverklo_impact` | Walk the symbol graph, return ranked transitive callers (the real blast radius) |\n| `sverklo_refs` | Find all references to a symbol, with caller context |\n| `sverklo_deps` | File dependency graph — both directions, importers and imports |\n| `sverklo_audit` | Surface god nodes, hub files, dead code candidates in one call |\n\n### Cross-repo impact analysis (v0.4.0+)\n\nLink multiple projects into a workspace and trace symbol impact across repo boundaries:\n\n```bash\n# Link multiple projects into a workspace\nsverklo workspace init myapp ./api ./frontend ./cms\n\n# Index cross-repo relationships\nsverklo workspace index myapp\n```\n\nThen ask your agent:\n\n```\nsverklo_impact symbol:\"User.email\" cross_repo:true\n```\n\nThis 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.\n\n### Review — diff-aware MR review with risk scoring\n| Tool | What |\n|------|------|\n| `sverklo_review_diff` | Risk-scored review of `git diff` — touched-symbol importance × coverage × churn |\n| `sverklo_test_map` | Which tests cover which changed symbols; flag untested production changes |\n| `sverklo_diff_search` | Semantic search restricted to the changed surface of a diff |\n\n### Memory — bi-temporal, git-aware, never stale\n| Tool | What |\n|------|------|\n| `sverklo_remember` | Save decisions, patterns, invariants — pinned to the current git SHA |\n| `sverklo_recall` | Semantic search over saved memories with staleness detection |\n| `sverklo_memories` | List all memories with health metrics (still valid / stale / orphaned) |\n| `sverklo_forget` | Delete a memory |\n| `sverklo_promote` / `sverklo_demote` | Move memories between tiers (project / global / archived) |\n\n### Index health\n| Tool | What |\n|------|------|\n| `sverklo_status` | Index health check, file counts, last update |\n| `sverklo_wakeup` | Warm the index after a long pause; incremental refresh |\n\n## Example prompts that showcase sverklo\n\nCopy-paste these into Claude Code, Cursor, or Windsurf on any indexed project. Each one exercises a tool that plain text search can't replicate.\n\n- **\"Find everything that would break if I rename `UserRepository.findActive`. Rank by depth, show me the riskiest 5 callers first.\"**\n- **\"Is `parseFoo` actually used anywhere in this repo, or is it dead code I can delete?\"**\n- **\"What are the top 10 most structurally important files in this codebase? Don't count test files.\"**\n- **\"Review the current git diff. What should I read first? Which changes touch untested production code?\"**\n- **\"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?\"**\n- **\"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.\"**\n- **\"What did we decide about rate limiting the public API? Check saved memories first, then the actual code.\"**\n\nIf 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).\n\n## Two ready-to-paste workflow prompts\n\nFor 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:\n\n```bash\nsverklo audit-prompt    # full codebase audit — 4-phase workflow\nsverklo review-prompt   # pull/merge request review with blast-radius analysis\n```\n\nPipe the output into `pbcopy` / `xclip` and paste into Claude Code, or save it to a file your agent can load.\n\n## How It Works\n\n```mermaid\ngraph LR\n    A[Your Code] --\u003e B[Parse\u003cbr/\u003e20+ languages]\n    B --\u003e C[Embed\u003cbr/\u003eONNX/Ollama]\n    B --\u003e D[Build Graph\u003cbr/\u003eimports/exports]\n    D --\u003e E[PageRank\u003cbr/\u003eimportance]\n    \n    F[Agent Query] --\u003e G[BM25]\n    F --\u003e H[Vector Search]\n    E --\u003e I[PageRank Boost]\n    G --\u003e J[RRF Fusion]\n    H --\u003e J\n    I --\u003e J\n    J --\u003e K[Token-Budgeted\u003cbr/\u003eResponse]\n```\n\n1. **Parses** your codebase into functions, classes, types (TS, JS, Python, Go, Rust, Java, C, C++, Ruby, PHP)\n2. **Embeds** code using all-MiniLM-L6-v2 ONNX model (384d, fully local) — or any Ollama model via config\n3. **Builds** a dependency graph and computes PageRank (structurally important files rank higher)\n4. **Searches** using hybrid BM25 + vector similarity + PageRank, fused via Reciprocal Rank Fusion\n5. **Remembers** decisions and patterns across sessions, linked to git state\n6. **Watches** for file changes and updates incrementally\n\n## Quick Start\n\n```bash\nnpm install -g sverklo\ncd your-project\nsverklo init\n```\n\nThis 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.\n\nIf sverklo doesn't appear in Claude Code's `/mcp` list after restart, run:\n```bash\nsverklo doctor\n```\nThis diagnoses MCP setup issues — checks the binary, the model, the config file location, the handshake, and tells you exactly what's wrong.\n\n### Cursor / Windsurf / VS Code\nThese IDEs use their own MCP config locations. Use the **full binary path** to avoid PATH resolution issues in spawned subprocesses:\n```json\n{\n  \"mcpServers\": {\n    \"sverklo\": {\n      \"command\": \"/full/path/to/sverklo\",\n      \"args\": [\".\"]\n    }\n  }\n}\n```\nFind the path with `which sverklo`. Add to:\n- **Cursor:** `.cursor/mcp.json`\n- **Windsurf:** `~/.windsurf/mcp.json`\n- **VS Code:** `.vscode/mcp.json`\n- **JetBrains:** Settings → Tools → MCP Servers\n\n### Google Antigravity\nAntigravity uses a **global** MCP config file (no per-project config — known limitation, see [Google forum](https://discuss.ai.google.dev/t/support-for-per-workspace-mcp-config-on-antigravity/111952)). `sverklo init` writes it for you if Antigravity is installed, otherwise edit the file by hand:\n\n`~/.gemini/antigravity/mcp_config.json` (Windows: `C:\\Users\\\u003cUSER\u003e\\.gemini\\antigravity\\mcp_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"sverklo\": {\n      \"command\": \"/full/path/to/sverklo\",\n      \"args\": [\"/absolute/path/to/your/project\"]\n    }\n  }\n}\n```\n\nRestart 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`).\n\n### Any MCP Client\n```bash\nnpx sverklo /path/to/your/project\n```\n\n### Dashboard\n```bash\nnpx sverklo ui .\n```\nOpens a web dashboard at `localhost:3847` — browse indexed files, search playground, memory viewer, dependency graph.\n\n\u003e **First run:** The ONNX embedding model (~90MB) downloads automatically. Takes ~30 seconds on first launch, then instant.\n\n## The web dashboard (`sverklo ui`)\n\nSverklo 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.\n\n```bash\nsverklo ui .\n```\n\nOpens `http://localhost:3847` in your browser. Everything runs locally — the dashboard reads straight from the SQLite index file at `~/.sverklo/\u003cproject-hash\u003e/index.db`. No cloud, no network calls, no server to stand up.\n\n![Sverklo dashboard showing the dependency graph view](./docs/dashboard.png)\n\nWhat you can see:\n\n- **Overview** — PageRank-ranked file list, language breakdown, chunk count, memory health\n- **File browser** — every indexed file with its chunks (functions, classes, types), import graph (both directions), and PageRank score\n- **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.\n- **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.\n- **Memory viewer** — all saved memories, grouped by tier (core / archive), with their git SHAs, tags, and staleness flags\n- **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.\n\nThe 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.\n\nKeep 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.\n\n## Performance\n\nReal measurements on real codebases. Every number below is reproducible with one command:\n\n```bash\ngit clone https://github.com/sverklo/sverklo \u0026\u0026 cd sverklo\nnpm install \u0026\u0026 npm run build\nnpm run bench   # clones gin/nestjs/react, runs the full suite\n```\n\nFull methodology in [`BENCHMARKS.md`](./BENCHMARKS.md). The detailed on-disk format is documented in [`docs/index-format.md`](./docs/index-format.md).\n\n| Repo | Files | Cold index | Search p95 | Impact analysis | DB size |\n|---|---:|---:|---:|---:|---:|\n| [gin-gonic/gin](https://github.com/gin-gonic/gin) | 99 | 10 s | 12 ms | 0.75 ms | 4 MB |\n| [nestjs/nest](https://github.com/nestjs/nest) | 1,709 | 22 s | 14 ms | 0.88 ms | 11 MB |\n| [facebook/react](https://github.com/facebook/react) | 4,368 | 152 s | 26 ms | 1.18 ms | 67 MB |\n\n- **Search latency stays under 26 ms p95** even on a 4k-file React monorepo\n- **Impact analysis is sub-millisecond** on every repo we tested — it's an indexed SQL join, not a string scan\n- **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\n- **Steady-state RAM is ~200 MB** after indexing finishes. Peak during indexing is 400–700 MB while the embedder batches chunks\n- **Languages:** 10 (TS, JS, Python, Go, Rust, Java, C, C++, Ruby, PHP)\n- **Dependencies:** zero config, zero API keys, zero cloud calls (after the one-time ~90 MB ONNX model download)\n\n## Troubleshooting\n\nMost 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:\n\n**Sverklo doesn't appear in Claude Code's `/mcp` list after restart.**\n1. Confirm the binary is on PATH: `which sverklo` (should print an absolute path)\n2. Confirm `.mcp.json` exists at the project root: `cat .mcp.json`\n3. Fully quit and restart Claude Code (not just reload the window) — MCP configs are read once on startup\n4. Check the sverklo MCP log in Claude Code: `View → Output → Model Context Protocol`\n\n**`sverklo init` wrote a config but the agent still can't find it.**\n- Cursor / Windsurf / VS Code use their own MCP config paths. See [Cursor / Windsurf / VS Code](#cursor--windsurf--vs-code) below — the config goes in `.cursor/mcp.json`, `~/.windsurf/mcp.json`, or `.vscode/mcp.json` respectively, not `.mcp.json`.\n- Antigravity uses a **global** config at `~/.gemini/antigravity/mcp_config.json`. See [Google Antigravity](#google-antigravity).\n\n**\"Failed to start sverklo\" / the handshake fails.**\n- Confirm Node ≥ 20: `node --version`\n- Try running the server manually to see the error directly: `sverklo .`\n- Enable debug logging: `SVERKLO_DEBUG=1 sverklo .`\n- If the ONNX model download failed, re-run it: `sverklo setup`\n\n**Index feels wrong or stale.**\n- Check status: `sverklo doctor` or call `sverklo_status` in your agent\n- Force a rescan: delete the index at `~/.sverklo/\u003cproject-hash\u003e/` and restart the server\n- Large binary files are skipped by default (\u003e1 MB). If you need them indexed, override via `.sverkloignore`\n\n**Slow queries.**\n- `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.\n- Large codebases take time to cold-index — but after that, incremental updates should be \u003c10 ms per file event.\n\nStill stuck? File an issue with the output of `sverklo doctor` attached. We triage within a couple days.\n\n## Why not... (as of 2026-04)\n\n| Alternative | Local | OSS | Code search | Symbol graph | Memory | MR review | License | Cost |\n|---|---|---|---|---|---|---|---|---|\n| **Sverklo** | ✓ | ✓ MIT | ✓ hybrid + PageRank | ✓ | ✓ git-aware | ✓ risk-scored | MIT | $0 |\n| Built-in grep / Read | ✓ | ✓ | text only | ✗ | ✗ | ✗ | varies | $0 |\n| [Cursor's @codebase](https://docs.cursor.com/context/codebase-indexing) | ✗ cloud | ✗ | ✓ | partial | ✗ | ✗ | proprietary | with Cursor sub |\n| [Sourcegraph Cody](https://sourcegraph.com/cody) | ✗ cloud | ✗ source-available | ✓ | ✓ | ✗ | partial | source-available | $9–19/dev/mo |\n| [Continue.dev](https://continue.dev) | partial | ✓ | ✓ basic | ✗ | ✗ | ✗ | Apache 2.0 | $0 |\n| [Claude Context (Zilliz)](https://github.com/zilliztech/claude-context) | ✗ Milvus | ✓ | ✓ vector only | ✗ | ✗ | ✗ | MIT | $0 + Milvus |\n| [Aider repo-map](https://aider.chat/docs/repomap.html) | ✓ | ✓ | ✗ | ✓ basic | ✗ | ✗ | Apache 2.0 | $0 |\n| [Greptile](https://greptile.com) | ✗ cloud | ✗ | ✓ | ✓ | ✗ | ✓ | proprietary | $30/dev/mo |\n| [Augment](https://augmentcode.com) | ✗ cloud | ✗ | ✓ | ✓ | ✗ | partial | proprietary | $20–200/mo |\n| [claude-mem](https://github.com/themanojdesai/claude-mem) | ✓ | ✓ | ✗ | ✗ | ✓ ChromaDB | ✗ | MIT | $0 |\n\nSverklo is the only tool that combines **hybrid code search + symbol graph + memory + diff-aware review** in one local-first MCP server.\n\n## Configuration\n\n| Setting | Location |\n|---------|----------|\n| Model files | `~/.sverklo/models/` (auto-downloaded) |\n| Index database | `~/.sverklo/\u003cproject\u003e/index.db` |\n| Project config | `.sverklo.yaml` in project root |\n| Custom ignores | `.sverkloignore` in project root |\n| Debug logging | `SVERKLO_DEBUG=1` |\n\n### `.sverklo.yaml` (v0.3.0+)\n\nDrop a `.sverklo.yaml` in your project root to tune indexing and search behavior per-repo:\n\n```yaml\n# .sverklo.yaml — customize Sverklo's behavior\nweights:\n  - glob: \"src/core/**\"\n    weight: 2.0          # boost core modules in search ranking\n  - glob: \"src/generated/**\"\n    weight: 0.1          # suppress generated code\n  - glob: \"vendor/**\"\n    weight: 0.2\n\nignore:\n  - \"*.generated.ts\"\n  - \".next/**\"\n\nsearch:\n  defaultTokenBudget: 6000\n  budgets:\n    search: 8000\n    audit: 5000\n```\n\n**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.\n\n**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.\n\n### Pluggable embeddings (v0.5.0+)\n\nSwap the default MiniLM-L6-v2 for any Ollama embedding model:\n\n```yaml\n# .sverklo.yaml\nembeddings:\n  provider: ollama\n  ollama:\n    model: nomic-embed-text\n    baseUrl: http://localhost:11434\n```\n\nDimensions auto-detected from the first response. Falls back to bundled ONNX if Ollama isn't running.\n\n## CLI tools (v0.5.0+)\n\n### `sverklo review` — CI-friendly diff review\n\n```bash\nsverklo review --ci --fail-on high\n```\n\nRisk-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.\n\n### `sverklo audit` — codebase health report\n\n```bash\nsverklo audit --format html --open\n```\n\nGenerates a self-contained HTML report: god nodes, hub files, orphan detection, coupling analysis, language distribution. Dark theme, shareable artifact.\n\nFormats: `markdown` (default), `html`, `json`.\n\n### GitHub Action\n\nAutomated PR review on every pull request:\n\n```yaml\n# .github/workflows/sverklo-review.yml\nname: Sverklo Review\non: [pull_request]\njobs:\n  review:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n      - uses: sverklo/sverklo/action@main\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n          fail-on: high\n```\n\nPosts risk-scored review comments directly on PRs. Updates existing comments on subsequent pushes.\n\n## Telemetry\n\n**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.\n\nIf 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.\n\n**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.\n\nEvery 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/`](./telemetry-endpoint/), retention is 90 days, and the entire client implementation is one file under 250 lines at [`src/telemetry/index.ts`](./src/telemetry/index.ts).\n\nRead [`TELEMETRY.md`](./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`](./TELEMETRY_DESIGN.md).\n\n```bash\nsverklo telemetry status    # show current state\nsverklo telemetry enable    # opt in (interactive, prints schema first)\nsverklo telemetry disable   # opt out, permanent per machine\nsverklo telemetry log       # show every event that was sent\n```\n\n## Open Source, Open Core\n\nThe 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.\n\n**Sverklo Pro** (later this year) adds smart auto-capture of decisions, cross-project pattern learning, and larger embedding models.\n\n**Sverklo Team** (later this year) adds shared team memory and on-prem deployment.\n\nThe open-core line is **\"Pro adds new things, never gates current things.\"** Anything in the OSS server today stays in the OSS server forever.\n\n## Links\n\n- [Website](https://sverklo.com)\n- [npm](https://www.npmjs.com/package/sverklo)\n- [Issues](https://github.com/sverklo/sverklo/issues)\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsverklo%2Fsverklo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsverklo%2Fsverklo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsverklo%2Fsverklo/lists"}