This repository employs the use of LLMs for automatic programming.

This readme is written by a human.

treesitter-index

treesitter-index is a cli tool that uses tree-sitter to generate a source code skeleton that strips most of the code implementation but retains many of the structurally useful information that can act as an index into the source code. The resulting index output is most useful to conserve tokens and improve the agentic programming experience.

Installation

In a checked out repository:

cargo install --path .

ripgrep

ripgrep (rg) is used to pre-filter files when a regex pattern is used (-e) and more than one input file or folder is provided and needs to be available on the system.

Usage

AGENTS.md

Put this instruction in your AGENTS.md

- When analyzing source files, prefer running `treesitter-index -g <glob> <files or directories...>` early to obtain a compact structural skeleton before reading the full file, and then perform targeted reads for implementation details. Line numbers are indicated in square brackets (e.g [5] means line 5, and [5-10] means lines 5 to 10). To filter for specific top-level symbols, use `-e`, for example: `treesitter-index -g "*.ts" -i -e "manager|main" src`. Add `--match-imports` to include matching imports. Don't use `*` as the glob since that circumvents the default ignore rules.

Skill file

You can use the skill in .agents/skills/treesitter-index/SKILL.md instead of the instruction as well.

Examples

Index one file:

treesitter-index src/main.rs

Index a directory recursively, only rust files:

treesitter-index -g '*.rs' src

Filter for top-level symbols (i.e. classes, class methods, functions, markdown headings):

treesitter-index -i -e 'manager|main' src

Output the treesitter syntax tree instead of a skeleton:

treesitter-index --format json src/main.rs
treesitter-index --format sexp src/main.rs

Options

Option	Description
-t, --type <TYPE>	Set the source language. Required for standard input and overrides extension-based detection.
--format <FORMAT>	Select skeleton, json, or sexp output. Defaults to skeleton.
-g, --glob <GLOB>	Include or exclude files. Prefix an exclusion with !; rules are applied in order.
-e, --regexp <REGEXP>	Include matching top-level symbols. May be repeated and is available for skeleton output.
--match-imports	Also match and include imports when using --regexp.
-i, --ignore-case	Make regular-expression matching case-insensitive.
-h, --help	Print command-line help.
-V, --version	Print the version.

Directory traversal respects standard ignore files such as .gitignore.

Supported languages are Python, JavaScript, JSX, TypeScript, TSX, Rust, Go, Java, and Markdown (.md and .markdown).

Releasing

Release a new binary distribution on github with:

cargo release patch --no-publish --execute

Acknowledgements

This project was adapted from Maki.

License

See LICENSE and THIRD_PARTY_NOTICES.