skeletree 0.1.1

Your agent stops reading your codebase and starts querying it.

A local indexer that turns any repo into a queryable graph of symbols, calls, imports and dependencies, and exposes it over MCP — so AI agents navigate code structure with hundreds of tokens instead of tens of thousands.

Status: early development. Python, TypeScript/TSX, JavaScript/JSX and Rust — NestJS, React and Next.js all index out of the box.

What it does

Skeletree parses a repository with tree-sitter, extracts every symbol (functions, classes, methods, interfaces, type aliases, constants) and the relationships between them (calls, imports, defines, references, extends), stores the result as a graph in a local SQLite file, and ranks symbols by PageRank centrality. An agent then queries that graph over MCP instead of grepping and reading files.

Each MCP response is token-budgeted: you ask for a map, a search, or a symbol's neighbors and get back compact text trimmed to a token ceiling, so a query costs hundreds of tokens where reading the files would cost tens of thousands.

How it works

walk (respect .gitignore) → parse (tree-sitter, in parallel)
  → persist symbols (SQLite, one transaction)
  → resolve edges (name-based)  → rank (PageRank)

1. Walk — ignore crate honors .gitignore; files are matched to a language by extension.
2. Parse — each file goes through a tree-sitter grammar + .scm queries; parsing is CPU-bound and runs across cores with rayon.
3. Persist — symbols are written in a single SQLite transaction. A full reindex replaces the previous contents atomically.
4. Resolve edges — refs are linked to symbols by name (preferring the same file). This is a heuristic, not an LSP: false positives are accepted and PageRank buries them.
5. Rank — PageRank over the edge graph scores each symbol's centrality, so the most-connected code surfaces first.

The index lives at <repo>/.skeletree/index.db — a portable SQLite file.

Language support

Frameworks that need no special handling — they're just the languages above:

• NestJS — decorated classes/methods (@Controller, @Injectable, @Get) parse as plain nodes.
• React — function, arrow, and class components; hooks. <Child/> usage becomes a references edge, so the component graph feeds ranking.
• Next.js — .tsx/.jsx pages and components index the same way.

Scope roadmap

Ordered by intended arrival. Nothing below blocks indexing today — it sharpens precision and widens coverage.

Adding a language is a self-contained change behind the Language trait — see Adding a language.

Workspace layout

Commands

serve reads the existing index; stats and serve fail with a clear message if you haven't indexed yet. export, init, and serve --watch are on the roadmap and currently stubs.

MCP tools

Point any MCP client at skeletree serve. It exposes three tools, each accepting a token_budget (default 1500):

Usage

Install the binary (once published):

cargo install skeletree

Index your repo — this writes .skeletree/index.db:

cd your-repo
skeletree index .
skeletree stats --limit 10       # sanity-check the ranking

Then wire skeletree serve into your agent as an MCP server. Run it from the repo root — it reads .skeletree/index.db relative to the current directory.

Claude Code

cd your-repo
claude mcp add skeletree -- skeletree serve

That writes the server into .mcp.json (project scope). Add -s user to make it available in every project instead. Verify with claude mcp list.

Codex

Codex reads MCP servers from ~/.codex/config.toml. Add:

[mcp_servers.skeletree]
command = "skeletree"
args = ["serve"]

Because serve resolves the index from the current directory, launch Codex from the repo root you indexed.

Any other MCP client

Point it at the skeletree binary with the serve argument:

{
  "mcpServers": {
    "skeletree": {
      "command": "skeletree",
      "args": ["serve"]
    }
  }
}

Development

Requires a recent stable Rust toolchain (pinned in rust-toolchain.toml).

cargo build --workspace           # build everything
cargo test  --workspace           # run all tests
cargo run -p skeletree -- --help

Try it end to end against this repo or any Python project:

cargo run -p skeletree -- index /path/to/python/repo
cargo run -p skeletree -- stats /path/to/python/repo --limit 20

CI runs build + test + clippy + fmt (.github/workflows/ci.yml).

Adding a language

The one extension point is the Language trait in skeletree-lang:

1. Implement Language for the new grammar (see python.rs).
2. Drop .scm queries whose capture names match the SymbolKind / EdgeKind strings.
3. Register it in Registry::with_defaults.
4. Map its file extensions in Lang::from_extension (skeletree-core).

License

Apache-2.0