Metadata-Version: 2.4
Name: skelpr
Version: 0.3.6
Summary: Agent-agnostic code-intelligence and safe-validation backend with hybrid retrieval, file:line citations, and MCP agent integration.
Author: Thrive360, Hashim Kalam
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/skelpr-thrive360/skelpr
Project-URL: Repository, https://github.com/skelpr-thrive360/skelpr
Project-URL: Issues, https://github.com/skelpr-thrive360/skelpr/issues
Keywords: mcp,model-context-protocol,agents,ai-agents,claude,cursor,code-intelligence,code-review,rag,hybrid-search,embeddings,retrieval,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
License-File: LICENSES/Apache-2.0.txt
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: questionary<3,>=2
Requires-Dist: pydantic>=2.6
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42
Requires-Dist: certifi>=2026.10.19
Requires-Dist: mcp>=2.0
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: qdrant-client>=1.9
Requires-Dist: tree-sitter>=0.25
Requires-Dist: tree-sitter-c
Requires-Dist: tree-sitter-c-sharp
Requires-Dist: tree-sitter-cpp
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-java
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-ruby
Requires-Dist: tree-sitter-rust
Requires-Dist: tree-sitter-typescript
Provides-Extra: postgres
Provides-Extra: vector
Provides-Extra: ast
Provides-Extra: mcp
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn[standard]>=0.29; extra == "server"
Provides-Extra: dev
Requires-Dist: skelpr[server]; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pylint>=3.2; extra == "dev"
Provides-Extra: all
Requires-Dist: skelpr[server]; extra == "all"
Dynamic: license-file

<div align="center">

<!-- Hero art: drop the file in `assets/` and uncomment. Nothing else is missing.
<img src="assets/skelpr-hero.png" alt="Skelpr — surgical code retrieval for AI agents" width="100%"/>
-->

<h1>Skelpr</h1>

### Budgeted, cited repository evidence for coding agents and code review.

<p>
  <a href="https://github.com/skelpr-thrive360/skelpr/actions/workflows/ci.yml?query=branch%3Adev+event%3Apush"><img src="https://github.com/skelpr-thrive360/skelpr/actions/workflows/ci.yml/badge.svg?branch=dev&amp;event=push" alt="CI on dev"/></a>
  <a href="https://pypi.org/project/skelpr/"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fskelpr%2Fjson&amp;query=%24.info.version&amp;prefix=v&amp;label=Published%20on%20PyPI&amp;logo=pypi&amp;logoColor=white&amp;style=flat&amp;color=blue" alt="Latest published Skelpr version on PyPI"/></a>
  <a href="https://pypi.org/project/skelpr/"><img src="https://img.shields.io/pypi/dm/skelpr?style=flat&amp;logo=pypi&amp;logoColor=white&amp;label=Downloads" alt="PyPI downloads"/></a>
  <a href="#requirements"><img src="https://img.shields.io/badge/python-3.10+-3776AB?style=flat&amp;logo=python&amp;logoColor=white" alt="Python 3.10+"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-proprietary-red?style=flat" alt="License: proprietary"/></a>
  <a href="#development"><img src="https://img.shields.io/badge/coverage-92.94%25-brightgreen.svg?style=flat" alt="Coverage"/></a>
</p>

| Historical Sock Shop MCP A/B | Agent without Skelpr | Agent with Skelpr |
|---|---|---|
| Agent tokens | 766k | **312k** (−59%) |
| Cache-read tokens | baseline | **−69%** |
| File reads | 113 | **27** (−76%) |
| Accuracy (per-task checklist) | 619 / 700 | **621 / 700** — no loss |

<p>
  <a href="#quick-start"><img src="https://img.shields.io/badge/Get%20started-activate%20%2B%20install-E5484D?style=for-the-badge" alt="Get started"/></a>
  <a href="docs/ARCHITECTURE.md"><img src="https://img.shields.io/badge/read-architecture%20%26%20retrieval-546FFF?style=for-the-badge" alt="Architecture and retrieval"/></a>
  <a href="docs/MCP_SETUP.md"><img src="https://img.shields.io/badge/set%20up-MCP%20in%20your%20agent-5865F2?style=for-the-badge" alt="MCP setup"/></a>
</p>

</div>

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](docs/ARCHITECTURE.md).

---

## Contents

- [Quick start](#quick-start) · [Install and upgrade](#install) · [Requirements](#requirements)
- [MCP integration](#mcp-integration) · [CLI commands](#cli-commands) · [Troubleshooting](#troubleshooting-retrieval-returns-nothing)
- [Architecture and docs](#docs) · [Development](#development) · [Support](#support) · [License](#license)
- [Sock Shop comparisons](#measured-impact) · [Django case study](#django-case-study--10-codex-tasks--2026-11-09)

## Quick start

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

```bash
pip install skelpr
skelpr activate <token>
skelpr license
cd <your-repo>
```

| Mode | Setup command |
|---|---|
| Coding agent (search and indexing) | `skelpr setup --no-configure --no-sandbox` |
| Standalone CLI | `skelpr setup` in an interactive terminal |

Start the configured embedding endpoint before indexing. The default is a local
OpenAI-compatible endpoint on port 1234. See [MCP setup](docs/MCP_SETUP.md) for
agent registration and the [tester guide](docs/tester-setup-guide.md#running-without-docker)
for persistent storage without Docker.
Run `skelpr setup --no-configure` to build the runner when you need sandboxed validation.

```bash
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](docs/CONFIGURATION.md#interactive-cli-onboarding).

## 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.

| | Agent (MCP) | Standalone Package |
|---|---|---|
| **What you get** | Surgical codebase access for your existing agent | Full ask/review/fix/validate pipeline |
| **Generation** | Provided by the agent | Provided by your configured endpoint |
| **Commands** | Agent calls MCP tools | `skelpr ask/fix/review/validate` |
| **Retrieval** | Skelpr (same engine) | Skelpr (same engine) |
| **Embeddings** | Local or hosted, for vector retrieval | Local or hosted, for vector retrieval |
| **Best for** | Enhancing Claude Code, Cursor, Windsurf, etc. | Self-contained coding assistant |

> 🧩 Mode diagrams, the shared retrieval engine, and the fallback hierarchy: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**

## MCP integration

After [quick start](#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`](docs/AGENT_INTEGRATION.md#live-checkout-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](docs/MCP_SETUP.md)**

## Install

The default install includes the CLI, MCP server, local AST grammars, and the
PostgreSQL and Qdrant clients. Use the server extra for the standalone HTTP API.

```bash
pip install skelpr
pip install "skelpr[server]"              # optional HTTP API

# 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. 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](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](docs/ACCESS.md). `pip` → `activate` → `license`, plus the vendor's half of
> the handover, is one page: [docs/HANDOVER.md](docs/HANDOVER.md).

### Upgrading

```bash
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

| Requirement | Needed for | Notes |
|---|---|---|
| Python ≥ 3.10 | everything | |
| `git` on PATH | diff / review / patch | degrades without it for index / ask |
| `ripgrep` | Live MCP checkout verification and literal scan helpers | Optional for ordinary BM25 query retrieval |
| **Docker Desktop, running** | `skelpr setup`, sandboxed `validate` | Start Docker Desktop first. `skelpr setup` checks the daemon, starts Postgres (5434) and Qdrant (6333/6334), and builds `skelpr-runner:latest`. Memory storage is process-local; host validation requires explicit local-fallback permission. |
| **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

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

| Job | Default model | Used for |
|---|---|---|
| Embeddings | `text-embedding-nomic-embed-text-v1.5@q8_0` | Indexing and vector search |
| Generation | `qwen2.5-14b-instruct` | Standalone CLI and model-backed HTTP routes |

- **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](docs/CONFIGURATION.md) for setup and verification.

## CLI commands

**Core**

| Command | What it does |
|---|---|
| `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 watch` | Index once, then watch from a terminal. MCP and `serve` watch automatically by default. The watcher indexes new and changed files, removes deleted entries, and detects branch switches. |
| `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 |
| `skelpr doctor` | Diagnose the install: repository rows, corpus, freshness, backends, agent wiring. Read-only; exits 1 when something needs fixing |

**MCP**

| Command | What it does |
|---|---|
| `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)**

| Command | What it does |
|---|---|
| `skelpr github setup` | Configure GitHub PR review automation (manual/automatic modes) |
| `skelpr github status` | Show current GitHub review automation status |

### 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](docs/MCP_SETUP.md#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](docs/MCP_SETUP.md) 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](docs/RETRIEVAL.md).

## ⚡ 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](#django-case-study--10-codex-tasks--2026-11-09) for Codex results and methodology.

Self-reported benchmarks: per-task tables, verbatim outputs and the "run it yourself" guide are in **[docs/BENCHMARK.md](docs/BENCHMARK.md)**; every answer side by side in **[docs/comparisons/COMP_ANTIGRAVITY.md](docs/comparisons/COMP_ANTIGRAVITY.md)**, and the Codex run in **[docs/comparisons/COMP_CODEX.md](docs/comparisons/COMP_CODEX.md)**.

The Sock Shop aggregate is a historical published result. Some retained task
artifacts do not reproduce that aggregate, as documented in the benchmark report.
It is not a fresh measurement of the current build or a general savings guarantee.

### 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

| Pipeline Strategy | Avg. Latency | Avg. Total Tokens | Avg. Cost / Query | Accuracy (0-100) | vs. Agentic Multi-Turn |
|---|---|---|---|---|---|
| Agentic Multi-Turn | 24.39s ⚠️ | 7,573 | $0.00200 | 88.4 / 100 | reference |
| **Skelpr Hybrid Engine** | **28.90s** ⚠️ | **3,925** (−48%) | **$0.00099** (−50%) | 85.1 / 100 | **48% fewer tokens · 50% cheaper · 4 of 7 tasks tied** |

> 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](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

<!-- Terminal demo: drop the recording in `assets/` and uncomment.
<p align="center">
  <img src="assets/skelpr-terminal-demo.gif" alt="Three cited searches, including a negative answer" width="820"/>
</p>
-->

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](docs/ARCHITECTURE.md#mcp-search-and-evidence-selection).

```text
$ 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](docs/AGENT_INTEGRATION.md#live-checkout-verification). The historical answers are in the [benchmark report](docs/BENCHMARK.md).

## 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

```bash
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.94%** 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](docs/observability-and-beta-testing.md).
- **Benchmarking** — an agent-agnostic A/B harness (Antigravity/Cursor/Codex) with per-arm artifacts: [benchmarks/README.md](benchmarks/README.md), [docs/BENCHMARK.md](docs/BENCHMARK.md), and the WITH/WITHOUT answers in [docs/comparisons/](docs/comparisons/) (one `COMP_<AGENT>.md` per agent).
- **Roadmap** — upcoming priorities and scope. See [ROADMAP.md](ROADMAP.md).

## Docs

| I want to… | Read |
|---|---|
| See what Skelpr offers | [Feature inventory](docs/FEATURES.md) |
| Set up an agent | [MCP setup](docs/MCP_SETUP.md) |
| Configure models or storage | [Configuration](docs/CONFIGURATION.md) |
| Understand the engine | [Architecture diagrams](docs/ARCHITECTURE.md) · [Retrieval design](docs/RETRIEVAL.md) |
| Check measured results | [Django evidence](docs/BENCHMARK_HISTORY.md) · [Sock Shop report](docs/BENCHMARK.md) |
| Find another guide | [Documentation index](docs/README.md) |

## Maintainer development

Maintainers with repository access can find setup and pre-merge checks in the
[development guide](docs/DEVELOPMENT.md).

## 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](SECURITY.md) says how.
- **Response expectations:** [SUPPORT.md](SUPPORT.md) · **What is stable:** [docs/STABILITY.md](docs/STABILITY.md)

## License

**Proprietary.** Skelpr 0.1.2 and later are licensed under the [Skelpr End User License
Agreement](LICENSE): 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](docs/DISTRIBUTION.md),
and the Apache-2.0 text is kept at [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt).

See [NOTICE](NOTICE) for attribution and
[THIRD_PARTY_NOTICES.md](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](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](benchmarks/results/django-final-20261102/README.md)
and the [verification and archive](docs/BENCHMARK_HISTORY.md).

| Question | Native total tokens | Skelpr total tokens | Savings | Accuracy native → Skelpr | Latency native → Skelpr |
|---|---:|---:|---:|---|---|
| Q1: qualified-symbol lookup | 14,944 | 13,997 | 6.34% | 3/3 → 3/3 | 24.80 → 42.23 s |
| Q2: multi-file execution flow | 46,686 | 27,322 | 41.48% | 23/24 → 24/24 | 64.33 → 69.75 s |
| Q3: architecture comparison | 42,919 | 43,452 | **1.24% overhead** | 23/30 → 25/30 | 40.10 → 82.41 s |
| **Overall** | **104,549** | **84,771** | **18.92%** | Different per-question rubrics | **129.23 → 194.39 s** |

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**.

| Task | Total tokens native → Skelpr | Token savings | Rubric native → Skelpr | Wall time native → Skelpr |
|---|---:|---:|---:|---:|
| Q1 · Middleware lookup | 14,203 → 13,530 | 4.74% | 3/3 → 3/3 | 38.87 → 55.39 s |
| Q2 · Request execution flow | 47,406 → 28,931 | 38.97% | 24/24 → 24/24 | 56.90 → 50.54 s |
| Q3 · WSGI and ASGI architecture | 63,091 → 29,474 | 53.28% | 26/30 → 27/30 | 61.67 → 56.48 s |
| Q4 · QuerySet.exists() behavior | 24,509 → 13,043 | 46.78% | 5/6 → 6/6 | 33.18 → 29.37 s |
| Q5 · Custom CSRF header test | 23,552 → 13,260 | 43.70% | 6/6 → 6/6 | 27.19 → 23.69 s |
| Q6 · Verify absent integrations | 34,206 → 31,154 | 8.92% | 5/6 → 5/6 | 49.72 → 52.81 s |
| Q7 · Cache Vary impact | 71,294 → 44,562 | 37.50% | 7/8 → 7/8 | 61.64 → 70.21 s |
| Q8 · Fix URL scheme validation | 60,019 → 39,048 | 34.94% | 2/2 → 2/2 | 72.63 → 63.64 s |
| Q9 · Savepoint commit hooks | 46,805 → 25,573 | 45.36% | 8/8 → 8/8 | 63.25 → 64.77 s |
| Q10 · Fix multi-batch prefetch | 52,912 → 36,174 | 31.63% | 3/3 → 3/3 | 69.37 → 54.36 s |
| **Overall** | **437,997 → 274,749** | **37.27%** | **89/96 → 91/96** | **534.40 → 521.25 s** |

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](benchmarks/results/django-case-study-20261109/metrics.json)
