@josephakern/pi-tree-sitter-cli

Thin pi extension exposing the tree-sitter CLI as capped agent tools.

Packages

Package details

extensionskill

Install @josephakern/pi-tree-sitter-cli from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:@josephakern/pi-tree-sitter-cli

Package: @josephakern/pi-tree-sitter-cli
Version: 0.2.1
Published: Jun 17, 2026
Downloads: not available
Author: josephakern
License: unknown
Types: extension, skill
Size: 57.2 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@josephakern/pi-tree-sitter-cli

Thin pi extension for exposing the existing tree-sitter CLI to agents.

Contract

This package does not install, bundle, or vendor Tree-sitter itself. It requires an existing tree-sitter executable on PATH, or an explicit TREE_SITTER_BIN=/absolute/path/to/tree-sitter.

If the executable is missing, tools fail with installation/configuration guidance instead of silently falling back or attempting auto-installation.

Optional grammar acquisition is explicit: tree_sitter_grammar_install installs npm grammar packages into a tool-local cache and writes a tool-local Tree-sitter config. It does not mutate your global Tree-sitter config. Tree-sitter and npm cache paths are also kept under the tool-local cache when these tools execute.

Principle

Expose the tool, do not domesticate it. Tree-sitter's query language is the abstraction; this package should stay a safe, capped, convenient doorway to the CLI.

Status

Implemented:

tree_sitter_languages — wraps tree-sitter dump-languages
tree_sitter_parse — wraps tree-sitter parse
tree_sitter_query — wraps tree-sitter query
tree_sitter_tags — wraps tree-sitter tags
tree_sitter_grammar_status — inspects the tool-local grammar cache
tree_sitter_grammar_install — explicitly installs npm grammar packages into the tool-local cache

The minimal Tree-sitter CLI plan from ../../PLAN.md is implemented, plus optional tool-local npm grammar management.

Query recipes

This package also ships a small recipe catalog. Recipes are plain .scm files plus the tree-sitter-recipes skill; they do not wrap or replace the raw tools.

Included query files:

queries/
  universal/syntax-errors.scm
  typescript/function-signatures.scm
  typescript/imports.scm
  typescript/tool-registrations.scm
  javascript/function-signatures.scm
  python/function-signatures.scm

The skill recommends using tree_sitter_tags first for navigation, then tree_sitter_query with a recipe file when richer captures are needed.

For project-specific patterns, prefer adding .scm files under .pi/tree-sitter/queries/ or tree-sitter/queries/ instead of adding wrapper tools.

Development

From the repository root:

npm install
npm run check

Temporary pi load:

pi -e ./packages/pi-tree-sitter-cli

Project-local install once stable:

pi install -l ./packages/pi-tree-sitter-cli

Set TREE_SITTER_BIN if tree-sitter is not on PATH. Set PI_TREE_SITTER_CLI_HOME to override the managed grammar cache directory.