| name | tsa-graph |
| version | 2.0.0 |
| description | Code archaeology via call graph + symbol resolution. Answer "who calls X",
"what does Y call", "where is Z defined", "what's the path from A to B" in
one MCP call instead of multi-step grep + read. Uses persisted cross-file
resolution (Synapse) so cross-module edges are precise, not regex-guessed.
Use when:
- User asks "what calls this function" / "what does this function call"
- Tracing a bug through layers (impact → caller chain)
- Planning refactor of a function/class (need full fanout)
- "Where is this symbol defined" / "find all references to X"
- "Show me the path from handler → DB"
- "Draw a UML class/package/component/sequence diagram"
Replaces: grep + read + manual chain-following (~10-30k tokens) with
2-4 MCP calls (~1-3k tokens).
|
| allowed-tools | ["mcp__tree-sitter-analyzer__nav","mcp__tree-sitter-analyzer__search","mcp__tree-sitter-analyzer__structure","mcp__tree-sitter-analyzer__health","mcp__tree-sitter-analyzer__viz","Bash","Read"] |
tsa-graph — Code archaeology, one call deep
This skill exposes the graph-focused tools that answer "who is connected to
what" — the questions agents waste the most tokens on when they fall back to
grep.
When to use
Pick the right tool by question shape:
| Question | Tool |
|---|
| Need search + snippets + callers/callees together? | search action=chain |
| What does FUNCTION call? | nav action=callees |
| What calls FUNCTION? | nav action=callers |
| Where is SYMBOL defined? | search action=symbol |
| What references SYMBOL anywhere? | nav action=xref |
| Path from CALLER to CALLEE? | nav action=call_path |
| Resolve "Path" in file X (project or stdlib?) | nav action=resolve |
| Need architecture diagram output? | viz action=uml |
Don't use when:
- You need the actual body of the function → use
structure action=read
- You're hunting a string literal in non-source files → use Grep
Procedure
Single-question case (90% of uses)
Pick the matching tool, call once. Read the response. Done.
Example: "what calls score_file?"
nav action=callers function_name="score_file" language="python" limit=20
Returns: callers: [{name, file, line, callee_resolution, callee_resolved_file}, ...].
The callee_resolution field tells you local / project / stdlib /
unknown so you can filter out noise.
When a question needs several graph hops plus source snippets, prefer the
chain surface:
search action=chain query="search('score_file').explore(max_files=3).callers(depth=1).callees(depth=1)"
Multi-step case (refactor planning)
Fan out 3 in parallel:
nav action=callers (who depends on this — blast radius)nav action=callees (what this depends on — what may need updating)search action=symbol with the symbol name (find aliases / shadows)
Then if you need a specific reachability path:
nav action=call_path from_function="X" to_function="Y" max_depth=10
Reading the new resolution fields (Synapse)
Each callee entry now carries:
name: "Path"
file: ".../health_scorer.py"
line: 366
callee_resolution: stdlib | local | project | third_party | dynamic | unknown
callee_resolved_file: "" | "<file the callee lives in>"
callee_symbol_id: null | <int FK to ast_symbol_rows>
Filter rules of thumb:
resolution=stdlib → ignore for change-impact (won't be in this repo)resolution=local|project with non-null callee_symbol_id → trustworthy edgeresolution=unknown → may need re-index: uv run tree-sitter-analyzer --ast-cache --ast-cache-mode index --ast-cache-force
CLI equivalents
uv run tree-sitter-analyzer --callees <FUNC> --output-format toon
uv run tree-sitter-analyzer --callers <FUNC> --output-format toon
uv run tree-sitter-analyzer --symbol-search <NAME> --output-format toon
uv run tree-sitter-analyzer --codegraph-xref <SYMBOL> --output-format toon
uv run tree-sitter-analyzer --call-path --call-path-source X --call-path-target Y
uv run tree-sitter-analyzer --uml class --output-format toon
Anti-patterns
- Don't
grep -rn "def X" tree_sitter_analyzer/ — use search action=symbol (10x faster, precise)
- Don't read 5 files to trace a call chain — use
nav action=call_path
- Don't ignore
callee_resolution — unknown entries are noise, filter them
Decision surface
function: <queried name>
callee_count | caller_count: <int>
callees | callers: [
{name, file, line, language, callee_resolution, callee_resolved_file}
]
verdict: INFO
