pi-hashline-readmap

pi-hashline-readmap

Upgrade Pi's local coding workflow with hash-anchored reads and edits, structural navigation, safer file exploration, and quieter command output.

pi-hashline-readmap replaces Pi's read, edit, grep, write, ls, and find; adds enhanced ast_search; retains deprecated optional nu; and post-processes bash.

Bundled nu is deprecated but retained. It stays available for at least one published deprecation release; removal requires a separately announced breaking release after migration-example verification and the removal checklist pass. See Nu deprecation and migration.

Install

pi install npm:pi-hashline-readmap

Requires Pi extension support and Node.js 22.19 or newer. Start a new Pi session after installing; sessions do not hot-reload extensions.

Validated compatibility baseline

Development, schema validation, and extension-load testing use the exact Pi version resolved by package-lock.json, currently Pi 0.84.2, with TypeBox 1.3.7. Pi provides @earendil-works/pi-coding-agent, @earendil-works/pi-tui, and typebox to loaded extensions, so those host-bundled packages intentionally retain "*" peer ranges; the development dependencies and lockfile record the versions validated by this repository.

Run the compatibility coverage through the normal test suite or by itself:

npm test
npm test -- tests/pi-extension-load-compatibility.test.ts tests/pi-host-null-pipeline.test.ts
npm run typecheck

The suite exercises the real locked-host tool pipeline as well as extension loading. Compatibility CI independently provisions exactly Pi 1.2.0. Through that host's loader, wrapper, agent-core pipeline, and ExtensionRunner, it checks required-null rejection, structuredContent passthrough, and real codemode scripts. An npm 11/12 matrix verifies both array and keyed-object npm pack --json output. This runtime lane does not replace the locked development baseline or typecheck; see AGENTS.md to reproduce it.

The extension and the exact Pi host version resolved by package-lock.json share one Node.js engine baseline, currently Node.js 22.19 or newer. The loader compatibility test verifies that this package's engines.node declaration stays identical to the installed locked Pi host package's declaration.

To advance the compatibility baseline, update the Pi development dependency ranges in package.json and refresh package-lock.json with npm install, reviewing both changes together. Then run the focused compatibility test, the full npm test suite, and npm run typecheck before committing the update. Do not narrow the Pi-hosted wildcard peer ranges to encode the baseline.

# alternatives
pi install git:github.com/coctostan/pi-hashline-readmap

git clone https://github.com/coctostan/pi-hashline-readmap.git
cd pi-hashline-readmap
npm install
pi install .

30-second read/edit

Create a disposable file, read it, and copy the returned LINE:HASH anchor:

write({ path: "hashline-demo.txt", content: "hello, hashline!\n" })
read({ path: "hashline-demo.txt" })
1:f0c|hello, hashline!

Edit against that verified content:

edit({
  path: "hashline-demo.txt",
  edits: [{ set_line: { anchor: "1:f0c", new_text: "hello, anchored edits!" } }]
})

If the file changed between read and edit, the edit reports a mismatch instead of touching the wrong line. Delete hashline-demo.txt when finished.

Why use it?

• Tie edits to content-derived anchors rather than fragile line numbers.
• Jump to symbols, request maps, and include direct same-file support.
• Turn grep and ast_search results into edit-ready anchors.
• Read supported images through Pi attachments.
• Create with write; explore with ls and find, then compose structured results in codemode.
• Compress noisy test, build, Git, Docker, linter, package-manager, and generic command output while retaining recovery paths.
• Use one coordinated extension instead of stacking overlapping read, grep, edit, and Bash-output packages.

Common workflows

Edit safely

Get fresh anchors from read, grep, ast_search, or write, then use set_line, replace_lines, or insert_after. Copy or move existing lines, within a file or from another file, with copy_lines and move_lines instead of retyping them. replace is an exact-text escape hatch. Deletion, overlap rejection, whole-symbol replacement, syntax checks, atomic writes, and structured diffs live in tool behavior and structured output. Anchor-looking text in new_text is kept unless it is a real pasted anchor row (literal: true keeps everything), and anchors made stale by your own line-shifting edit are remapped or refused, never applied to a different line.

Navigate large files

read({ path: "src/hashline.ts", map: true })
read({ path: "src/read.ts", symbol: "registerReadTool", limit: 80 })
read({ path: "tests/fixtures/small.ts", symbol: "createDemoDirectory", map: true })
read({ path: "tests/fixtures/small.ts", symbol: "createDemoDirectory", limit: 2, bundle: "local", map: true })

A symbol can combine with limit, map: true, and bundle: "local". symbol+offset is invalid, and bundle without symbol is invalid. Truncated full-file reads append a map when available. Dedicated mapper/runtime details are in configuration and dependencies.

Minified or generated files can contain a single very long line that read clips at 500 characters. Recover any part of it with a character window — the anchor stays the full line's anchor, so it still works with edit:

read({ path: "dist/app.min.js", offset: 1, charOffset: 500 })
read({ path: "data.json", offset: 1, charOffset: 0, charLimit: 5000 })

charLimit defaults to 500 and is capped at 10,000; each result tells you the remaining characters and the next call to make.

Search and explore

grep({ pattern: "createDemoDirectory", path: "tests", literal: true })
grep({ pattern: "createDemoDirectory", path: "tests", summary: true })
grep({ pattern: "createDemoDirectory", path: "tests", scope: "symbol", scopeContext: 3 })
ast_search({ pattern: "console.log($$$ARGS)", lang: "typescript", path: "src", limit: 100 })
write({ path: "src/new-module.ts", content: "export const demo = 1;\n" })
ls({ path: "src", glob: "*.ts" })
find({ pattern: "*.test.ts", path: "tests", maxDepth: 2 })

Normal grep output has anchors; summary mode has counts only. ls lists one directory; find recurses by basename and respects .gitignore. Deprecated nu still registers when Nushell is available; prefer tested source, discovery, and CLI composition recipes for general exploration.

ast_search patterns may start with - (--$A, -$A). A pattern ast-grep cannot parse returns Pattern failed to parse: … instead of "No matches found", and empty patterns are rejected up front.

write returns anchors for up to 2000 lines or 50 KB. Larger writes return a one-line summary (path, line count, bytes), so read with offset/limit before editing. Binary-looking content is written with a warning and no anchors.

Bash output

PI_RTK_BYPASS=1 skips route compression, but the default-on context guard can still trim oversized output. See Bash compression and recovery for routes, limits, snapshots, bypass behavior, and metadata.

Configuration

Most users need none. Global settings live at ~/.pi/agent/hashline-readmap/settings.json; project settings at .pi/hashline-readmap/settings.json; environment variables win. See configuration and local dependencies.

Structured output and integrations

Results retain readable text and additive details.ptcValue records. See structured output and codemode and integration surfaces.

Enable Pi 1.1 codemode additively with pi --tools +codemode or "defaultTools": ["+codemode"], preserving your existing selection. Scripts receive Hashline structured values, including fresh LINE:HASH anchors and raw grep records. See tested codemode recipes for compact projections, failure handling, image variants, search/edit chains, and small cross-call state; codemode integration defines the result contracts. Codemode-only exposure remains opt-in and does not bypass permission guards.

Required JSON null arguments are rejected before Pi can coerce them into strings or other scalars; optional nulls behave like omission, and the literal string "null" remains valid. Pi's preparation errors preserve the message and isError, but not custom structured error metadata. See host-boundary null contracts.

Context hygiene

Hashline tracks file, symbol, and command resources, signals staleness forward-only, and keeps hard anchor checks at edit time. See context-hygiene metadata.

Provider-visible metadata

Compact descriptions, parameter descriptions, snippets, and guidelines are provider-visible; full prompt bodies are detailed references. See the constraint inventory and measured diagnosis.

Documentation

Advanced behavior and integration contracts are documented in the references below.

• Bash output and recovery
• Configuration and dependencies
• Context hygiene
• Integration surfaces
• Structured output and tool behavior
• Codemode recipes
• Nu deprecation and migration
• Provider-visible metadata and diagnosis
• Exploratory functional testing
• Benchmarking edits
• Tool prompt references
• Changelog

Development

npm install
npm test
npm run typecheck
npm run build   # optional: bundle dist/index.js for faster Pi startup
npm pack --dry-run

npm run build bundles the extension into dist/index.js; Pi loads it when present and falls back to index.ts otherwise (see AGENTS.md and startup performance).

Project layout:

index.ts                  # extension entry point
src/
  read.ts                 # hashlined reads and maps
  edit.ts                 # anchored edits
  grep.ts                 # anchored text search
  sg.ts                   # ast-grep wrapper
  write.ts                # complete writes
  ls.ts / find.ts         # file exploration
  nu.ts                   # deprecated specialist shell
  readmap/                # structural mapping and symbol lookup
  rtk/                    # Bash output compression
prompts/                  # detailed tool references
docs/                     # advanced user and integration references
tests/                    # Vitest suite

Restart Pi after source changes. See AGENTS.md.

Contributing

PRs are welcome. Update focused tests, prompt references, public docs, and mapper cache versions when contracts change.

Credits

• pi-hashline-edit — hash-anchored editing
• pi-read-map — structural file maps
• pi-repo-map — repository-map and tree-sitter inspiration
• pi-rtk — Bash output compression

License

MIT. See LICENSE.