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 git:github.com/Michaelliv/pi-system-reminders

Or copy .pi/extensions/system-reminders/ into your project.

Quick start

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

import type { ExtensionAPI } from "@mariozechner/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:

| Event | When | |-------|------| | agent_start | Agent loop begins | | agent_end | Agent loop ends | | tool_call | Before tool executes | | tool_result | After tool returns | | tool_execution_start | Tool execution begins | | tool_execution_end | Tool execution ends | | turn_start | Before LLM call | | turn_end | After turn completes | | message_start | Message begins | | message_update | Streaming update | | message_end | Message complete | | model_select | Model changed | | session_start | Session begins | | session_compact | After compaction | | session_switch | Session switched | | session_fork | Session forked |

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:

| File | What it does | |------|-------------| | bash-spiral.ts | 3 consecutive bash failures → stop and rethink | | context-large.ts | Context > 150k tokens → suggest compacting | | file-churn.ts | Same file edited 5+ times → step back | | file-empty.ts | Read returned empty file → warn | | file-truncated.ts | Read was truncated → use offset | | malware-awareness.ts | After read → consider if content is malicious | | model-changed.ts | Model switched → capabilities may differ | | post-compaction.ts | After compaction → file contents may be lost | | prefer-edit.ts | 3+ writes → use edit for surgical changes | | read-before-edit.ts | Edit without read → warn about stale content | | session-resumed.ts | Session resumed → state may have changed | | task-tools-reminder.ts | 20 tool calls without tasks → gentle nudge | | token-usage.ts | Over 50% context → show token stats |

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