为编码 Agent 提供基于 tree-sitter 的结构化、字节精确、低 token 消耗的代码库访问能力

https://github.com/Entelligentsia/grove…

用 Rust 写了一个双面工具：既当 CLI 也用 MCP 协议跑，核心是靠 tree-sitter 语法树给 AI Agent 提供代码结构信息，不用 grep 也不用读整个文件。

支持 27 种语言，有 7 个工具：outline 看文件骨架、source 取单个符号的源码、map 看目录的依赖关系、callers 查谁调了它、definition 跳定义、symbols 搜符号、check 检查语法错误。

Entelligentsia/grove

Source: https://github.com/Entelligentsia/grove

grove — structural sight for coding agents

grove gives coding agents structural, byte-precise, token-cheap access to a codebase via tree-sitter — instead of reading whole files. One engine, seven tools, two faces (a human CLI grove <verb> and an MCP server grove serve), with grammars loaded at runtime from a WASM registry, so adding a language needs no recompile and no toolchain on the consumer.

(asciinema cast: docs/assets/grove_demo.cast — play it interactively with asciinema play docs/assets/grove_demo.cast.)

Why grove

Agents burn tokens and round-trips grep-ing and read-ing whole files to answer “where is this defined / what does it do / who calls it.” grove replaces that with one symbol at a time, by exact bytes, behind a stable id the agent passes between turns.

• Token-cheap — outline a 1700-line file as a skeleton; source one symbol’s body, not the whole file. A map call returns a directory’s definitions + references in one shot.
• Byte-precise & stable — every result carries a symbol-id (<lang>:<relpath>#<name>@<line>, 1-based) you pass forward across turns.
• One engine, two faces — the same Rust binary drives the CLI and an MCP server, so a human and an agent see the same thing.
• Runtime grammars — all 27 official tree-sitter grammars load from a hosted WASM registry; new languages are a registry entry, not a recompile.

Not an LSP. grove is a syntactic, tree-sitter-powered shell for agents — not a semantic language server. It speaks MCP (not LSP), parses (doesn’t analyze), and locates (doesn’t refactor): no type inference, completion, rename, or type-resolved go-to-def. It’s the cheap syntactic layer beneath where an LSP’s semantics begin — complementary, not competitive. Full reasoning: Is grove an LSP?.

27 languages out of the box — one binary, grammars loaded at runtime from the hosted WASM registry:

Bash	C	C++	C#	Go	Java	JavaScript	Julia
PHP	Python	Ruby	Rust	Scala	TypeScript	TSX	Agda2
CSS2	Embedded Template2	Haskell2	HTML2	JSDoc2	JSON2	OCaml2	OCaml Interface2
CodeQL2	Regex2	Verilog2

² minimal profile — core tools only (callers/definition degrade); full profile = all tools. <kbd> = no official logo. Profiles are data, not compiled in. See Languages & grammars.

See VISION.md for the product vision.

Quick start

# 1. install (one line — detects platform, verifies sha256)
curl -fsSL https://raw.githubusercontent.com/Entelligentsia/grove/main/install.sh | sh

# 2. wire it into a project (in the project root)
grove init

grove init detects the project’s languages, auto-fetches their grammars, and writes .mcp.json (the tools exist) + a CLAUDE.md steering directive (the agent reaches for grove instead of grep) + grove.lock. That’s it — your agent now has structural sight. Other install channels (Homebrew, npm, cargo, agent skill) and --as mcp|skill|both are in Install and Setup.

As an agent skill (Claude Code, Cursor, Codex, Cline, …): npx skills add Entelligentsia/grove — the skill self-installs the binary on first use if it’s missing. See Setup.

Evaluated on real codebases

grove is measured in is-grep-enough — a fair, blind-judged comparison of three navigation regimes (text baseline, structural grove, semantic lsp) given the same agent the same prompt across 50 tasks: 10 large, popular, grammar-backed repos × 5 rungs of climbing complexity (locate a symbol → trace flow → recover an architecture). Same substrate, one variable — the navigation capability. Explore every run in the live dashboard.

The result is a curve, not a verdict:

• Answer quality ties — and on the hardest traces grove is the more reliable one. Grounding ~0.97 and completeness ~0.99 across all three arms; grep is enough to be correct most of the time. But where text search drifts on a dense trace — the C++ L5 architecture trace drops baseline grounding to 0.80 — grove holds 0.97, because it cites the real syntax tree instead of guessing line numbers.
• grove runs leaner on context, and the lead widens with complexity. ~395K mean tokens vs 567K (lsp) and 780K (baseline) overall — roughly half the text-search context. By the hardest rung (architecture / binding-spine), baseline pushes ~1.5M tokens against grove’s ~534K — 2.8× leaner (on the TypeScript L5 trace, 2.43M → 570K, 4.3× leaner) — while grove stays tightest on quality.
• Reported honestly, including where grove doesn’t win. On trivial locate-one-symbol tasks (L1), grove’s fixed structural-call overhead means it isn’t the cheapest — plain text search is. grove pays off on the navigation that actually costs tokens: tracing flow, mapping a subsystem, recovering an architecture.

Token throughput isn’t the billed bill — much of baseline’s volume is cheap cache reads — but it is what drives context-window pressure and latency. Full methodology, per-repo data, blind judgements, and every raw transcript: is-grep-enough · live dashboard.

The tools

Add --json to any command for the agent-facing shape. Full reference + examples: Tools.

As a library — grove-core

The same engine ships as a standalone crate, grove-core, so you can embed grove’s structural queries directly in Rust — no subprocess, no CLI. The grove binary is a thin clap + MCP shell over it. The crate is clap-free; grammars still load at runtime from the WASM registry, so nothing is compiled in.

On crates.io as grove-cst — CST for the concrete syntax trees tree-sitter builds (grove-core is taken by an unrelated crate). Alias it so imports stay use grove_core::…:

# Cargo.toml
[dependencies]
grove_core = { package = "grove-cst", version = "0.1" }

use std::path::Path;
use grove_core::{init, ops};

fn main() -> anyhow::Result<()> {
    let project = Path::new(".");

    // 1. Provision grammars for this project's languages — fetches any missing
    //    grammar into the OS cache and pins grove.lock. Run once.
    for action in init::provision_project(project, false)? {
        println!("provisioned: {action}");
    }

    // 2. Query — grammars resolve from the cache. Every definition under `src/`,
    //    gitignore-aware, as typed results.
    for s in ops::symbols(&project.join("src"), None, None, false, false)? {
        println!("{} {} — {}:{}", s.kind, s.name, s.file, s.line);
    }
    Ok(())
}

(Offline? Set GROVE_REGISTRY=<dir> to resolve grammars from a pinned registry and skip the fetch — see core/README.md.)

The consumer surface is the ops module — the same seven tools (outline, symbols, source, check, callers, map, definition), returning typed Symbol / Defect / CallSite / FileMap values (re-exported at the crate root). init::provision_project is the grammar-provisioning entry point behind grove init. Crate overview and full API surface: core/README.md · core/src/lib.rs.

Documentation

• Install — curl/Homebrew/npm/cargo, build from source, the agent skill
• Setup — grove init, --as mcp|skill|both, what it writes, offline/dry-run
• Languages & grammars — the WASM registry, fetch/lock, where grammars live, profiles
• Tools — the seven tools, --json, symbol-id, examples
• MCP server — grove serve, .mcp.json, steering, error model
• Library — grove-core: embed the engine in Rust (no CLI, no subprocess)
• Roadmap & repo layout — what’s not done yet, source map
• FAQ — Is grove an LSP? and other positioning questions
• VISION.md — product vision · CHANGELOG.md — releases
• Eval: Entelligentsia/is-grep-enough — text vs structural vs semantic navigation, same agent, 50 blind-judged tasks · live dashboard
• Registry: Entelligentsia/grove-registry · Homebrew tap: Entelligentsia/homebrew-grove

Status

Pre-1.0. callers/definition are name-based (no receiver-type resolution); 12 languages ship a minimal profile (core tools only); no incremental reparse yet. Details and the rest of the roadmap: Roadmap.