smart-explore
π―SkillLets your AI agent explore a codebase by looking at its outline first, such as function and class names, instead of reading whole files. This saves the agent's reading budget. It uses three companion tools to search code, show a file's structure, and open only the part you need.
Installation
npx skills add thedotmack/claude-mem --skill smart-exploreRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/smart-exploreInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/smart-explore/ - All projects
~/.claude/skills/smart-explore/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βToken-optimized structural code search using tree-sitter AST parsing. Use instead of reading full files when you need to understand code structure, find functions, or explore a codebase efficiently.
Smart Explore
Structural code exploration using AST parsing. This skill overrides your default exploration behavior. While this skill is active, use smart_search/smart_outline/smart_unfold as your primary tools instead of Read, Grep, and Glob.
Core principle: Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map.
Your Next Tool Call
This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:
smart_search(query="<topic>", path="./src") -- discover files + symbols across a directory
smart_outline(file_path="<file>") -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>") -- full source of one symbol
Do NOT run Grep, Glob, Read, or find to discover files first. smart_search walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob β Grep β Read discovery cycle.
3-Layer Workflow
Step 1: Search -- Discover Files and Symbols
smart_search(query="shutdown", path="./src", max_results=15)
Returns: Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)
-- Matching Symbols --
function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
method WorkerService.shutdown (services/worker-service.ts:846)
-- Folded File Views --
services/infrastructure/GracefulShutdown.ts (7 symbols)
services/worker-service.ts (12 symbols)
This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.
Parameters:
query(string, required) -- What to search for (function name, concept, class name)path(string) -- Root directory to search (defaults to cwd)max_results(number) -- Max matching symbols, default 20, max 50file_pattern(string, optional) -- Filter to specific files/paths
Step 2: Outline -- Get File Structure
smart_outline(file_path="services/worker-service.ts")
Returns: Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)
Skip this step when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.
Parameters:
file_path(string, required) -- Path to the file
Step 3: Unfold -- See Implementation
Review symbols from Steps 1-2. Pick the ones you need. Unfold only those:
smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")
Returns: Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400-2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size β unlike Read + agent summarization, which may truncate long methods.
Parameters:
file_path(string, required) -- Path to the file (as returned by search/outline)symbol_name(string, required) -- Name of the function/class/method to expand
When to Use Standard Tools Instead
Use these only when smart_* tools are the wrong fit:
- Grep: Exact string/regex search ("find all TODO comments", "where is
ensureWorkerStarteddefined?") - Read: Small files under ~100 lines, non-code files (JSON, markdown, config)
- Glob: File path patterns ("find all test files")
- Explore agent: When you need synthesized understanding across 6+ files, architecture narratives, or answers to open-ended questions like "how does this entire system work end-to-end?" Smart-explore is a scalpel β it answers "where is this?" and "show me that." It doesn't synthesize cross-file data flows, design decisions, or edge cases across an entire feature.
For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.
Workflow Examples
Discover how a feature works (cross-cutting):
1. smart_search(query="shutdown", path="./src")
-> 14 symbols across 7 files, full picture in one call
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
-> See the core implementation
Navigate a large file:
1. smart_outline(file_path="services/worker-service.ts")
-> 1,466 tokens: 12 functions, WorkerService class with 24 members
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
-> 1,610 tokens: the specific method you need
Total: ~3,076 tokens vs ~12,000 to Read the full file
Write documentation about code (hybrid workflow):
1. smart_search(query="feature name", path="./src") -- discover all relevant files and symbols
2. smart_outline on key files -- understand structure
3. smart_unfold on important functions -- get implementation details
4. Read on small config/markdown/plan files -- get non-code context
Use smart_* tools for code exploration, Read for non-code files. Mix freely.
Exploration then precision:
1. smart_search(query="session", path="./src", max_results=10)
-> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
2. Pick the relevant one, unfold it
Token Economics
| Approach | Tokens | Use Case |
|---|---|---|
| smart_outline | ~1,000-2,000 | "What's in this file?" |
| smart_unfold | ~400-2,100 | "Show me this function" |
| smart_search | ~2,000-6,000 | "Find all X across the codebase" |
| search + unfold | ~3,000-8,000 | End-to-end: find and read (the primary workflow) |
| Read (full file) | ~12,000+ | When you truly need everything |
| Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative |
4-8x savings on file understanding (outline + unfold vs Read). 11-18x savings on codebase exploration vs Explore agent. The narrower the query, the wider the gap β a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.
Language Support
Smart-explore uses tree-sitter AST parsing for structural analysis. For file
contents outside its language support, use a text-search tool such as rg.
Bundled Languages
| Language | Extensions |
|---|---|
| JavaScript | .js, .mjs, .cjs |
| TypeScript | .ts |
| TSX / JSX | .tsx, .jsx |
| Python | .py, .pyw |
| Go | .go |
| Rust | .rs |
| Ruby | .rb |
| Java | .java |
| C | .c, .h |
| C++ | .cpp, .cc, .cxx, .hpp, .hh |
| Delphi / Pascal | .pas, .dpr, .dpk, .lpr, .pp |
Files with unrecognized extensions do not produce structured symbols for
smart_outline or smart_unfold. smart_search is not a general file-content
search: its extension filter can exclude unsupported files, and files without
symbols can match only by path. Use rg or another text-search tool to search
their contents.
Additional languages
Custom tree-sitter grammars cannot currently be registered through .claude-mem.json.
Installing a grammar in a project's node_modules does not enable structural
parsing for its extensions. Support must be added to the shipped language map,
grammar packages and symbol queries before smart_outline and smart_unfold
can use it.
Markdown Special Support
Markdown files (.md, .mdx) receive special handling beyond the generic plain-text fallback:
smart_outlineβ extracts headings (#,##,###) as the symbol tree. Use it to navigate long documents without reading the full file.smart_searchβ searches within code fences as well as prose, so queries for function names inside```ts ```blocks work as expected.smart_unfoldβ expands heading sections rather than function bodies; each section up to the next same-level heading is returned as a chunk.- Frontmatter β YAML frontmatter (lines between leading
---delimiters) is included insmart_outlineoutput under a syntheticfrontmattersymbol so metadata liketitle:anddescription:is visible without reading the whole file.
More from this repository10
Claude-Mem gives Claude Code a memory that stays after a session ends. It keeps that memory in a compressed, shorter form.
claude-mem gives Claude Code a memory that lasts between sessions. It records what Claude does while you work, saves short summaries, and shows that context automatically when you start a new session.
Searches your saved Claude-Mem memory on cmem.ai to recall what happened in earlier sessions. It answers questions like what you did last time on a project, file or decision.
Helps your AI agent write a step-by-step plan before building a feature. It first checks the real documentation for what is available, then splits the work into phases. Each phase has a clear goal, examples to copy, checks to prove it works, and mistakes to avoid.
Carries out a step-by-step plan by handing each piece of work to separate helper agents. After each step it checks the result, reviews the code and saves the changes to git only when the checks pass.
Writes a story-style report of a project's whole development history, based on the notes that claude-mem has saved over time. It needs the claude-mem background service to be running.
Automated semantic versioning and release workflow for Claude Code plugins, bumps package.json, marketplace.json, and plugin.json in lockstep, runs the build, tags the commit, creates a GitHub release, and generates changelog entries. Enforces 'nothing left uncommitted or unpushed' by running git status at the end.
Turns the notes claude-mem keeps about your past work into focused knowledge bases you can chat with. You pick notes by project, topic, file, or date, load them into a session, then ask questions about past decisions and fixes.
Reviews a design against Dieter Rams' ten principles of good design, scoring each one with evidence. It then recommends a new design, a refinement or a redesign, and writes a ready-to-use prompt for /make-plan.
Tells your AI to read every source file in your project in full before starting work, so it deeply understands the code. It uses a lot of tokens up front to save effort later.