Pi Read Map
Extension
Adds bounded structural maps to large read results, with language-specific symbol extraction, fallbacks, caching, and line ranges for targeted follow-up reads.
What it does
Pi Read Map replaces Pi's read tool with a compatible wrapper that adds structural outlines when a file exceeds normal read limits.
The outline reports symbols and line ranges so later reads can target relevant sections instead of scanning a large file sequentially.
When to reach for it
Invocation: Use the normal read tool on a large source or data file; no separate command is required.
- A file is too long or large for one ordinary read result
- Read it once to receive the initial content plus a structural map.
- You need to locate symbols before spending context on implementation details
- Use map line ranges for narrow offset and limit reads.
- A language-specific parser cannot handle the file
- Allow the extension to fall back through ctags and text-based extraction.
What it adds
- Language-aware structural mappers for common programming, markup, and data formats.
- An in-memory cache keyed by file path and modification time.
- Progressive detail reduction and symbol truncation that bound map size.
How it fits
No related catalog surfaces are recorded.
Common questions
- When does map generation run?
- It runs for untargeted regular text-file reads above 2,000 lines or 50 KiB. Targeted reads, recognized binary files, smaller files, and ordinary read errors stay with Pi's built-in tool.
- What does the map cost?
- The map adds context up front. Formatting progressively removes detail and ultimately limits the symbol selection when a complete outline would exceed its budget.
It’s working if
- A large supported file returns its ordinary first chunk followed by a map in the same tool result.
- A targeted read using a map line range returns only the requested section without regenerating the map.
Source and setup
Provenance
- Project
- Pi Read Map
- Origin
- Kevin
- Current maintainer
- Will Hampson
- Relationship
- adopted
- Installed source
git:github.com/Whamp/pi-read-map- Source path
- View source (
src/index.ts) - Upstream
- https://github.com/kcosr/codemap
- Compatibility
- Pi package APIs
- Node.js
- Bundled parsers with optional system-tool fallbacks
- License
- MIT
- License publication scope
- Upstream-derived portions require Kevin's MIT notice; public catalog prose remains independently written and attributes Codemap as the foundation.
- Reviewed revision
97b6a73305000845d22646f62c72fbf6121e16f3- Catalog revision
e0c035a297462c519315abfa1af31a1ed3bd9eef
Setup notes
- Adopted and maintained by Will Hampson from Kevin's MIT-licensed Codemap foundation, with a Clojure mapper contribution credited to Baishampayan Ghose.
- The C++ and Rust mappers identify themselves as ports from Codemap. Preserve Kevin's upstream MIT notice alongside Will Hampson's project MIT notice for reused portions.
- Specialized parsers are bundled for several languages; Python, Go, JSON, and ctags paths may depend on corresponding system tools.
- The repository's summary-judge skill is development evaluation material and is not declared as an installed package skill.
- Behavior claims were reviewed against the installed Git commit rather than a moving branch.