Skelpr gives coding agents budgeted repository evidence with source citations. Query retrieval combines BM25, symbol and file lookups, and available vector results. Parser-backed function boundaries and indexed source relationships help select relevant code. See the architecture diagrams.

Contents

• Quick start · Install and upgrade · Requirements
• MCP integration · CLI commands · Troubleshooting
• Architecture and docs · Development · Support · License
• Sock Shop comparisons · Django case study

Quick start

Install Skelpr and activate this machine before indexing. Start Docker for skelpr setup.

pip install "skelpr[mcp,postgres,vector,ast]"
skelpr activate <token>
skelpr license
cd <your-repo>

Start the configured embedding endpoint before indexing. The default is a local OpenAI-compatible endpoint on port 1234. See MCP setup for agent registration and the tester guide for persistent storage without Docker.

skelpr init
skelpr index

• Coding agent: Run skelpr install-mcp, then reconnect the agent.
• Standalone CLI: Try skelpr ask "how does authentication work?".

Interactive CLI model configuration

skelpr setup verifies generation and embeddings, then saves verified settings. skelpr init writes .skelpr.yaml from them. For provider options, credential storage, or scripted setup, see configuration.

Why Skelpr?

• Cited source for answering questions, reviewing changes, and preparing edits.
• Bounded context with function-level evidence where parser support allows it.
• Native fallback when an agent needs evidence outside the returned spans.

Two integration modes

Use Agent (MCP) when your coding agent supplies generation. Pick Standalone when you want Skelpr to call your configured generation provider.

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

MCP integration

After quick start, use skelpr install-mcp --agent <id> to target one client, or --project-level for a supported repository-local config.

Available MCP tools:

• skelpr_search — Budgeted code evidence from BM25, symbol and vector retrieval with RRF, plus focused lookup and edit evidence where supported. Pass {"query": "your question"}. For explicit live file or text checks, use verification.
• skelpr_get_context — Budgeted context (default 4000 approximate tokens, top_k=8); use missing_evidence and exclude_span_ids for focused follow-ups. Whole functions may be omitted if they cannot fit.
• skelpr_find_symbol / skelpr_dependencies — Symbol definition and location lookup; structural relationships and dependencies
• skelpr_validate — Run configured validation in Docker or with explicitly enabled host fallback
• skelpr_apply_ast_patch — Generate a unified diff for review and separate application
• skelpr_health — System health and backend status

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

Install

# Wheel only, published to PyPI, so a plain `pip install skelpr` resolves anywhere.
pip install skelpr
pip install "skelpr[postgres,vector,ast,server]"   # production backends
pip install "skelpr[mcp]"                 # MCP server support
pip install "skelpr[all]"                 # everything

# From source — the repository is private, so this needs access to it:
git clone https://github.com/skelpr-thrive360/skelpr.git skelpr && cd skelpr
pip install -e ".[all]"                    # editable dev install
pip install -e ".[dev]"                    # + pytest/ruff/mypy

Installing is public; running is licensed. The wheel is published to PyPI, wheel-only, so pip install skelpr works on any machine with nothing else to configure. There is no source distribution, so pip install --no-binary skelpr is unsupported. A machine still needs skelpr activate <token>, and each activation spends a seat. Distribution detail: docs/DISTRIBUTION.md.

Activation. Installing needs no account; running does. One token per person, one seat per machine: skelpr activate <token>, then skelpr license to check it. Everything else — seats and deactivate, the lease and its renewal, the environment overrides, and the limits of the mechanism — is in docs/ACCESS.md. pip → activate → license, plus the vendor's half of the handover, is one page: docs/HANDOVER.md.

Upgrading

skelpr upgrade --check     # what is published vs what you run (exit 1 when one is available)
skelpr upgrade             # install it, through pip, pipx or uv — whichever owns the install

skelpr license also says when a newer release exists. The check is one request a day at most, never installs anything by itself, and is switched off by SKELPR_NO_UPDATE_CHECK=1 — for a CI job, or anyone who would rather this build asked nothing. A machine set to SKELPR_OFFLINE=1 never checks at all.

Restart after upgrading. The files on disk change; the processes already running do not. Your agent holds the MCP server in its own process, and skelpr watch/skelpr serve are daemons — each keeps running the old code until it is restarted. Run skelpr index as well if the release notes mention indexing or embedding changes. An editable install is refused on purpose: skelpr upgrade never replaces a working copy, so a checkout is updated with git.

Why no auto-update: an unattended upgrade would swap the package under a live MCP server, change what a lease unlocks mid-session, and land migrations against a database the user is running. Better a notice nobody can miss than a version nobody chose.

Requirements

Local models

The default endpoint is http://127.0.0.1:1234/v1.

• Local: Load the models in your server and match its advertised IDs in .skelpr.yaml.
• Hosted: Set the provider and credentials before indexing. An eligible Skelpr lease can mint a credential for the hosted embedding endpoint.
• Endpoint unavailable: Keyless, non-strict initialization can use hashing. Strict indexing needs a working endpoint. BM25 and symbols can still supply search evidence.

See the model configuration guide for setup and verification.

CLI commands

Core

MCP

GitHub integration (opt-in)

Troubleshooting: retrieval returns nothing

1. Check that MCP reports the repository you intended to search.
2. Run skelpr doctor from that repository. Add --verbose to see passing checks.
3. Check index freshness and storage. An index built in memory disappears when its process exits.
4. Refresh the index if diagnostics show it is missing or stale.

doctor reports duplicate repository rows and backend problems without repairing them. See MCP troubleshooting.

FAQ

Do I need Docker? Retrieval supports in-memory fallbacks, which do not persist between processes. Docker adds PostgreSQL/Qdrant and isolated validation. Validation without Docker requires sandbox.allow_local_fallback: true and runs on the host.

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? AST extraction uses supported tree-sitter grammars with regex fallback. BM25 is language-agnostic; complete-function and dependency analysis depend on parser support, with Python, TypeScript/JavaScript and Go regression fixtures.

Which agents work out of the box? skelpr install-mcp can detect Codex, Claude Code, Cursor, Windsurf, and other supported clients. Codex setup uses its own CLI at user scope. See MCP setup for the client list and manual registration.

How is this different from plain embedding RAG? Skelpr combines BM25 and vector candidates through RRF while preserving explicit symbol/file lookup intent. Bounded import/reference tracing and function-level selection provide cited evidence. Indexed and live-checkout results each describe the scope that was checked. See retrieval design.

⚡ Measured impact

Historical Sock Shop MCP A/B: −59% agent tokens · −76% file reads · accuracy 619 → 621 / 700. See the separate ten-task Django case study for Codex results and methodology.

Self-reported benchmarks: per-task tables, verbatim outputs and the "run it yourself" guide are in docs/BENCHMARK.md; every answer side by side in docs/comparisons/COMP_ANTIGRAVITY.md, and the Codex run in docs/comparisons/COMP_CODEX.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: -59% (766k → 312k) — cache-read tokens, the biggest quota consumer, drop -69%
• 📖 File reads: -76% (113 → 27) — one skelpr_search (median 0.54s) replaces ~4 native file reads
• 🎯 Accuracy: no loss (619 → 621 / 700, every task within the ±5 tolerance) — the run-1 gaps this engine was built to fix (Helm/ingress, the healthcheck step, 3 of 5 image sites) are closed and all 5 image sites are recovered. Not a clean sweep: two single checklist facts traded the other way (session-db ↔ Makefile; kube-state-metrics), and both arms miss the negative task's phrase (60/60). Token and file-read savings are unaffected.

CLI mode · Standalone: agentic multi-turn vs. the hybrid engine

Same 7 questions, same model (openai/gpt-oss-120b on Groq), same checkout, scored by the deterministic per-task checklist (0-100); per-task detail in docs/BENCHMARK.md. The hybrid engine retrieves pre-ranked, cited chunks in one pass — one model call per task instead of two — which is where the token and cost savings come from. ⚠️ The latency figures include Groq free-tier rate-limit backoff (the Skelpr arm ran second and absorbed the waits): on the task with no throttling it answered in 1.56s vs 3.55s. Accuracy is near-parity, not better: 4 of 7 tasks tie and the agentic reference leads the other three by 5-10 points.

👀 See it in action

Historical output from the A/B harness (Sock Shop, 2026-09-24, WITH arm). The agent asks whether a recommendations service exists. This older build included a graph summary in search results. Current query retrieval uses the pipeline shown in the architecture guide.

$ 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

The agent reported no recommendations service after three searches and one file read. Both arms scored 60/100 because the evaluator required the phrase "does not exist". Current indexed results describe the indexed scope. For explicit live-checkout text and path checks, use MCP verification. The historical answers are in the benchmark report.

Roadmap

• Full deployment isolation for filesystem and sandbox execution (metadata has RLS; Qdrant collections are already tenant-specific)
• 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/retrieval/test_indexing.py tests/retrieval/test_retrieval.py tests/mcp/test_mcp_server.py

Test coverage: 92.08% of skelpr, statements and branches, measured with pytest --cov=skelpr --cov-report=term-missing. CI gates on an 80% floor (--cov-fail-under=80), so a patch that quietly stops testing something fails the build. The badge and this figure are rewritten from the coverage report after every merge to main, so neither is hand-typed.

• 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 — an agent-agnostic A/B harness (Antigravity/Cursor/Codex) with per-arm artifacts: benchmarks/README.md, docs/BENCHMARK.md, and the WITH/WITHOUT 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

Maintainer development

Maintainers with repository access can find setup and pre-merge checks in the development guide.

Support

Skelpr is sold and supported directly by its vendor: access, seat changes, renewals and bug reports go back through the contact that issued your token, not a public tracker.

• Security: report privately — SECURITY.md says how.
• Response expectations: SUPPORT.md · What is stable: docs/STABILITY.md

License

Proprietary. Skelpr 0.1.2 and later are licensed under the Skelpr End User License Agreement: running needs an access token, the token is issued to a person, and activating a machine spends one of its seats.

Versions 0.1.0 and 0.1.1 were published under Apache-2.0 and remain governed by it — an irrevocable grant that the later change of license does not touch, and that no withdrawal can take back. Those two releases have been taken out of the project's distribution; what that does and does not reach is in docs/DISTRIBUTION.md, and the Apache-2.0 text is kept at LICENSES/Apache-2.0.txt.

See NOTICE for attribution and THIRD_PARTY_NOTICES.md for the dependencies, the benchmark corpus and the model output quoted in the docs.

The release process is in docs/RELEASING.md; releases are the git tags on main.

Additional benchmark: Django Q1/Q2/Q3 — 2026-11-02

This is a separate, completed single-run Codex comparison, not a replacement for the historical results above and not evidence of general performance. Run with gpt-6.1-sol at low reasoning; comparable frozen native baselines were reused for Q1/Q2, Q3 used a fresh pair, native fallback was allowed and there were no retries. Detail: the report, protocol, scores and six verbatim answers and the verification and archive.

Savings sum input and output tokens, cached input included. Native reads fell 22 → 8, model requests 10 → 9, evidence tool calls 7 → 6; cached input 60,672 → 54,272, uncached 41,715 → 28,648. Provider cache state was uncontrolled, so this is not a billing-cost measurement, and Q1's uncached input rose.

Mixed verdict: Q1 and Q2 passed; Q3 missed both goals, with each answer below the frozen 27/30 threshold and total latency up 50.43%. Transaction behaviour stayed incomplete and available evidence went unused, across fallback calls Q3 needed for missing architecture detail. Direct MCP coverage was Q1 3/3, Q2 8/8 and Q3 five complete / five partial; accurate citations and untruncated functions did not close Q3's selection and dependency gaps, and the fixed budgets were not raised. Repeat runs across repositories are needed before generalising.

Django case study · 10 Codex tasks · 2026-11-09

Across ten matched comparisons on the public Django checkout, Skelpr MCP reduced total tokens by 37.27% and native search or read calls from 28 to 9. Combined rubric scores rose from 89/96 to 91/96, and model requests fell from 41 to 31.

Total tokens include input and output, with cached input counted. Uncached input fell from 134,804 to 87,110 with uncontrolled provider cache state. Wall time includes startup and shutdown. Six tasks finished faster, and summed wall time fell 2.46%. Native search or read counts exclude test runs.

The case study uses Codex CLI with high reasoning and matched settings within each pair. It reports one retained comparison per question across successive Skelpr builds. The questions informed retrieval tuning, and Q8 and Q10 used intentionally seeded defects in isolated Django copies. These observed results describe this case study. A release-wide estimate would require a fresh run on one frozen build and unseen tasks.

Per-run metrics and Django source revision