@undreren/pi-checkpoint

Context checkpoints and restore_conversation compaction for Pi Coding Agent

Packages

Package details

extension

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

npm repohome report
$ pi install npm:@undreren/pi-checkpoint
Package
@undreren/pi-checkpoint
Version
0.1.3
Published
Jul 22, 2026
Downloads
284/mo · 284/wk
Author
undreren
License
MIT
Types
extension
Size
29.2 KB
Dependencies
0 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

@undreren/pi-checkpoint

Pi package that adds context checkpoints and conversation restore for agents and users.

Install

pi install npm:@undreren/pi-checkpoint

Or from this repo:

node install.mjs

Tools

  • checkpoint — create a conversation-only bookmark, returns #N with compaction guidance
  • restore_conversation — compact context back to a checkpoint with a required summary

Commands (TUI)

  • /checkpoint [label] — create a checkpoint (injects tool call + result)
  • /restore_conversation — picker (current branch, newest first) then summary prompt

Behavior

  • Conversation-only compaction (no filesystem restore)
  • restore_conversation replaces intermediate messages with your summary; it does not mean undo
  • Restore lands on checkpoint → restore_conversation tool_call → restore_conversation tool_result
  • Agent restore_conversation auto-continues; user /restore_conversation waits for your next message
  • Checkpoint ids are global per session (#1, #2, …); accept #3 or 3

Agent semantics

  • Checkpoint creates a conversation bookmark. The filesystem is unchanged.
  • Restore conversation compacts everything after that checkpoint into the summary you provide.
  • The summary is authored by you (or the user via /restore_conversation) and becomes your durable memory.
  • Intermediate tool outputs are removed from context after restore; trust the summary and tool_result.details.
  • Restore success is reported in the session tool_result with isError: false.

Cursor bridge notes

When pi tools are replayed through a Cursor bridge:

  • restore_conversation tool_result must not be duplicated on an error channel.
  • tool_call.arguments.summary should remain visible after compaction.
  • Compacted messages must actually leave agent context.
  • Prefer the session-written restore_conversation tool_result over any minimal hook block reason.

Develop

npm install
npm test

License

MIT