| name | tsa-find |
| description | | Use when this capability is needed. |
tsa-find — File / text search, sized for agents
The "I just want to find X" skill. Wraps fd + rg + sized partial reads
with consistent output formatting.
Tool routing
| Question | Tool |
|---|
| Filename pattern only | project action=files |
| Content pattern only (regex / literal) | search action=content |
| Filename pattern AND content | search action=grep |
| Several patterns in one call (≥2) | search action=batch |
| Read specific lines of one file | structure action=read |
| "Is this file too big to read fully?" | health action=scale |
Procedure
Single search
search action=content query="TODO" roots=["tree_sitter_analyzer/"] include_globs=["*.py"]
Returns: matches: [{file, line, content}] with sized previews. Always
includes file:line so the agent can cite without reading the file.
Sized partial read (the killer feature)
Before reading a large file blind, use:
health action=scale file_path="tree_sitter_analyzer/ast_cache.py"
Then extract only what you need:
structure action=read file_path="..." start_line=800 end_line=870
Avoids reading 80KB when you need 2KB.
Combined find+grep
search action=grep file_pattern="test_*.py" content_pattern="def test_synapse"
CLI equivalents
uv run tree-sitter-analyzer --project-root . --outline
uv run tree-sitter-analyzer --check-tools
uv run tree-sitter-analyzer <file> --partial-read
Anti-patterns
- DON'T
Read a large file before checking scale — burns tokens
- DON'T
Bash grep -rn for things search action=content handles — slower + noisier
- DON'T call
search action=batch with a single query — it enforces a ≥2-query minimum (raises "must be at least 2 queries"); use search action=content for one pattern
- DON'T re-search the same query twice in one session — cache the result mentally
Source: aimasteracc/tree-sitter-analyzer — distributed by TomeVault.