sverklo/sverklo/sverklo-skill

Sverklo Code Intelligence Skill

Sverklo is a local-first code intelligence MCP server. It gives you a dependency graph, semantic search, blast-radius analysis, and risk-scored PR review — all running on the user's machine. No API keys, no cloud, no data leaves the laptop.

Setup (one time per project)

npm install -g sverklo
cd /path/to/project
sverklo init

sverklo init auto-detects the user's AI editor (Claude Code, Cursor, Windsurf, etc.), writes the MCP config, appends sverklo instructions to CLAUDE.md, and verifies the setup. Safe to re-run.

If something looks wrong after setup:

sverklo doctor

Once installed, sverklo tools appear as MCP tools prefixed with sverklo_. The index builds automatically on first use.

When to use Sverklo vs Grep vs Read

Use Sverklo when:

• You don't know exactly what to search for ("where is auth handled?")
• You need to understand importance or ranking ("what are the key files?")
• You need blast-radius analysis ("what breaks if I rename this?")
• You need to prove code is dead ("is this function actually called?")
• You're reviewing a diff and need risk scoring

Use Grep when:

• You need exact string matching ("does FEATURE_FLAG_X exist?")
• You know the literal identifier and just want its location

Use Read when:

• You need to see file contents (sverklo is not a file reader)

Skip sverklo for codebases under ~50 source files — the overhead doesn't pay off. Just read everything directly.

Tools Reference

1. sverklo_search — Semantic code search

Hybrid BM25 + vector + PageRank search. Use instead of Grep when you don't know the exact string.

sverklo_search query:"authentication middleware" top_k:5

Returns ranked code chunks with file paths, line numbers, and relevance scores. Results are ordered by structural importance (PageRank), not just text similarity.

When to reach for it: "Where is X handled?", "Find the code that does Y", any exploratory search where you'd otherwise grep for 10 different terms.

2. sverklo_impact — Blast-radius analysis

Walk the symbol graph and return all transitive callers, ranked by depth.

sverklo_impact symbol:"UserService.validate"

Returns every function and file that depends on the symbol, how deep the dependency chain goes, and a risk ranking. Essential before any rename, move, or signature change.

When to reach for it: Before refactoring, renaming, or deleting anything. "What breaks if I change this?"

3. sverklo_review_diff — Risk-scored PR review

Analyzes the current git diff and scores each changed file by risk: touched-symbol importance x test coverage x churn history.

sverklo_review_diff

Returns files sorted by risk, flags production changes with no corresponding test changes, identifies dangling references, and suggests what to read first.

When to reach for it: Reviewing any PR or diff. "What should I look at first?", "Are there untested changes?"

4. sverklo_audit — Codebase health scoring

One-call structural analysis that surfaces god classes, hub files, dead code candidates, and complexity hotspots.

sverklo_audit

Returns a health report with specific files and symbols flagged, grouped by issue type.

When to reach for it: Onboarding to a new codebase, planning a refactor, or answering "what's the scariest part of this repo?"

5. sverklo_remember / sverklo_recall — Persistent memory

Save decisions, patterns, and invariants pinned to the current git SHA. Recall them later with semantic search and staleness detection.

sverklo_remember content:"We use Postgres advisory locks instead of Redis for cross-worker mutexes — operational familiarity."

sverklo_recall query:"rate limiting strategy"

Memories survive across sessions. Stale memories (where the referenced code has changed) are flagged automatically.

When to reach for it: Recording architectural decisions, checking what was decided before, any context that should persist across coding sessions.

Other Useful Tools

These are available once sverklo is connected:

Example Workflows

Onboarding to a new codebase

1. sverklo_context — get the project overview, saved memories, and codebase map
2. sverklo_overview — see the most important files ranked by PageRank
3. sverklo_audit — identify god nodes, hub files, and dead code

Reviewing a PR

1. sverklo_review_diff — get risk-scored file analysis and dangling references
2. sverklo_impact on any high-risk symbols — see the full blast radius
3. sverklo_test_map — check which tests cover the changed code

Planning a safe refactor

1. sverklo_impact on the symbol — see all callers and the blast radius
2. sverklo_refs — find every reference with exact matching
3. sverklo_deps on the file — understand its dependency context
4. sverklo_test_map — identify which tests need updating

Example prompts that trigger sverklo tools

• "Find everything that would break if I rename UserRepository.findActive."
• "Is parseFoo actually used anywhere, or can I delete it?"
• "What are the top 10 most important files in this codebase?"
• "Review the current diff. What should I read first?"
• "I'm onboarding — give me a 5-minute mental model of this repo."
• "Save a decision: we chose X over Y because Z."
• "What did we decide about rate limiting? Check memories first."