symbol-tree
ALWAYS USE FIRST when exploring, searching, or researching this codebase. Use symbol_tree MCP tool before grep/glob/read. Provides instant architecture overview, function relationships, and call graphs without reading full implementations.
When & Why to Use This Skill
The Symbol Tree skill is a high-performance developer utility designed for rapid TypeScript codebase exploration and architectural mapping. It provides an instant overview of file structures, function relationships, and complex call graphs, enabling developers and AI agents to grasp system design without the overhead of reading full implementations. By optimizing context retrieval and reducing token consumption, it serves as an essential first step for codebase research and structural analysis.
Use Cases
- Codebase Onboarding: Quickly visualize the module hierarchy and entry points of a new or complex project to accelerate the learning curve.
- Impact Analysis: Utilize call graphs and type dependency trees to assess how modifying a specific function or interface will ripple through the system.
- Efficient Debugging: Trace function signatures and relationships across multiple files to locate the source of issues without manual grep searches.
- Token-Optimized Development: Provide AI agents with high-level architectural context, allowing them to make informed decisions while staying within context window limits.
| name | symbol-tree |
|---|---|
| description | "ALWAYS USE FIRST when exploring, searching, or researching this codebase. Use symbol_tree MCP tool before grep/glob/read. Provides instant architecture overview, function relationships, and call graphs without reading full implementations." |
| allowed-tools | Bash |
Symbol Tree Analysis
Analyze TypeScript codebases using the symbol-tree CLI This is not optional. The symbol tree tool provides:
- Instant overview of file/module structure
- Function signatures and relationships
- Call graphs showing what calls what
- Type symbols (interfaces, types, enums) with dependency graphs
- All without reading hundreds of lines of implementation
This saves tokens and gives better context faster than file searches.
How to Run
bun run scripts/symbol-tree-mcp/src/cli.ts [path] [options]
Options
| Option | Description |
|---|---|
[path] |
Directory to analyze (default: cwd) |
--file <file> |
Specific file to analyze |
--symbol <name> |
Symbol to search for (e.g., "step", "Runtime") |
--pattern <glob> |
File pattern (default: "**/*.{ts,tsx,js,jsx}") |
--depth <n> |
Limit call graph depth |
--text-limit <n> |
Max output chars (default: 50000) |
--exports-only |
Only show exported symbols |
--no-files |
Hide file paths/line numbers |
--group-by-file |
Group by file instead of symbol type |
--format <fmt> |
"adjacency" (default) or "tree" |
--src-dir <dir> |
Source dir filter (default: "src") |
Examples
# Analyze runtime directory
bun run scripts/symbol-tree-mcp/src/cli.ts src/runtime
# Find a specific symbol
bun run scripts/symbol-tree-mcp/src/cli.ts --symbol step
# Analyze a specific file
bun run scripts/symbol-tree-mcp/src/cli.ts --file src/runtime/state.ts
# Exports only, tree format
bun run scripts/symbol-tree-mcp/src/cli.ts --exports-only --format tree
# Full project overview
bun run scripts/symbol-tree-mcp/src/cli.ts src --exports-only
Correct Workflow
- FIRST: Run symbol-tree to get overview
- THEN: Use the output to identify relevant files/functions
- ONLY THEN: Use Read/Grep/Glob for specific details if needed
Output Format
Each symbol shows location as: (file:startLine-endLine)
Output Sections:
=== CLASSES ===- Class definitions=== INTERFACES ===- Interface definitions=== TYPES ===- Type aliases=== ENUMS ===- Enum definitions=== FUNCTIONS ===- Function signatures=== TYPE DEPENDENCIES ===- Which types extend/use other types=== DEPENDENCIES ===- Function call graphs
Using with Read tool:
offset: UsestartLineto begin reading at the symbollimit: UseendLine - startLine + 1to read only the symbol's code