io.github.yashdoke7/skeletongraph

Works with

Parses

SkeletonGraph indexes your repository with tree-sitter — no LLM — and hands a coding agent a ranked list of the functions relevant to its task, over MCP. It is also the instrument of a study of what better code retrieval actually buys an agent that has to fix the code, across two production agents, two Claude behavioral regimes, and two benchmarks. The short answer is below; it is more useful, and less flattering, than a token ratio.

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

What we found

We ran the same retriever in every setting we could: without an agent, in a controlled agent loop on an open-weight model, and inside Claude Code (exploratory and lean regimes) and Codex CLI, on SWE-bench Verified and the decontaminated SWE-rebench — 3,433 agent runs, every patch verified by running the project's tests, plus 500 agent-free retrieval evaluations, with every agent comparison paired by task. The evaluation covers Python repositories.

1. It finds code better than every agent's own search

Without an agent, on 100 SWE-bench Verified tasks (file level):

Inside the agents, over all tasks, SkeletonGraph's first search returned a file the fix changes on 80–92% of tasks, against 61–90% for the agents' own first search (87–96% against 60–93% on the tasks where the agent actually called it). The largest margin was Codex, where the right file came first on 71% of the tasks where it was called, instead of 32%.

2. But the agents already found the right code — so that gain doesn't reach the fix

With or without SkeletonGraph, the production agents read code from the right file on 96–100% of tasks — on SWE-bench Verified usually with their very first tool call — and edited it on 88–97%. At the level of functions, where they are far from perfect (63–69% edited a function the fix changes), SkeletonGraph did not move them either. Of the 69 tasks whose outcome differed between arms, 61 were tasks where both arms had already edited the right file: they differ in whether the change was correct, not in where it was made. No production-agent setting showed a statistically detectable solve-rate improvement from retrieval. Only an agent that often failed to find the code on its own — the controlled loop, whose search-free arm edited the right file on 65% of tasks — gained (35 → 42 solved, not statistically significant).

3. What it changes is cost — and the agent decides the direction

Where an agent spends a lot searching, reading and re-checking, SkeletonGraph replaces that work and saves; where it already finds the code in one or two calls, the retriever is added on top and costs a little more. The penalty is small and bounded; the saving grows with how much the agent would have spent.

4. Agents change underneath you

Across two Claude Code windows three weeks apart—exploratory through 2.1.274 and lean at 2.1.278, on the same tasks and prompt—the built-in agent went from 10.9 to 4.7 tool turns per task, read a fifth as much, ran code after editing on 2 tasks instead of 40, and its own first search put the right file first on 85 tasks instead of 59. The same retrieval backend, under a leaner integration, went from saving 93k tokens a task to costing 66k. The product release, available tools, account-loaded skills, integration, and possibly the served model changed together. We can describe the two regimes, not attribute the break to the version number alone. That volatility is part of the result: the meaningful unit of evaluation is the complete, versioned agent environment.

What this means if you use it

• Expect better first searches, not more solved tasks. The bottleneck for current frontier agents is turning located code into a correct fix, which retrieval does not address.
• The saving depends on the complete agent environment. It is largest with agents and tasks that explore a lot, and it can turn into a small overhead with lean ones. Measure it on your own setup.
• Integration instructions cost tokens. On Codex, the shipped integration added 53k tokens a task against 8k for the plain one, with no detectable difference in solve rate.

Every result with its confidence interval and caveats is in docs/RESULTS.md; how to reproduce it is in eval/README.md. The July 2026 preprint reported the first Claude Code release window only.

SkeletonGraph has two product surfaces:

• SG IDE: MCP context server for Cursor, Claude Code, Copilot, Codex, Antigravity, Windsurf, and other agentic IDEs.
• SG CLI: terminal pipeline for route, prepare, dry-run, provider execution, and cost-aware model selection.

How it works

SkeletonGraph parses a repository into function-level structure, a cross-file call graph, and PageRank centrality with zero LLM calls — deterministic, cheap, and instant to rebuild after every edit. At query time it resolves the symbols an issue names, walks the call graph outward, and ranks candidates by three signals — BM25, code embeddings, and structural confirmation — fused with reciprocal-rank fusion.

prompt -> (optional) retrieval planner -> classify task -> find target nodes -> expand graph -> assemble packet

sg-rerank, the product default, skips the dense leg for a lighter index; sg-fusion adds it and ranks best in our retrieval benchmark (table above).

Install

pip install skeletongraph           # core: indexing, MCP server, CLI (no API key needed)
pip install "skeletongraph[llm]"    # + litellm for sg run --execute / sg summarize --tier cloud
pip install "skeletongraph[all]"    # everything, including the evaluation harness

Quick Start: SG IDE

Use this path when you already work inside Cursor, Claude Code, Copilot, Codex, Antigravity, or another MCP-capable coding environment.

cd your-project
sg init
sg build
sg doctor

sg init writes the MCP config and the agent instruction file for the selected IDE. SG IDE does not require an API key. Your IDE subscription/model still does the reasoning and editing; SkeletonGraph supplies the retrieval.

Supported IDE setup targets include:

Quick Start: SG CLI

Use this path when you want a terminal-first context and model-routing pipeline.

cd your-project
sg build
sg route "fix the auth token validation bug"
sg prepare "fix the auth token validation bug" --out .skeletongraph/context.md
sg run "fix the auth token validation bug" --dry-run

sg route, sg prepare, and sg run --dry-run do not need an API key.

To call a provider:

sg config --cli-provider anthropic
$env:ANTHROPIC_API_KEY = "..."
sg run "fix the auth token validation bug" --execute

To test locally without a paid provider key:

ollama pull qwen3-coder:latest
ollama serve
sg config --cli-provider local
sg run "fix the auth token validation bug" --dry-run
sg run "fix the auth token validation bug" --execute

Local execution is intended for cheap pipeline testing. Use provider models for quality benchmarks unless the benchmark is specifically for local models.

Model Dependency, Prewarming, and Keeping the Index Fresh

SG downloads two small embedding models on first use, both via sentence-transformers (a hard dependency, not optional):

• jinaai/jina-embeddings-v2-base-code (SG_DENSE_MODEL) — the semantic leg of fusion/sg_search. Loaded on sg warm or on an agent's first dense-retrieval query. Loads with trust_remote_code=True (Jina ships custom modeling code on the HF Hub) — this executes code from that model repo, same as any trust_remote_code model.
• all-MiniLM-L6-v2 (SG_EMBED_MODEL) — a smaller, separate model used only as a confidence-score tiebreaker at index time. Downloads automatically on the first sg build, not on sg warm.

Both need internet access the very first time each is used on a machine — after that, both are cached locally (Hugging Face's model cache, plus SG's own content-hash caches: .skeletongraph/dense_cache for the dense leg, .skeletongraph/embeddings.npz for the confidence tiebreaker) — so later builds are incremental: only functions whose text actually changed get re-embedded.

Prewarm before launching an agent, so that cost lands during setup instead of on the agent's first real search:

sg build                 # parse + structural index (no LLM, fast)
sg warm --path .          # prebuild BM25 + dense caches (one-time; minutes on CPU)
sg warm --path . --mode rerank   # skip the dense leg entirely (no embedding cost)

Without this, the first sg_search call an agent makes pays the cold-encode cost inline — on a large repo this can exceed the dense retrieval leg's internal timeout (SG_DENSE_TIMEOUT_S, 20s by default), in which case it silently degrades to a 2-signal (lexical + structural) result rather than failing outright. Prewarming avoids relying on that fallback altogether.

Keeping the index current as files change — two options, pick based on how you work:

sg update --path .        # one-shot: re-index only files that changed since last build
sg watch --path .         # background daemon: auto-reindexes on save (needs `pip install "skeletongraph[daemon]"`)

sg watch is the hands-off option for active development — it debounces rapid saves and calls the same incremental update path as sg update, so editing a file is reflected in the index without a manual rebuild.

Model Routing

SkeletonGraph separates IDE-facing model labels from CLI provider model names.

For IDEs, model tiers are recommendations:

For CLI execution, SkeletonGraph can route to provider model names:

sg config --cli-provider anthropic
sg config --cli-provider openai
sg config --cli-provider google
sg config --cli-provider local

Dynamic routing uses task mode, confidence, candidate count, token size, and complexity. Code-changing work keeps an MLM floor by default so cost savings do not come from making weak models edit code unsafely. Retrieval planning can use small models to propose targets over AST/summaries before the heavy model runs.

IDE Integration

After sg init and sg build, register SG as an MCP server and write IDE hooks:

sg install --ide claude-code   # Claude Code: hooks + MCP server + CLAUDE.md rules
sg install --ide cursor        # Cursor: MCP + .cursor/rules/skeletongraph.mdc + hooks
sg install --ide cline         # Cline: MCP config + rules block
sg install --ide roo           # Roo: MCP config + rules block
sg install --ide copilot       # GitHub Copilot: MCP + copilot-instructions.md
sg install --ide windsurf      # Windsurf: MCP + .windsurfrules
sg install --ide zed           # Zed: MCP config + rules block
sg install --ide continue      # Continue: MCP config + rules block
sg install                     # auto-detect all installed IDEs

codex and antigravity are accepted as aliases and currently route through the Copilot-style MCP installer.

For any other MCP-capable client, or to configure it by hand, see mcp.example.json for the raw server config (sg serve --path /path/to/your/project). The "plain" integration measured above is the server started with SG_MCP_PLAIN=1, which removes the guidance text from tool descriptions and results, registered without the rules and hooks sg install writes.

After install, restart your editor. SkeletonGraph runs as a background MCP server (sg serve --path .) that the IDE connects to automatically.

MCP Tools

Seven tools are exposed to the agent:

Smart context routing. On each UserPromptSubmit, SG classifies the prompt (architecture / explain / decision / debug / test / review / general) and includes the matching MD file from .skeletongraph/ — e.g. architecture.md only for design/refactor queries, project.md only for "what is this codebase" queries. Constraints + session digest + relevant functions are always injected.

Cold start. If no .skeletongraph/ index exists when an MCP tool is called, SG auto-builds on first invocation (see auto_build_on_query in config).

CLI Reference

Indexing & status

Retrieval

Constraints & session

Summarization

Model routing & execution

Background indexing

Provider output from sg run --execute is written to .skeletongraph/runs/.

Python API

from skeletongraph.engine import SGEngine

engine = SGEngine(project_root=".")
result = engine.query("fix the content-length bug", delivery="cli")

print(result.context_text)
print(result.query_mode)
print(result.model_tier)
print(result.recommended_model)
print(result.routing_reason)

Repository layout

src/skeletongraph/      the package
  parser/                 AST extraction (tree-sitter)
  graph/                  dependency graph and ranking
  storage/                .skeletongraph persistence
  retrieval/              classification, resolution, model routing
  assembly/               context packet construction
  session/                memory and dedup
  server/                 MCP server
  install/                per-IDE hook + MCP config writers (`sg install`)
  hooks/                  IDE hook handlers
  llm/                    LiteLLM wrapper for optional CLI execution
  cli/                    Click commands
  engine.py               unified query pipeline
tests/                  unit tests (pytest)
eval/                   the evaluation harness — see eval/README.md
  datasets/               the frozen task sets
docs/
  RESULTS.md              every result, with confidence intervals and caveats
  assets/                 README images and the script that draws the banner and hero

Reproducing the results

Everything — task sets, drivers for every agent, verification, and the scripts behind every number and figure — is in eval/. The per-run records and transcripts are several gigabytes and are published with the tagged release rather than in git. eval/results_summary.json holds the computed results, so the figures regenerate without them:

pip install -e ".[all]"
python -m eval.scripts.make_submission_figures

License

SkeletonGraph is released under the MIT License — free to use, modify, and distribute, for commercial and private projects alike.

Citation

If SkeletonGraph is useful in your research, please cite the preprint:

@misc{doke2026skeletongraph,
  title  = {SkeletonGraph: A Zero-LLM Structural Retrieval Engine for Coding Agents,
            and Why Its Gains Land in the Cost Tail, Not the Median},
  author = {Doke, Yash},
  year   = {2026},
  note   = {Preprint, Research Square},
  doi    = {10.21203/rs.3.rs-10749266/v1},
  url    = {https://doi.org/10.21203/rs.3.rs-10749266/v1}
}