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