insight
Understand code in one call. Structure, relationships, history - all at once.
When & Why to Use This Skill
Insight is a high-performance Claude skill designed to streamline codebase navigation and technical analysis. It eliminates the need for multiple manual tool calls by providing a unified view of code structure, symbol relationships, and git history in a single request. Beyond comprehension, it includes automated refactoring intelligence to identify technical debt, complexity bottlenecks, and coupling issues, making it an essential utility for developers working on complex or unfamiliar repositories.
Use Cases
- Rapid Codebase Onboarding: Quickly grasp the architecture, entry points, and key symbols of a new project or module without manual file-by-file exploration.
- Impact Analysis & Dependency Mapping: Trace callers, callees, and dependencies for specific symbols to understand the downstream effects of code changes.
- Automated Technical Debt Auditing: Identify high-priority refactoring targets such as long functions, high coupling, and unused code using the built-in analysis engine.
- Enhanced Code Reviews: Generate instant summaries of file changes, complexity metrics, and potential risks to provide more thorough and data-driven feedback.
- Contextual Debugging: Locate relevant code symbols and their recent change history to identify when and why a specific logic path was modified.
| name | insight |
|---|---|
| description | "Understand code in one call. Structure, relationships, history - all at once." |
| allowed-tools | mcp__insight__insight, mcp__insight__suggest_refactoring |
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
| The Problem | Multiple Tools | insight Solution |
|---|---|---|
| Understand a file | list_symbols + get_imports + git_log + ... | One insight call |
| Understand a class | read_symbol + get_callers + find_references + ... | One insight call |
| Understand a module | Read each file + trace dependencies + ... | One insight call |
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
| Option | Default | Description |
|---|---|---|
| includeCode | true | Include source code in output |
| maxChanges | 5 | Max recent git commits to show |
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
| Issue | Detection | Suggestion |
|---|---|---|
| Long functions (>50 lines) | Code analysis | Extract smaller functions |
| Large files (>500 lines) | Metrics | Split into modules |
| High coupling (>15 imports) | Import analysis | Reduce dependencies |
| Unused functions | Call graph | Remove dead code |
| Complex symbols (many callees) | Call analysis | Simplify |
| Poor naming | Pattern matching | Rename suggestions |
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.