pi-history

Ghost completion for prompt history across pi sessions.

pi-history records your real prompts. Two isolation levels — project (default: one history per project) and global (one history shared by all projects in the active Pi profile) — configured under <Pi agent directory>/pi-history/ (normally ~/.pi/agent/pi-history/).

Features

• Captures TUI input; skips extension-injected messages and blank prompts; preserves multiline text.
• Caps each project at maxEntries; exact duplicates move to newest instead of storing copies.
• /pi-history status — metadata only. /pi-history clear — confirms, then wipes and records a clear marker.
• Ctrl+R — fuzzy reverse search; Enter replaces the buffer, Escape restores the draft.
• Ghost completion (best effort): dim prefix-match suffix, Ctrl+E accepts all, Alt+Right accepts the next word. Degrades gracefully when editor support is missing.

Install

pi install npm:@sagmans/pi-history

Install from npm so pi only offers updates after a published release.

Existing pi-history installs do not switch npm identities automatically. Migrate once:

pi remove npm:pi-history
pi install npm:@sagmans/pi-history

The package rename does not move or rewrite configuration or prompt history under ~/.pi/agent/pi-history/. Do not install both npm identities at once.

Supported environments

| Component | Supported | | --- | --- | | OS | macOS (primary), Linux. Windows unsupported (POSIX permissions, symlinks). | | Node.js | >=22.19.0 (CI tests 22.19.0 and 24) | | pi | >=0.80.x, tested at 0.85.1 | | Terminal | tested under herdr and standard macOS terminals | | Mode | TUI only. RPC, JSON, and print are inert. |

Configuration

{ "maxEntries": 2000, "isolationLevel": "project" }

User config lives in the active Pi profile's data directory (<Pi agent directory>/pi-history/), not the installed package, so it survives pi update. Precedence (lowest → highest): built-in defaults → shipped config.json → config.json → config.local.json. The highest file that mentions an option wins; an invalid value falls back to the default with a warning.

Profile isolation and upgrade migration

Each PI_CODING_AGENT_DIR profile has separate configuration and history. On the first TUI start after upgrading, pi-history freezes recognized files from the former default location into a versioned migration snapshot. A profile with no existing pi-history/ directory imports that frozen snapshot; any existing target, including an empty directory, wins unchanged. Interrupted owned migration work resumes from private claims without replacing concurrent files.

The snapshot can contain pre-upgrade history previously mixed across profiles, and each import creates another private copy. To stop future imports, remove only ~/.pi/agent/pi-history-profile-migration-v1/snapshot/; retain the bundle and .complete marker so current default-profile data is never snapshotted again. Details: docs/adr/0002-profile-storage-migration.md.

Diagnostics

/pi-history status prints one versioned, privacy-safe line, e.g. pi-history: diagnosticsVersion=2; state=healthy; initialization=ready; storage=ready; editor=ready; entries=12; cap=2000; scope=project. Full field reference: docs/diagnostics.md.

Documentation

• docs/diagnostics.md — /pi-history status field reference
• docs/history-format.md — persisted schema versions, lazy migration, downgrade behavior
• docs/maintainer-development.md — maintainer setup, commands, hooks
• docs/maintainer-smoke.md — disposable Herdr smoke test
• docs/adr/ — architecture decision records
• CONTEXT.md — domain language
• CONTRIBUTING.md — participation policy & bug reports
• SECURITY.md — vulnerability reporting
• RELEASE.md — release policy
• CHANGELOG.md — version history

License

MIT · Security · Report bugs · Releases