Skelpr

Surgical code retrieval for AI agents, PR reviews, and fixes — in a real agent A/B: 48% fewer tokens, 42% faster answers, and +16 accuracy points.

Every AI coding tool dumps whole files into the LLM context window: slow, expensive, and hallucination-prone. Skelpr is the surgical librarian — AST-aware parsing and hybrid search (lexical + vector + symbol graph) extract only the exact snippets an LLM needs to answer, review, patch, and validate, each carrying a precise file:line citation.

Table of contents

• ⚡ Measured impact
• 👀 See it in action
• Quick start
• Why Skelpr?
• Who it's for
• Two integration modes
• How it compares
• MCP integration
• Install
• Requirements
• Local models
• CLI commands
• FAQ
• Roadmap
• Development
• Docs
• Contributing
• License

---

⚡ Measured impact

Agent mode · MCP A/B: -48% agent tokens  ·  -42% wall-clock  ·  +16 accuracy points vs. native tools only

Self-reported benchmarks — full methodology in docs/BENCHMARK.md.

Agent mode · A/B: what happens to a real coding agent (MCP integration)

7 tasks x 2 arms (Antigravity · Gemini 3.6 Flash Medium + Skelpr MCP vs. native tools only) on the Sock Shop microservices demo:

• 🧠 Tokens: -48% (740k → 384k) — cache-read tokens, the biggest quota consumer, drop -61%
• ⚡ Wall-clock: -42% (301s → 175s) — one skelpr_search (avg 0.86s) replaces ~5 native file reads
• 🎯 Accuracy: +16 points (619 → 635) — including a +40 jump on the negative task (60 → 100), where search proves absence with a cited no-results answer

⚠️ The +16 accuracy swing is driven by the negative task's evaluator phrase match (60 → 100 — both answers are equally correct); on the other six tasks the WITH arm totals 535 vs 559. Token and time savings are unaffected. Per-task breakdown: docs/BENCHMARK.md.

📊 Suite totals, per-task tables, verbatim agent outputs, and the "run it yourself" guide: docs/BENCHMARK.md · 🔎 WITH vs WITHOUT, every answer side by side: docs/comparisons/COMP_ANTIGRAVITY.md

CLI mode · Reference: standalone CLI vs. naive full-repo dump

Model / Provider	Pipeline Strategy	Avg. Latency	Avg. Prompt Tokens	Avg. Cost / Query	Accuracy (0-10)	Payload Reduction	Cost Reduction
gemini-2.5-flash	Naive Full-Repo Dump	16.37s	122,710	$0.00935	8.7 / 10	Baseline	Baseline
	Agentic Multi-Turn	19.62s	7,491	$0.00076	8.7 / 10	93.9%	91.8%
	Skelpr Hybrid Engine	5.61s	2,474	$0.00021	9.0 / 10	98.0%	97.8%

⚠️ Baseline note: "Naive full-repo dump" is a worst-case reference — real users rarely paste an entire repository into a prompt. Treat these savings as an upper bound; realistic behavior is captured by the agent A/B above (per-task detail in docs/BENCHMARK.md).

👀 See it in action

Real output from the A/B harness (Sock Shop repo, 2026-09-09/10). The agent asks "does a 'recommendations' service exist?" — three searches, ~0.7s total, and it answers with a cited no:

$ skelpr_search "recommendation recommendations inventory service" --top-k 10

## Skelpr Search Results — 10 chunks

[GRAPH]    .skelpr/graphify/summary.txt:1-2                          architecture graph summary
[LEXICAL]  deploy/kubernetes/autoscaling/grafana-service.yaml:1-23   matched 1/4 terms, filename matches 'service'
[LEXICAL]  deploy/kubernetes/autoscaling/heapster-service.yaml:1-17  matched 1/4 terms, filename matches 'service'
[LEXICAL]  deploy/kubernetes/manifests/02-carts-svc.yml:1-5          ...

$ skelpr_search "recommendationservice inventoryservice recommendation inventory" --top-k 10

## Skelpr Search Results — 1 chunk

[GRAPH]    .skelpr/graphify/summary.txt:1-2                          architecture graph summary

Zero code defines a recommendations service — so the agent answers 100/100 on the negative task (it scored 60/100 without Skelpr). Full verbatim exchange: docs/BENCHMARK.md.

Quick start

Two things have to be running before the first run, and Skelpr cannot start either of them for you:

1. Docker Desktop, started and finished booting. skelpr setup talks to the daemon (docker info) to start Postgres and Qdrant and to build the sandbox image. If Docker Desktop is installed but not running, setup stops after step 1 and says so.
2. An embedding model server — LM Studio serving text-embedding-nomic-embed-text-v1.5 (GGUF, Q8_0, ~146 MB) on http://127.0.0.1:1234/v1. Without it, indexing still runs but vector recall degrades to a local hashing fallback. Steps: Local models.

cd <your-repo>

# 1. Start Docker services (Postgres + Qdrant + sandbox) — Docker Desktop must be up
skelpr setup

# 2. Configure LLM provider
skelpr init --gemini YOUR_KEY    # Google Gemini
skelpr init --openai sk-proj-..  # OpenAI
skelpr init --anthropic sk-ant-.. # Anthropic
skelpr init --openrouter YOUR_KEY # OpenRouter
skelpr init --groq gsk_...       # Groq
skelpr init --local              # Local model server

# 3. Index repository (AST chunking + hybrid indexing)
skelpr index

# 4. Query, review, or fix
skelpr ask "how does authentication token refresh work?"
skelpr review --diff origin/main...HEAD
skelpr fix --issue "ValueError in user_service.py on line 42" --apply
skelpr validate                   # Run sandboxed tests/lints
skelpr serve                      # Optional FastAPI server on :8080

Why Skelpr?

• Precision Over Volume — AST-aware chunking isolates exact functions, classes, and scopes, significantly reducing the lost-in-the-middle hallucination problem common with large context dumps.
• Minimal Token Payloads — Plug in premium cloud models (OpenAI, Anthropic) for massive enterprise repositories without runaway token costs, or run ultra-fast local models (Qwen, Gemma via LM Studio/vLLM) without hitting context limits.
• Grounded & Verifiable — Every output includes precise file:line citations. Edits are verified via sandboxed validation before applying.
• Enterprise-oriented — Multi-tenant architecture with row-level security, state consistency tracking, and AST-based patching for reliable code modifications.

Who it's for

• Local-first developers — run Qwen/Gemma entirely offline via LM Studio, vLLM, or Ollama: no API keys, no context-limit ceilings, no code leaving your machine.
• Teams on paid models — keep premium cloud LLMs for enterprise repos without runaway token bills, at the same or better accuracy.
• Agent power-users — give Claude Code, Cursor, Windsurf, or any MCP-compatible agent surgical, cited code access with one command.

Two integration modes

	Standalone Package	Agent (MCP)
What you get	Full ask/review/fix/validate pipeline	Surgical codebase access for your existing agent
LLM needed	Yes (your endpoint)	No (agent's LLM)
Commands	skelpr ask/fix/review/validate	Agent calls MCP tools
Retrieval	Skelpr (same engine)	Skelpr (same engine)
Reasoning	Your LLM via Skelpr	Agent's own LLM
Best for	Self-contained coding assistant	Enhancing Claude Code, Cursor, Windsurf, etc.

Standalone — Skelpr handles everything end to end: retrieval, context building, LLM calls, patching, and validation. Requires an LLM API key or local model server.

Agent (MCP) — Skelpr runs as a code-intelligence backend via the MCP protocol; the agent's LLM handles reasoning, so no LLM key is needed on the Skelpr side (local embeddings via LM Studio make it fully keyless).

🧩 Mode diagrams, the shared retrieval engine, and the fallback hierarchy: docs/ARCHITECTURE.md

How it compares

Instead of …	With Skelpr
Letting agents browse/read every file	-48% agent tokens, -42% wall-clock, +16 accuracy in agent A/B
Dumping the whole repo into context (worst-case baseline)	98% smaller payloads, ~3x faster, same or better accuracy
grep + clicking through files	One hybrid search returns the exact files, pre-ranked, with path:line citations
Embedding-only RAG	Deterministic-first fusion (lexical > symbol > graph > vector) — exact matches win, absence is provable, and paths are never hallucinated

MCP integration

The generic Skelpr MCP server exposes code intelligence to any MCP-compatible agent (Claude Code, Cursor, Windsurf, and more).

pip install ".[mcp]"
cd <your-repo>
skelpr setup          # one-time: verify deps (model endpoint, storage) + build sandbox image
skelpr init && skelpr index
skelpr install-mcp    # auto-detect agents, preflight check, write config

install-mcp auto-detects installed agents, warns before overwriting existing entries (--force to skip), and supports --project-level for repo-local config. Register custom agents with skelpr register-agent "<name>" <id> --cli <cmd> --global-config <path>.

Available MCP tools:

• skelpr_search — Hybrid code search (lexical + symbol + graph + vector); default top-5 chunks with 600-char snippets to keep agent context compact
• skelpr_get_context — Token-budgeted context for agent context windows (default 4000-token budget, top-8 chunks, full chunk text)
• skelpr_find_symbol / skelpr_dependencies — Symbol definition and location lookup; structural relationships and dependencies
• skelpr_validate — Run validation commands in isolated sandbox
• skelpr_apply_ast_patch — Optional AST-precise structural patching
• skelpr_health — System health and backend status

📚 Manual registration, project-level config, and troubleshooting: docs/MCP_SETUP.md

Install

pip install skelpr                        # from PyPI (recommended)
pip install "skelpr[postgres,vector,ast,server]"   # production backends
pip install "skelpr[mcp]"                 # MCP server support
pip install "skelpr[all]"                 # everything

# From source (contributors):
git clone https://github.com/skelpr-thrive360/skelpr.git && cd Skelpr
pip install -e ".[all]"                    # editable dev install
pip install -e ".[dev]"                    # + pytest/ruff/mypy

Not on PyPI yet? Install from source with the git clone above — the repository is public, so no access token is needed.

Requirements

Requirement	Needed for	Notes
Python ≥ 3.10	everything
git on PATH	diff / review / patch	degrades without it for index / ask
ripgrep	fast lexical search	recommended; pure-Python fallback otherwise
Docker Desktop, running	skelpr setup, sandboxed validate	Setup checks the daemon with docker info first. Start Docker Desktop before you run it — that one command starts Postgres 16 (port 5434) and Qdrant (6333/6334) and builds the skelpr-runner:latest sandbox image. Without Docker the core still runs end to end on in-memory fallbacks.
An embeddings server	skelpr index + vector retrieval, in both modes	LM Studio serving text-embedding-nomic-embed-text-v1.5 (GGUF Q8_0, ~146 MB) at http://127.0.0.1:1234/v1 is the default. Any OpenAI-compatible /v1/embeddings you host works.
A generation model server	ask / fix / review / chat (CLI mode)	LM Studio serving qwen2.5-14b-instruct, or a cloud provider key. Not needed in MCP mode — the agent brings its own model.

Local models

Skelpr speaks to any OpenAI-compatible server, and expects two different models for two different jobs:

Job	Model	Used by
Embeddings	text-embedding-nomic-embed-text-v1.5 — GGUF, Q8_0	skelpr index and vector retrieval — needed in both modes
Generation	qwen2.5-14b-instruct	ask / fix / review / chat — CLI mode only

1. The embedding model (required)

Non-vector retrieval works without it, and vector search degrades to a deterministic hashing embedder instead of failing — so a missing embedding server shows up as quietly worse recall, not as an error. Start it before you index.

LM Studio (what the default config points at):

1. Install LM Studio from https://lmstudio.ai.

2. In the model catalog, search nomic-embed-text-v1.5 (publisher nomic-ai) and download the Q8_0 GGUF build — the exact one the default targets:

   Field	Value
   Model	nomic-ai/nomic-embed-text-v1.5
   Format	GGUF
   Quantization	Q8_0
   Architecture	nomic-bert
   Domain	embedding
   Size on disk	~146 MB

3. Load the model, then start the local server (default port 1234) and confirm it answers:

   curl -s http://127.0.0.1:1234/v1/embeddings \
     -H 'Content-Type: application/json' \
     -d '{"input":["hello"],"model":"text-embedding-nomic-embed-text-v1.5@q8_0"}'
   

4. Keep the identifier in .skelpr.yaml matching what the server advertises. LM Studio puts the quantization in the model name, which is where the @q8_0 suffix comes from:

   embeddings:
     endpoint: http://127.0.0.1:1234/v1
     model: text-embedding-nomic-embed-text-v1.5@q8_0
   

Loading the model on another machine, a GPU box, or a vLLM/Ollama server you run elsewhere is supported — point embeddings.endpoint at it. skelpr index tells you which side you landed on:

INFO  Embedding server online at http://127.0.0.1:1234/v1/embeddings (dim=768)
WARNING  No local embedding server reachable at http://127.0.0.1:1234/v1; using hashing fallback

2. The generation model (CLI mode)

# LM Studio — load qwen2.5-14b-instruct and start the server on port 1234
# vLLM
vllm serve qwen2.5-14b-instruct --dtype auto --max-model-len 32768
# Ollama
ollama serve && ollama pull qwen2.5:14b

⚙️ Full LM Studio setup steps and the complete .skelpr.yaml reference: docs/CONFIGURATION.md

CLI commands

Core

• skelpr setup — Start Docker services (Postgres + Qdrant) and build the sandbox image
• skelpr init — Create .skelpr.yaml configuration
• skelpr index — Build/refresh hybrid knowledge base
• skelpr ask — Ask grounded questions about the repo
• skelpr chat — Interactive loop for ask/fix (no shell quoting needed)
• skelpr context — Export token-optimized context chunks to stdout
• skelpr review — Review a git diff and emit structured findings
• skelpr fix — Diagnose an issue and generate a minimal patch
• skelpr validate — Run configured test/lint/typecheck in sandbox
• skelpr serve — Start the local FastAPI server

MCP

• skelpr install-mcp / skelpr uninstall-mcp — Configure/remove the MCP server for detected agents
• skelpr register-agent — Register a custom MCP-compatible agent (e.g. Antigravity, Devin)

GitHub integration (opt-in)

• skelpr github setup — Configure GitHub PR review automation (manual/automatic modes)
• skelpr github status — Show current GitHub review automation status

FAQ

Do I need Docker? No. The core runs end-to-end out of the box with in-memory fallbacks. Docker adds sandboxed validation plus Postgres + Qdrant for production-scale indexing.

Do I need an LLM API key? CLI mode: yes — a cloud key or a local OpenAI-compatible server. Agent mode: no — the agent brings its own LLM; local embeddings via LM Studio make the whole setup keyless.

Which languages does it support? Any language with a tree-sitter grammar (regex fallback for the rest); lexical search is language-agnostic via ripgrep.

Which agents work out of the box? Claude Code, Cursor, and Windsurf auto-detect via skelpr install-mcp; any MCP-compatible agent (Antigravity, Devin, …) via skelpr register-agent.

How is this different from plain embedding RAG? RAG ranks by similarity only. Skelpr fuses five signals — lexical, symbol, graph, filename, vector — with deterministic source priority, so exact matches win, every result is path:line-cited, and negative queries return a provable no.

Roadmap

• Full cross-backend tenant isolation (Qdrant, filesystem, and sandbox scoped like PostgreSQL RLS)
• More agents pre-registered in install-mcp
• Repeat-run the A/B arms to quantify single-run variance (the fix task has scored 84 / 92 / 84 across identical runs)

Development

pip install -e ".[dev]"
pytest tests/                                  # run all tests
pytest tests/test_indexing.py tests/test_retrieval.py tests/test_mcp_server.py

• Test the MCP server: python -c "from skelpr.integrations.mcp_server import skelpr_health; print(skelpr_health())", or via the MCP Inspector: npx -y @modelcontextprotocol/inspector@latest python -m skelpr.integrations.mcp_server (connection, health, retrieval, symbols, dependencies, and validation verified).
• Observability — optional Langfuse tracing for retrieval benchmarking; each skelpr_get_context call produces a trace with retrieval metrics, timing, context size, and backend status. See docs/observability-and-beta-testing.md.
• Benchmarking — agent-agnostic A/B harness (Antigravity/Cursor) with per-arm artifacts; see tests/benchmarking/README.md, docs/BENCHMARK.md, and the WITH/WITHOUT side-by-side answers in docs/comparisons/ (one COMP_<AGENT>.md per agent).
• Plan board — the shortlist of next work as a checkbox list, with one detail file (why now, what to build, done-when) per item: NEXT_STEPS/README.md.

Docs

Doc	Contents
docs/BENCHMARK.md	Full benchmark reports + how to reproduce
docs/comparisons/COMP_ANTIGRAVITY.md	WITH vs WITHOUT — every task's verbatim answer side by side (one doc per agent)
docs/ARCHITECTURE.md	Mode diagrams, retrieval engine, fallback hierarchy, enterprise features
docs/CONFIGURATION.md	Local model setup + .skelpr.yaml reference
docs/MCP_SETUP.md	MCP installation, manual registration, troubleshooting
docs/observability-and-beta-testing.md	Langfuse tracing setup

Contributing

Contributions are welcome — especially benchmark runs on other agent stacks, new evaluator tasks, and retrieval-quality fixes.

pip install -e ".[dev]"
python scripts/check.py            # board + benchmark claims + repo hygiene (seconds)
python scripts/check.py --all      # + ruff, mypy, pytest
pytest -m "not slow and not docker and not live"   # fast loop; no Docker or backends needed

• CONTRIBUTING.md — setup, the two commands that matter, PR rules, DCO sign-off.
• docs/CODE_MAP.md — which module does what, plus recipes (add a language, add a retrieval signal, add an MCP tool, add a benchmark task).
• ROADMAP.md — what is next, and which items are good first contributions.
• docs/BENCHMARK.md — reproduce or extend the A/B harness.

Two project-specific rules worth knowing before you open a PR: published numbers must be re-derivable from artifacts (scripts/check_claims.py enforces it), and no absolute path from your machine may be committed (scripts/check_repo_hygiene.py enforces it — see docs/HYGIENE.md).

Community

• Questions and ideas: Discussions (Q&A, Ideas, Show & tell)
• Bugs and features: Issues
• Security: report privately via SECURITY.md — never in a public issue
• Conduct: CODE_OF_CONDUCT.md · Who decides what: GOVERNANCE.md · Who is who: MAINTAINERS.md
• Support and response expectations: SUPPORT.md · What is stable: docs/STABILITY.md

License

Apache-2.0 — see LICENSE for details, NOTICE for the attribution notice, and THIRD_PARTY_NOTICES.md for the dependencies, the benchmark corpus and the model output quoted in the docs.

Releases are listed in CHANGELOG.md; the release process is in docs/RELEASING.md.