@sagmans/pi-history

Ghost completion for prompt history in pi's TUI

Packages

Package details

extension

Install @sagmans/pi-history from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@sagmans/pi-history
Package
@sagmans/pi-history
Version
0.1.6
Published
Aug 13, 2026
Downloads
449/mo · 32/wk
Author
assagman
License
MIT
Types
extension
Size
108.2 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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.84.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

License

MIT · Security · Report bugs · Releases