pi-hashline-readmap AGENTS.md

AGENTS.md — Developer & Agent Guide

Repo-local guide for working on pi-hashline-readmap.

What This Project Is

pi-hashline-readmap is a unified pi extension that replaces several built-in tools with enhanced versions:

• read — hashlined reads, structural maps, symbol-addressable reads
• edit — hash-anchored edits with semantic diff summaries
• grep — hashlined search results
• ast_search — ast-grep wrapper with hashlined output
• bash filtering — command-aware output compression

The extension is loaded via an absolute path entry in ~/.pi/agent/settings.json's extensions array (pointing at this workspace's index.ts), so new agent sessions pick up local edits automatically. Running sessions do not hot-reload the module graph — restart any in-flight agent session to see changes take effect.

Version Control

This repo is currently operated as a normal git repo with GitHub PRs. Do not assume jj is configured here.

Standard flow:

git checkout main
git pull --ff-only origin main
git checkout -b feat/my-feature
# edit / test
git add -A
git commit -m "feat: my feature description"
git push -u origin feat/my-feature
gh pr create --base main --head feat/my-feature

After merge:

git checkout main
git pull --ff-only origin main
git branch -d feat/my-feature

Use git branch -D only after verifying the work is on origin/main.

Megapowers-managed work

When /mega on is active, do not run ad-hoc branch/commit/push commands outside the allowed workflow moments. Use megapowers tools for phase changes and TDD signals. Post-merge cleanup on local main is the main exception.

Development

Prereqs:

node --version   # >= 22.19.0
npm install

Useful optional tools:

brew install ast-grep
brew install difftastic
brew install shellcheck yq scc

Validation:

npm test
npm run typecheck

Source map

• index.ts — extension entry point
• src/read.ts, src/edit.ts, src/grep.ts, src/sg.ts, src/nu.ts — core tool implementations
• src/*-output.ts, src/*-render-helpers.ts — tool result shaping / rendering
• src/readmap/ — structural mapping, symbol lookup, language detection, per-language mappers
• src/rtk/ — bash output routing and compression techniques
• prompts/ — tool prompt/schema docs
• scripts/ — helper scripts used by readmap internals
• tests/ — feature-focused tests and fixtures