Skeletongraph README

Works with 

Languages 

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

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.

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

SkeletonGraph is a retrieval engine purpose-built for coding agents, not a general RAG library retrofitted onto code. It 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 reranks a BM25 recall pool by structural confirmation so the agent lands on the right function on the first try, instead of grepping and re-reading its way there. Its leaner operating point, sg-rerank (the product default), skips the dense leg entirely and still delivers the best file and function recall of any method we benchmarked it against — at the lowest token cost of any of them.

The thesis: code-context tools have mostly been validated as a token-optimization game — how few tokens can you spend. SkeletonGraph re-centers the question on retrieval quality — did the agent land on the correct function — of which lower token cost turns out to be a consequence, measurable only end-to-end inside a real agent loop, not in an offline benchmark.

Results

All numbers below are regenerated from the released run artifacts (python -m eval.scripts.make_paper_figures). The full verified ledger, including withdrawn claims, is in docs/paper/FINDINGS.md.

1. Controlled retrieval ablation (react loop, open-weight model, 100 tasks)

Identical action space for every arm; only the retrieval backend changes. The none arm gets no code access at all and establishes the memorization floor.

sg-fusion is the top arm, the cheapest arm, and the only one that localizes to the function (57% vs grep's 0% — lexical search is file-granular by construction). Against the closed-book floor of 35.0%, retrieval is worth +7 points here.

sg-rerank's recall/cost profile is reported separately in the agent-free intrinsic retrieval ablation in the paper (Table 2, §5.1) — best MRR/recall@10 short of full fusion, at the lowest index cost.

2. Deployment: SkeletonGraph vs native Claude Code (MCP, Docker-verified)

The product itself — SG as an MCP server driving Claude Code (sonnet) against Claude Code on its own tools. 100 paired SWE-bench Verified tasks:

_{SG's first-search recall excludes 3 tasks where the agent never called SG at all — those are adoption events, not retrieval failures. Including them gives .836.}

Equivalent solve rate at −14.6% cost and −21.4% turns. The saving is not spread evenly — it lives almost entirely in the tail:

Retrieval does nothing for the typical task and removes over 40% of the cost of the worst ones. Paired bootstrap 95% CI on the mean: [−25.3%, −1.2%]; McNemar on pass@1: p = 1.0 (no difference).

3. What the numbers don't cover

That tail effect is where the chart above comes from. Retrieval quality itself holds up under real stress-testing: it survives having all the location cues (tracebacks, code blocks) stripped from the issue text, and it survives on a decontaminated benchmark of repos the model hasn't memorized. But better retrieval doesn't move the solve rate (McNemar p=1.0), and an agent given enough turns to explore on its own eventually learns a repo about as well as a ranked list tells it — retrieval buys speed and cost, not a ceiling past what patient exploration reaches.

Full methodology — the n=15→50 revision, the dose-response check, the cumulative-recall mechanism, and every withdrawn claim — is in the paper and docs/paper/FINDINGS.md.

SkeletonGraph is wrapper-first: it returns a full context packet or exposes a retrieval index (AST skeletons + call graph + local summaries + optional embeddings) so the IDE agent or CLI can choose targets.

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.

Why SkeletonGraph

Most coding agents spend expensive turns discovering the repo:

search -> read file -> read neighbor -> read tests -> realize the target

SkeletonGraph moves that work into a deterministic graph pipeline:

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

The goal is not only lower token cost. The useful product outcomes are:

• fewer exploratory file reads
• faster first useful answer
• better target/test/blast-radius context
• transparent routing reasons
• lower model overkill for routine tasks
• reusable packets for IDEs, CLIs, and other agents

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

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 packet or retrieval signals for efficient target selection.

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

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 IDE agent. Use these instead of grep/glob/file reads:

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/. Evaluation is currently done externally via a SWE-bench harness (see the Evaluation section below).

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)

Architecture

src/skeletongraph/
  parser/       AST extraction
  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 (prompt-submit routing, etc.)
  llm/          LiteLLM wrapper for optional CLI execution
  cli/          Click commands
  engine.py     unified query pipeline

Evaluation

The full methodology, verified results, and every withdrawn/superseded claim are in the paper and docs/paper/FINDINGS.md.

SkeletonGraph should be evaluated on both quality and cost:

• target recall and packet completeness
• missed tests/callers
• first useful answer latency
• file reads after SG context
• pass rate
• cost per passing task
• dynamic routing overkill/underpower rate
• IDE compliance with SG-first context usage

Cost savings are only meaningful when reported with pass rate.

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:

@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}
}