Insight

insight

One call to understand anything. No more 5+ tool calls to figure out what a file does.

First: insight

insight({ target: 'src/​TaskRunner.ts' })

Returns everything you need:

• Structure (symbols, imports, exports)
• Relationships (callers, callees, dependencies)
• Recent changes (git history)
• Metrics and notes

Why This Wins

What You Get

For a File

• Language and summary
• All symbols with kinds and lines
• Imports and exports
• Who imports this file
• Recent git changes
• Complexity metrics
• Notes (warnings, suggestions)

For a Directory

• Summary of the module
• Files and subdirectories
• Entry points (index files)
• Key exported symbols
• External and internal dependencies
• Recent changes across all files

For a Symbol

• Kind, file, line
• Code (truncated for large symbols >50 lines)
• Function signature
• Methods section for classes (constructors and methods)
• What it calls (filtered - excludes noisy built-ins like push, map, slice)
• What calls it
• Related symbols in same file
• Recent changes

Smart Handling

• Ambiguous names: Shows disambiguation when multiple symbols match
• Better errors: Suggests similar symbols when exact match not found
• Large code: Truncated with line count to prevent context overflow

Examples

Understand a file

insight({ target: 'src/​server.ts' })
insight({ target: 'packages/​syntax/​src/​tools/​listSymbols.ts' })

Understand a directory

insight({ target: 'src/​utils' })
insight({ target: 'packages/​task-runner' })

Understand a symbol

insight({ target: 'TaskRunner' })
insight({ target: 'handleRequest' })

Options

When to Use

• Starting work on unfamiliar code
• Before making changes (understand impact)
• Reviewing what a module does
• Getting oriented in a new codebase

---

suggest_refactoring

Find tech debt and improvement opportunities before you start working.

suggest_refactoring({ target: 'src/​api.ts' })

Returns prioritized suggestions:

• High Priority - Should fix now (long functions, high coupling)
• Medium Priority - Worth addressing (large files, many symbols)
• Low Priority - Nice to have (naming, minor cleanup)

What It Detects

Focus Your Analysis

suggest_refactoring({ target: 'src/', focus: 'coupling' })
suggest_refactoring({ target: 'src/', focus: 'complexity' })
suggest_refactoring({ target: 'src/', focus: 'unused' })

Focus options: all, complexity, coupling, unused, tests, naming

When to Use suggest_refactoring

• Before major changes - understand existing tech debt
• Code review - get automated quality feedback
• Planning refactoring - prioritize what to fix
• Learning a codebase - find the problem areas

Derived, Not Stored

Everything is computed fresh from current code. Never stale.