tree-sitting
Symbol-level navigation of a local checkout using tree-sitter ASTs. Answers where a symbol is defined, what lines it spans, which symbols a file exposes, what a directory holds, and where a name is referenced — every answer carries exact line ranges to feed straight into a scoped
Install
npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/code-intelligence/skills/tree-sitting
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
git clone https://github.com/oaustegard/claude-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.
README
tree-sitting
AST-powered code navigation using tree-sitter. Parses all source files in a codebase into in-memory syntax trees, then provides fast query tools for symbol search, file/directory overview, source retrieval, and reference finding.
Features
- Fast scanning — parses ~250 files in ~700ms, then all queries are sub-millisecond from cache
- Symbol search — find by exact name, substring, or glob pattern across the entire codebase
- Directory and file overview — structural summaries with symbol counts, signatures, and doc comments
- Source retrieval — fetch implementation of any symbol, preferring definitions over declarations
- Reference finding — locate all textual references to a symbol via fast grep against cached source
- 12 grammars — Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown, Mojo. Bundled for Linux x86_64 (
.so) and macOS (.dylib);scripts/build_grammars.pycompiles them anywhere else. - Three-tier extraction — custom extractors (richest), community tags.scm queries, and generic heuristic fallback
- Dual deployment — direct Python calls in Claude.ai, or long-lived MCP server in Claude Code
Dependencies
- tree-sitter — bare parser runtime
- Python 3.10+ — the grammars are ABI 15, which needs the tree-sitter >= 0.25 binding
- fastmcp — required only for MCP server mode (Claude Code)
Skill manifest
tree-sitting
Tree-sitter symbol index over a local checkout. Every result carries line
ranges, so the next step is a scoped Read.
Setup
Needs Python 3.10+ and pip install tree-sitter. On macOS, /usr/bin/python3
is 3.9 and will not work; use a Homebrew or uv Python. Grammars are bundled
for Linux x86_64 (parsers/*.so) and macOS (parsers/*.dylib).
If a file's grammar doesn't load, the file is skipped and stderr prints
WARNING: no grammar for … with the fix. Resolve that before trusting an empty
result. On other platforms, run python3 scripts/build_grammars.py (needs git
and cc). It writes to $TREESIT_PARSERS_DIR, or ~/.cache/tree-sitting/parsers/
when that is unset, and grammars there take precedence over the bundle.
Installed tree-sitter-<lang> wheels are the last fallback.
Use
scripts/treesit.py in this skill's directory scans the repo on every call
(cached on disk; invalidated when files or grammars change), prints a tree
overview, then answers the queries. Batch queries so one scan serves them all.
python3 scripts/treesit.py REPO # overview, depth 1
python3 scripts/treesit.py REPO --path=src/core --detail=full # drill in
python3 scripts/treesit.py REPO --no-tree 'find:Parser*' 'source:parse_input' 'refs:ParseState'
| Query | Returns |
|---|---|
find:PATTERN[:KIND[:LIMIT]] |
symbols by name, substring or glob |
symbols:FILE |
every symbol in a file |
source:SYMBOL[:FILE] |
the symbol's source |
refs:SYMBOL[:LIMIT] |
textual references |
imports:FILE |
a file's imports |
dir:PATH |
directory overview |
Flags: --depth N (-1 = all), --detail sparse|normal|full, --path DIR,
--skip DIRS, --no-tree, --stats, --no-cache, --rebuild-cache.
scripts/engine.py exposes CodeCache for use inside one Python process.
Languages: Python, JavaScript, TypeScript/TSX, Go, Rust, Ruby, Java, C, HTML,
Markdown (heading outline), Mojo. Other languages get generic extraction if
their tree-sitter-<lang> wheel is installed.
Use something else for
- a repo that isn't on disk:
accessing-github-repos - what a codebase does:
featuring - a first look at an unfamiliar repo:
exploring-codebases - binding-resolved Python callers:
searching-codebases --refs - literal text or regex:
rg
Files (claude-skills)
-
parsers
-
libtree_sitter_c.dylib 1.2 MB · in bundle
-
libtree_sitter_c.so 612.8 KB · in bundle
-
libtree_sitter_go.dylib 483.5 KB · in bundle
-
libtree_sitter_go.so 232.4 KB · in bundle
-
libtree_sitter_html.dylib 98.5 KB · in bundle
-
libtree_sitter_html.so 33.1 KB · in bundle
-
libtree_sitter_java.dylib 868.8 KB · in bundle
-
libtree_sitter_java.so 423.6 KB · in bundle
-
libtree_sitter_javascript.dylib 853.7 KB · in bundle
-
libtree_sitter_javascript.so 425.5 KB · in bundle
-
libtree_sitter_markdown.dylib 776.4 KB · in bundle
-
libtree_sitter_markdown.so 363.5 KB · in bundle
-
libtree_sitter_mojo.dylib 1.3 MB · in bundle
-
libtree_sitter_mojo.so 681.1 KB · in bundle
-
libtree_sitter_python.dylib 933.6 KB · in bundle
-
libtree_sitter_python.so 473.1 KB · in bundle
-
libtree_sitter_ruby.dylib 4.1 MB · in bundle
-
libtree_sitter_ruby.so 2 MB · in bundle
-
libtree_sitter_rust.dylib 2.2 MB · in bundle
-
libtree_sitter_rust.so 1.1 MB · in bundle
-
libtree_sitter_tsx.dylib 2.8 MB · in bundle
-
libtree_sitter_tsx.so 1.4 MB · in bundle
-
libtree_sitter_typescript.dylib 2.7 MB · in bundle
-
libtree_sitter_typescript.so 1.4 MB · in bundle
-
-
scripts
-
build_grammars.py 3.9 KB
Loading… -
engine.py 76.8 KB
Loading… -
server.py 6.6 KB
Loading… -
treesit.py 14.6 KB
Loading…
-
-
tests
-
test_cache_fingerprint.py 11.5 KB
Loading… -
test_cache_lazy_source.py 10.3 KB
Loading… -
test_cache_lifecycle.py 30.3 KB
Loading… -
test_cache_roundtrip.py 18.9 KB
Loading… -
test_cli_cache.py 14.5 KB
Loading… -
test_engine.py 19 KB
Loading… -
test_grammar_sources.py 2.9 KB
Loading…
-
-
CHANGELOG.md 4.7 KB
Loading… -
README.md 1.4 KB
# tree-sitting AST-powered code navigation using tree-sitter. Parses all source files in a codebase into in-memory syntax trees, then provides fast query tools for symbol search, file/directory overview, source retrieval, and reference finding. ## Features - **Fast scanning** — parses ~250 files in ~700ms, then all queries are sub-millisecond from cache - **Symbol search** — find by exact name, substring, or glob pattern across the entire codebase - **Directory and file overview** — structural summaries with symbol counts, signatures, and doc comments - **Source retrieval** — fetch implementation of any symbol, preferring definitions over declarations - **Reference finding** — locate all textual references to a symbol via fast grep against cached source - **12 grammars** — Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown, Mojo. Bundled for Linux x86_64 (`.so`) and macOS (`.dylib`); `scripts/build_grammars.py` compiles them anywhere else. - **Three-tier extraction** — custom extractors (richest), community tags.scm queries, and generic heuristic fallback - **Dual deployment** — direct Python calls in Claude.ai, or long-lived MCP server in Claude Code ## Dependencies - **tree-sitter** — bare parser runtime - **Python 3.10+** — the grammars are ABI 15, which needs the tree-sitter >= 0.25 binding - **fastmcp** — required only for MCP server mode (Claude Code) -
SKILL.md 3.1 KB
--- name: tree-sitting description: Symbol-level navigation of a local checkout using tree-sitter ASTs. Answers where a symbol is defined, what lines it spans, which symbols a file exposes, what a directory holds, and where a name is referenced — every answer carries exact line ranges to feed straight into a scoped read. Use for "where is X defined", "who calls X", "find the function/class named", "what's in this file", "give me the line range for", "show me the source of", "list the symbols in", or before editing a file you have not read. Each invocation auto-scans and is self-contained. Not for first-encounter repo orientation (use exploring-codebases), for what a codebase DOES rather than what it contains (featuring), for binding-resolved Python caller sets (searching-codebases), or for literal text and regex matching (plain ripgrep). metadata: version: 0.10.1 --- # tree-sitting Tree-sitter symbol index over a local checkout. Every result carries line ranges, so the next step is a scoped `Read`. ## Setup Needs Python 3.10+ and `pip install tree-sitter`. On macOS, `/usr/bin/python3` is 3.9 and will not work; use a Homebrew or uv Python. Grammars are bundled for Linux x86_64 (`parsers/*.so`) and macOS (`parsers/*.dylib`). If a file's grammar doesn't load, the file is skipped and stderr prints `WARNING: no grammar for …` with the fix. Resolve that before trusting an empty result. On other platforms, run `python3 scripts/build_grammars.py` (needs git and cc). It writes to `$TREESIT_PARSERS_DIR`, or `~/.cache/tree-sitting/parsers/` when that is unset, and grammars there take precedence over the bundle. Installed `tree-sitter-<lang>` wheels are the last fallback. ## Use `scripts/treesit.py` in this skill's directory scans the repo on every call (cached on disk; invalidated when files or grammars change), prints a tree overview, then answers the queries. Batch queries so one scan serves them all. ```bash python3 scripts/treesit.py REPO # overview, depth 1 python3 scripts/treesit.py REPO --path=src/core --detail=full # drill in python3 scripts/treesit.py REPO --no-tree 'find:Parser*' 'source:parse_input' 'refs:ParseState' ``` | Query | Returns | |---|---| | `find:PATTERN[:KIND[:LIMIT]]` | symbols by name, substring or glob | | `symbols:FILE` | every symbol in a file | | `source:SYMBOL[:FILE]` | the symbol's source | | `refs:SYMBOL[:LIMIT]` | textual references | | `imports:FILE` | a file's imports | | `dir:PATH` | directory overview | Flags: `--depth N` (-1 = all), `--detail sparse|normal|full`, `--path DIR`, `--skip DIRS`, `--no-tree`, `--stats`, `--no-cache`, `--rebuild-cache`. `scripts/engine.py` exposes `CodeCache` for use inside one Python process. Languages: Python, JavaScript, TypeScript/TSX, Go, Rust, Ruby, Java, C, HTML, Markdown (heading outline), Mojo. Other languages get generic extraction if their `tree-sitter-<lang>` wheel is installed. ## Use something else for - a repo that isn't on disk: `accessing-github-repos` - what a codebase does: `featuring` - a first look at an unfamiliar repo: `exploring-codebases` - binding-resolved Python callers: `searching-codebases --refs` - literal text or regex: `rg`
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.