Stop wasting tokens on irrelevant code. Extract only the signal, ignore the noise.
Passive by Default — No configuration required! The extension now works out-of-the-box:
- ✅ Always on — No toggle needed, just install and use
- ✅ Lower threshold — Optimizes files over 300 lines (down from 500)
- ✅ Impact integration — Pre-generates skeletons for affected files
- ✅ Context optimization — Auto-optimizes when context is full
- ✅ Intelligent caching — File hashing + LRU eviction
Reading entire files is the most expensive operation for an AI agent in terms of context window management. When working with large source files, loading the entire content into the context window causes:
- Attention Dilution: The "Lost in the Middle" phenomenon, where critical logic is buried under thousands of lines of boilerplate.
- Context Exhaustion: Rapidly consuming the token budget, leaving less room for the agent to reason or generate complex code.
- Increased Latency: Higher token counts increase processing time and API costs.
pi-smart-reader implements Structural Extraction. Instead of a linear read, the agent interacts with the file's Abstract Syntax Tree (AST) to retrieve only the exact fragments needed for the task.
No configuration required! The extension automatically:
- Detects large files (>300 lines) when Pi reads them
- Generates skeletal views transparently in the background
- Caches results for 5 minutes to avoid redundant work
- Optimizes context when usage exceeds 70%
Generates a high-level map of the file. It preserves all class and function signatures while stripping implementation bodies.
- Value: Turn a 2,000-line file into a 50-line map of capabilities.
- Use Case: Identify which methods exist in a service without loading the full file.
Surgically extracts the full body of a specific function, method, or variable.
- Value: Loads only the target logic into the context window.
- Use Case: Extract the full implementation of a specific method once identified via the skeleton.
Automatically identifies internal calls within the extracted symbol. If a function calls another helper in the same file, the tool suggests that related symbol, preventing the agent from having to guess dependencies.
pi-smart-reader works in tandem with pi-impact-analyzer to provide a high-efficiency debugging workflow:
- Analyze:
pi-impact-analyzeridentifies the "blast radius" of a change - Pre-generate:
pi-smart-readerautomatically generates skeletons for affected files - Access: Skeletal views are ready in context for instant access
This integration happens automatically — no configuration needed!
pi install npm:pi-smart-readerJust install and use! The extension automatically:
- Monitors file reads via Pi's
tool_resultevents - Detects large files (>300 lines) in supported languages
- Generates skeletal views transparently
- Caches results for 5 minutes
- Optimizes context when usage is high
No commands needed — it just works!
For explicit control, use the smart_read tool:
{
"tool": "smart_read",
"input": {
"path": "src/services/AuthService.ts",
"options": { "mode": "skeleton" }
}
}Result: A skeletal view showing all class and function signatures.
{
"tool": "smart_read",
"input": {
"path": "src/services/AuthService.ts",
"options": {
"mode": "symbol",
"symbol": "verifyToken"
}
}
}Result: The full implementation of verifyToken with related dependencies.
The extension works with sensible defaults. Use the /smart-reader command to customize:
/smart-reader status # Show current configuration
/smart-reader threshold 300 # Set line threshold
/smart-reader clear # Clear cache
| Metric | Value |
|---|---|
| Skeleton Generation | ~1ms per 1000 lines |
| Symbol Extraction | ~0.5ms per symbol |
| Cache Hit Rate | 95%+ (after warmup) |
| Token Reduction | 70-90% for large files |
- TypeScript (
.ts,.tsx) - JavaScript (
.js,.jsx,.mjs,.cjs) - Python (
.py) - Rust (
.rs) - Go (
.go) - Java (
.java)
For use outside the Pi tool system, import the library directly:
import { SmartParser, SkeletonEngine, SymbolExtractor } from "pi-smart-reader";
// Initialize parser
const parser = new SmartParser();
await parser.initialize();
// Generate skeleton
const skeletonEngine = new SkeletonEngine(parser);
const skeleton = skeletonEngine.generateSkeleton(sourceCode);
// Extract symbol
const symbolExtractor = new SymbolExtractor(parser);
const { content, relatedSymbols } = symbolExtractor.extractSymbol(
sourceCode,
"myFunction"
);┌─────────────────────────────────────────────────────────────┐
│ Pi Session │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. User Reads Large File │
│ └─ smart-reader generates skeleton (if >300 lines) │
│ │
│ 2. User Mentions Code Change │
│ └─ impact-analyzer analyzes impact │
│ │
│ 3. Impact Analysis Complete │
│ └─ smart-reader pre-generates skeletons for affected │
│ │
│ 4. Context Getting Full │
│ └─ smart-reader auto-optimizes large files │
│ │
└─────────────────────────────────────────────────────────────┘
-
Engine: Powered by
tree-sitter(WASM) for high-performance, language-aware parsing -
Complexity: Parsing occurs in
$O(N)$ time, while context impact is reduced to$O(1)$ relative to the extracted symbol size - Caching: File hashing + LRU eviction for optimal cache management
- Integration: Event-based communication with pi-impact-analyzer
- Languages: TypeScript, JavaScript, Python, Rust, Go, Java
- Platforms: Node.js 18+ (runs as a Pi extension)
- Pi: Built for the Pi coding agent ecosystem
Contributions are welcome. We are seeking support for:
- Additional language bindings (C++, C#, Ruby)
- Improved entropy-based symbol detection
- Enhanced dependency mapping logic
Please follow the standard Pull Request process: Fork, Branch, Commit, and PR.
Distributed under the MIT License. See the LICENSE file for more information.
- Pi — The AI coding agent
- tree-sitter — Parser generator toolkit