pi-system-reminders

Reactive system reminders for pi. Claude Code has them built-in — now pi does too.

Drop a .ts file in a folder, get a reactive reminder that watches conversation state and steers the agent when conditions are met. Same DX as pi extensions — export a default function, get the full ExtensionAPI.

Install

pi install npm:pi-system-reminders

Quick start

Create .pi/reminders/bash-spiral.ts:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  let consecutiveFailures = 0;

  pi.on("tool_result", async (event) => {
    if (event.toolName === "bash") {
      consecutiveFailures = event.isError ? consecutiveFailures + 1 : 0;
    }
  });

  return {
    on: "tool_execution_end",
    when: () => consecutiveFailures >= 3,
    message: "3 consecutive bash failures. Stop and rethink.",
    cooldown: 10,
  };
}

Reload pi. After 3 failed bash calls, the agent sees:

<system-reminder name="bash-spiral">
3 consecutive bash failures. Stop and rethink.
</system-reminder>

How it works

1. Extension discovers .ts files from ~/.pi/agent/reminders/ (global) and .pi/reminders/ (project-local)
2. Each file exports a function receiving ExtensionAPI — same as pi extensions
3. The function returns a reminder: an event to listen on, a predicate, and a message
4. When the predicate returns true, a <system-reminder> steering message is injected into the conversation

Reminder shape

export default function (pi: ExtensionAPI) {
  // Use pi.on() to track state, pi.exec() to run commands, etc.

  return {
    on: "tool_execution_end",           // event(s) to evaluate on
    when: ({ branch, ctx, event }) => boolean,  // fire?
    message: "text" | (rc) => "text",   // what to inject
    cooldown: 5,                        // skip N evaluations after firing
    once: true,                         // fire only once per session
  };
}

Events

16 pi lifecycle events available:

Use a string or array: on: "tool_execution_end" or on: ["turn_start", "turn_end"].

when() context

when: ({ branch, ctx, event }) => {
  branch   // session branch entries
  ctx      // ExtensionContext (sessionManager, getContextUsage(), ui, etc.)
  event    // raw event data from pi
}

Examples

13 ready-to-use reminders in examples/, including ports of Claude Code's built-in system reminders:

Copy any example to .pi/reminders/ to activate it.