tsa-graph

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:

1. nav action=callers (who depends on this — blast radius)
2. nav action=callees (what this depends on — what may need updating)
3. 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 edge
• resolution=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   # graph queries are observational, not actionable