{ "markdown": "\n

\n \"SkeletonGraph\n

\n\n

\n \"PyPI\"\n \"Python\n \"Preprint\"\n \"MIT\n \"MCP\n \"MCP\n \"Zero-LLM\n

\n\n

\n Works with \n \"Cursor\"\n \"Claude\n \"GitHub\n \"Codex\"\n \"Antigravity\"\n \"Windsurf\"\n \"Cline\"\n \"Any\n

\n\n

\n Languages \n \"Python\"\n \"JavaScript\"\n \"TypeScript\"\n \"Go\"\n \"Rust\"\n \"Java\"\n \"C#\"\n \"C++\"\n \"Ruby\"\n \"PHP\"\n

\n\n**Coding agents burn tokens reading whole files to find one function. SkeletonGraph\nindexes your repo with tree-sitter — no LLM — and hands the agent the exact function\nto edit, over MCP.**\n\n\n \n \"SkeletonGraph\n\n\n

Index once with tree-sitter (no LLM) → three signals rank the same symbols → reciprocal-rank fusion returns the exact function, served to your agent over MCP.

\n\n

The answer is rank 2, 3, and 2 across the three signals — top of none of them. Fusing is what puts it first.

\n\nSkeletonGraph is a retrieval engine purpose-built for coding agents, not a general\nRAG library retrofitted onto code. It parses a repository into function-level\nstructure, a cross-file call graph, and PageRank centrality with **zero LLM calls** —\ndeterministic, cheap, and instant to rebuild after every edit. At query time it\nresolves the symbols an issue names, walks the call graph outward, and reranks a\nBM25 recall pool by structural confirmation so the agent lands on the **right\nfunction** on the first try, instead of grepping and re-reading its way there. Its\nleaner operating point, **`sg-rerank`** (the product default), skips the dense leg\nentirely and still delivers the best file *and* function recall of any method we\nbenchmarked it against — at the lowest token cost of any of them.\n\nThe thesis: code-context tools have mostly been validated as a **token-optimization**\ngame — how few tokens can you spend. SkeletonGraph re-centers the question on\n**retrieval quality** — did the agent land on the correct function — of which lower\ntoken cost turns out to be a *consequence*, measurable only end-to-end inside a real\nagent loop, not in an offline benchmark.\n\n## Results\n\nAll numbers below are regenerated from the released run artifacts\n(`python -m eval.scripts.make_paper_figures`). The full verified ledger, including\nwithdrawn claims, is in [`docs/paper/FINDINGS.md`](docs/paper/FINDINGS.md).\n\n### 1. Controlled retrieval ablation (react loop, open-weight model, 100 tasks)\n\nIdentical action space for every arm; **only the retrieval backend changes**. The\n`none` arm gets no code access at all and establishes the memorization floor.\n\n| arm | pass@1 | file recall@1 | function hit | tokens (k) | turns | $/task |\n|---|--:|--:|--:|--:|--:|--:|\n| **`sg-fusion`** | **42.0%** | .737 | **57%** | **180** | 21.9 | **.052** |\n| `bm25` | 41.0% | .642 | 43% | 264 | 24.6 | .074 |\n| `graphify` (knowledge graph) | 41.0% | .223 | 9% | 275 | 25.6 | .078 |\n| `grep` | 39.0% | .647 | 0% | 282 | 22.4 | .079 |\n| `aider` (repo-map) | 36.7% | — | — | 1,126 | 18.1 | .160 |\n| `none` (no retrieval) | 35.0% | — | — | 345 | 23.6 | .066 |\n\n**`sg-fusion` is the top arm, the cheapest arm, and the only one that localizes to\nthe function** (57% vs grep's 0% — lexical search is file-granular by construction).\nAgainst the closed-book floor of 35.0%, retrieval is worth **+7 points** here.\n\n`sg-rerank`'s recall/cost profile is reported separately in the agent-free intrinsic\nretrieval ablation in [the paper](docs/paper/ResearchPaper.pdf)\n(Table 2, §5.1) — best MRR/recall@10 short of full fusion, at the lowest index cost.\n\n### 2. Deployment: SkeletonGraph vs native Claude Code (MCP, Docker-verified)\n\nThe product itself — SG as an MCP server driving **Claude Code (sonnet)** against\nClaude Code on its own tools. 100 paired SWE-bench Verified tasks:\n\n| arm | pass@1 | file recall@1 | turns | $/task |\n|---|--:|--:|--:|--:|\n| `native` (Claude's own Grep/Read) | 74/100 | .663 | 14.5 | .434 |\n| **`sg-fusion`** (SkeletonGraph MCP) | 75/100 | **.862** | **11.4** | **.371** |\n\nSG's first-search recall excludes 3 tasks where the agent never called SG at\nall — those are adoption events, not retrieval failures. Including them gives .836.\n\n**Equivalent solve rate at −14.6% cost and −21.4% turns.** The saving is not spread\nevenly — it lives almost entirely in the tail:\n\n| cost percentile | native | +SG | change |\n|---|--:|--:|--:|\n| 50th (median task) | $0.255 | $0.260 | **+1.9%** |\n| 90th | $1.010 | $0.752 | −25.6% |\n| 95th (worst tasks) | $1.559 | $0.896 | **−42.5%** |\n\nRetrieval does nothing for the typical task and removes over 40% of the cost of the\nworst ones. Paired bootstrap 95% CI on the mean: [−25.3%, −1.2%]; McNemar on pass@1:\np = 1.0 (no difference).\n\n### 3. What the numbers don't cover\n\n![Retrieval changes nothing on ordinary tasks; it truncates the expensive ones](docs/paper/figures/fig_tail.png)\n\nThat tail effect is where the chart above comes from. Retrieval quality itself holds\nup under real stress-testing: it survives having all the location cues (tracebacks,\ncode blocks) stripped from the issue text, and it survives on a decontaminated\nbenchmark of repos the model hasn't memorized. But better retrieval doesn't move the\nsolve rate (McNemar p=1.0), and an agent given enough turns to explore on its own\neventually learns a repo about as well as a ranked list tells it — retrieval buys\nspeed and cost, not a ceiling past what patient exploration reaches.\n\nFull methodology — the n=15→50 revision, the dose-response check, the\ncumulative-recall mechanism, and every withdrawn claim — is in\n[the paper](docs/paper/ResearchPaper.pdf) and\n[`docs/paper/FINDINGS.md`](docs/paper/FINDINGS.md).\n\nSkeletonGraph is wrapper-first: it returns a full context packet or exposes a\nretrieval index (AST skeletons + call graph + local summaries + optional embeddings)\nso the IDE agent or CLI can choose targets.\n\nSkeletonGraph has two product surfaces:\n\n- **SG IDE**: MCP context server for Cursor, Claude Code, Copilot, Codex,\n Antigravity, Windsurf, and other agentic IDEs.\n- **SG CLI**: terminal pipeline for route, prepare, dry-run, provider execution,\n and cost-aware model selection.\n\n## Why SkeletonGraph\n\nMost coding agents spend expensive turns discovering the repo:\n\n```text\nsearch -> read file -> read neighbor -> read tests -> realize the target\n```\n\nSkeletonGraph moves that work into a deterministic graph pipeline:\n\n```text\nprompt -> (optional) retrieval planner -> classify task -> find target nodes -> expand graph -> assemble packet\n```\n\nThe goal is not only lower token cost. The useful product outcomes are:\n\n- fewer exploratory file reads\n- faster first useful answer\n- better target/test/blast-radius context\n- transparent routing reasons\n- lower model overkill for routine tasks\n- reusable packets for IDEs, CLIs, and other agents\n\n## Install\n\n```bash\npip install skeletongraph # core: indexing, MCP server, CLI (no API key needed)\npip install \"skeletongraph[llm]\" # + litellm for sg run --execute / sg summarize --tier cloud\npip install \"skeletongraph[all]\" # everything\n```\n\n## Quick Start: SG IDE\n\nUse this path when you already work inside Cursor, Claude Code, Copilot, Codex,\nAntigravity, or another MCP-capable coding environment.\n\n```bash\ncd your-project\nsg init\nsg build\nsg doctor\n```\n\n`sg init` writes the MCP config and the agent instruction file for the selected\nIDE. SG IDE does not require an API key. Your IDE subscription/model still does\nthe reasoning and editing; SkeletonGraph supplies the packet or retrieval\nsignals for efficient target selection.\n\nSupported IDE setup targets include:\n\n| IDE | Integration | Model switching |\n| --- | --- | --- |\n| Cursor | MCP + rules | manual in IDE |\n| Claude Code | MCP + `CLAUDE.md` | `/model` command |\n| GitHub Copilot | MCP + instructions | manual in IDE |\n| Codex | MCP + `AGENTS.md` | manual in agent |\n| Antigravity | MCP + rules | manual in IDE |\n| Windsurf | MCP + rules | manual in IDE |\n\n## Quick Start: SG CLI\n\nUse this path when you want a terminal-first context and model-routing pipeline.\n\n```bash\ncd your-project\nsg build\nsg route \"fix the auth token validation bug\"\nsg prepare \"fix the auth token validation bug\" --out .skeletongraph/context.md\nsg run \"fix the auth token validation bug\" --dry-run\n```\n\n`sg route`, `sg prepare`, and `sg run --dry-run` do not need an API key.\n\nTo call a provider:\n\n```bash\nsg config --cli-provider anthropic\n$env:ANTHROPIC_API_KEY = \"...\"\nsg run \"fix the auth token validation bug\" --execute\n```\n\nTo test locally without a paid provider key:\n\n```bash\nollama pull qwen3-coder:latest\nollama serve\nsg config --cli-provider local\nsg run \"fix the auth token validation bug\" --dry-run\nsg run \"fix the auth token validation bug\" --execute\n```\n\nLocal execution is intended for cheap pipeline testing. Use provider models for\nquality benchmarks unless the benchmark is specifically for local models.\n\n## Model Dependency, Prewarming, and Keeping the Index Fresh\n\nSG downloads **two** small embedding models on first use, both via\n`sentence-transformers` (a hard dependency, not optional):\n\n- **`jinaai/jina-embeddings-v2-base-code`** (`SG_DENSE_MODEL`) — the semantic\n leg of `fusion`/`sg_search`. Loaded on `sg warm` or on an agent's first\n dense-retrieval query. Loads with `trust_remote_code=True` (Jina ships custom\n modeling code on the HF Hub) — this executes code from that model repo, same\n as any `trust_remote_code` model.\n- **`all-MiniLM-L6-v2`** (`SG_EMBED_MODEL`) — a smaller, separate model used\n only as a confidence-score tiebreaker at index time. Downloads automatically\n on the **first `sg build`**, not on `sg warm`.\n\nBoth need internet access the very first time each is used on a machine — after\nthat, both are cached locally (Hugging Face's model cache, plus SG's own\ncontent-hash caches: `.skeletongraph/dense_cache` for the dense leg,\n`.skeletongraph/embeddings.npz` for the confidence tiebreaker) — so later builds\nare incremental: only functions whose text actually changed get re-embedded.\n\n**Prewarm before launching an agent**, so that cost lands during setup instead\nof on the agent's first real search:\n\n```bash\nsg build # parse + structural index (no LLM, fast)\nsg warm --path . # prebuild BM25 + dense caches (one-time; minutes on CPU)\nsg warm --path . --mode rerank # skip the dense leg entirely (no embedding cost)\n```\n\nWithout this, the first `sg_search` call an agent makes pays the cold-encode\ncost inline — on a large repo this can exceed the dense retrieval leg's\ninternal timeout (`SG_DENSE_TIMEOUT_S`, 20s by default), in which case it\nsilently degrades to a 2-signal (lexical + structural) result rather than\nfailing outright. Prewarming avoids relying on that fallback altogether.\n\n**Keeping the index current as files change** — two options, pick based on\nhow you work:\n\n```bash\nsg update --path . # one-shot: re-index only files that changed since last build\nsg watch --path . # background daemon: auto-reindexes on save (needs `pip install \"skeletongraph[daemon]\"`)\n```\n\n`sg watch` is the hands-off option for active development — it debounces\nrapid saves and calls the same incremental update path as `sg update`, so\nediting a file is reflected in the index without a manual rebuild.\n\n## Model Routing\n\nSkeletonGraph separates IDE-facing model labels from CLI provider model names.\n\nFor IDEs, model tiers are recommendations:\n\n| Tier | Typical use |\n| --- | --- |\n| SLM | docs, explanations, simple lookup |\n| MLM | normal coding, debugging, tests, review |\n| LLM | architecture, broad migrations, low-confidence tasks |\n\nFor CLI execution, SkeletonGraph can route to provider model names:\n\n```bash\nsg config --cli-provider anthropic\nsg config --cli-provider openai\nsg config --cli-provider google\nsg config --cli-provider local\n```\n\nDynamic routing uses task mode, confidence, candidate count, token size, and\ncomplexity. Code-changing work keeps an MLM floor by default so cost savings do\nnot come from making weak models edit code unsafely. Retrieval planning can use\nsmall models to propose targets over AST/summaries before the heavy model runs.\n\n## IDE Integration\n\nAfter `sg init` and `sg build`, register SG as an MCP server and write IDE hooks:\n\n```bash\nsg install --ide claude-code # Claude Code: hooks + MCP server + CLAUDE.md rules\nsg install --ide cursor # Cursor: MCP + .cursor/rules/skeletongraph.mdc + hooks\nsg install --ide cline # Cline: MCP config + rules block\nsg install --ide roo # Roo: MCP config + rules block\nsg install --ide copilot # GitHub Copilot: MCP + copilot-instructions.md\nsg install --ide windsurf # Windsurf: MCP + .windsurfrules\nsg install --ide zed # Zed: MCP config + rules block\nsg install --ide continue # Continue: MCP config + rules block\nsg install # auto-detect all installed IDEs\n```\n\n`codex` and `antigravity` are accepted as aliases and currently route through the\nCopilot-style MCP installer.\n\nFor any other MCP-capable client, or to configure it by hand, see\n[`mcp.example.json`](mcp.example.json) for the raw server config\n(`sg serve --path /path/to/your/project`).\n\nAfter install, restart your editor. SkeletonGraph runs as a background MCP server\n(`sg serve --path .`) that the IDE connects to automatically.\n\n## MCP Tools\n\nSeven tools are exposed to the IDE agent. Use these **instead of** grep/glob/file reads:\n\n| Tool | When to call | Returns |\n| --- | --- | --- |\n| `sg_overview` | Session start — once per session | Constraints + top-N functions (by PageRank) + recent turns + index stats |\n| `sg_search \"query\"` | **Primary retrieval** — almost every prompt | Top-3 matches with body excerpts + summaries + 1-hop callers; top-4..N as signatures + summaries. One call usually enough — no need to chain. |\n| `sg_get \"fqn\"` | When the exact FQN is known | Signature + summary + 1-hop callers + callees |\n| `sg_expand \"target\"` | When more body is needed than `sg_search` returned | Full function body / file / line range (token-capped) |\n| `sg_constraint list` / `propose` | Before proposing changes | Confirmed + proposed project rules |\n| `sg_log` | Reviewing recent session turns | Last-N turn summaries with files touched |\n| `sg_decision` | A design/implementation choice is made (picked or rejected, and why) | Recorded so it survives context compaction — recall later with `sg_log(kind=\"decision\")` |\n\n**Smart context routing.** On each `UserPromptSubmit`, SG classifies the prompt\n(architecture / explain / decision / debug / test / review / general) and\nincludes the matching MD file from `.skeletongraph/` — e.g. `architecture.md`\nonly for design/refactor queries, `project.md` only for \"what is this codebase\"\nqueries. Constraints + session digest + relevant functions are always injected.\n\n**Cold start.** If no `.skeletongraph/` index exists when an MCP tool is called,\nSG auto-builds on first invocation (see `auto_build_on_query` in config).\n\n## CLI Reference\n\n**Indexing & status**\n\n| Command | Purpose |\n| --- | --- |\n| `sg init [--agent cursor]` | Configure project, IDE preset, MCP, constraints |\n| `sg index` | Full index (alias for `sg build`) |\n| `sg index --incremental` | Only re-index changed files |\n| `sg build` | Full index with detailed output |\n| `sg update` | Incremental update |\n| `sg status` | Show index status |\n| `sg doctor` | Check index, routing, provider, Ollama readiness |\n| `sg overview` | Project skeleton: top functions, constraints, session |\n| `sg install [--ide ]` | Write IDE hooks + MCP config |\n\n**Retrieval**\n\n| Command | Purpose |\n| --- | --- |\n| `sg search \"query\"` | BM25 + graph search (no API key) |\n| `sg get \"fqn\"` | Get function signature, summary, callers |\n| `sg expand \"target\"` | Expand function body / file / line range |\n\n**Constraints & session**\n\n| Command | Purpose |\n| --- | --- |\n| `sg constraint list` | List all constraints |\n| `sg constraint propose \"text\"` | Add a proposal |\n| `sg constraint confirm ` | Promote proposal → decisions.md |\n| `sg constraint remove ` | Remove a constraint |\n| `sg constraint aggregate` | Import from IDE rule files |\n| `sg log [--last-n 10]` | Show recent session turns |\n\n**Summarization**\n\n| Command | Purpose | API key |\n| --- | --- | --- |\n| `sg summarize --tier local` | Ollama Tier-0.5 (free, on-device) | no |\n| `sg summarize --tier cloud` | Cloud LLM Tier-1 | provider key |\n| `sg summarize --tier cloud --force` | Re-summarize all functions | provider key |\n\n**Model routing & execution**\n\n| Command | Purpose | API key |\n| --- | --- | --- |\n| `sg route \"task\"` | Show task mode, tier, recommended model | no |\n| `sg run \"task\" --dry-run` | Plan routed execution | no |\n| `sg run \"task\" --execute` | Call configured provider | provider or local |\n| `sg config [--agent cursor]` | Configure IDE and CLI models | no |\n| `sg config --cli-provider anthropic` | Set CLI execution provider | no |\n\n**Background indexing**\n\n| Command | Purpose |\n| --- | --- |\n| `sg watch` | Daemon: auto-reindex files on save |\n\nProvider output from `sg run --execute` is written to `.skeletongraph/runs/`.\nEvaluation is currently done externally via a SWE-bench harness (see the\n[Evaluation](#evaluation) section below).\n\n## Python API\n\n```python\nfrom skeletongraph.engine import SGEngine\n\nengine = SGEngine(project_root=\".\")\nresult = engine.query(\"fix the content-length bug\", delivery=\"cli\")\n\nprint(result.context_text)\nprint(result.query_mode)\nprint(result.model_tier)\nprint(result.recommended_model)\nprint(result.routing_reason)\n```\n\n## Architecture\n\n```text\nsrc/skeletongraph/\n parser/ AST extraction\n graph/ dependency graph and ranking\n storage/ .skeletongraph persistence\n retrieval/ classification, resolution, model routing\n assembly/ context packet construction\n session/ memory and dedup\n server/ MCP server\n install/ per-IDE hook + MCP config writers (`sg install`)\n hooks/ IDE hook handlers (prompt-submit routing, etc.)\n llm/ LiteLLM wrapper for optional CLI execution\n cli/ Click commands\n engine.py unified query pipeline\n```\n\n## Evaluation\n\nThe full methodology, verified results, and every withdrawn/superseded claim are in\n[the paper](docs/paper/ResearchPaper.pdf) and\n[`docs/paper/FINDINGS.md`](docs/paper/FINDINGS.md).\n\nSkeletonGraph should be evaluated on both quality and cost:\n\n- target recall and packet completeness\n- missed tests/callers\n- first useful answer latency\n- file reads after SG context\n- pass rate\n- cost per passing task\n- dynamic routing overkill/underpower rate\n- IDE compliance with SG-first context usage\n\nCost savings are only meaningful when reported with pass rate.\n\n## License\n\nSkeletonGraph is released under the [MIT License](LICENSE) — free to use, modify, and\ndistribute, for commercial and private projects alike.\n\n## Citation\n\nIf SkeletonGraph is useful in your research, please cite:\n\n```bibtex\n@misc{doke2026skeletongraph,\n title = {SkeletonGraph: A Zero-LLM Structural Retrieval Engine for Coding Agents,\n and Why Its Gains Land in the Cost Tail, Not the Median},\n author = {Doke, Yash},\n year = {2026},\n note = {Preprint, Research Square},\n doi = {10.21203/rs.3.rs-10749266/v1},\n url = {https://doi.org/10.21203/rs.3.rs-10749266/v1}\n}\n```\n", "bytes": 23488, "sha": "565a23c9012453585eb70d459983251e46ca59ee6f60ea33ed827f95fbd10eca", "repo_slug": "yashdoke7/skeletongraph", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_yashdoke7_skeletongraph_537acf2d/readme" }