---
title: "@henryqw/pi-notes"
seo:
  description: "Persistent notes in a Pi widget, managed with /note commands."
---

<div class="not-prose my-6 flex flex-wrap items-center gap-3"><span class="text-sm text-muted-foreground">v0.2.4</span><a href="https://www.npmjs.com/package/@henryqw/pi-notes" aria-label="View @henryqw/pi-notes on npm"><img alt="Monthly npm downloads" height="20" src="https://img.shields.io/npm/dm/%40henryqw%2Fpi-notes?cacheSeconds=7200&amp;color=1d4ed8&amp;label=downloads&amp;labelColor=101828&amp;style=flat-square" width="144"></a></div>

Keep persistent post-it reminders in a Pi widget. Manage them with slash commands.

![Pi showing two persistent notes above the editor](https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-notes/example.png)

## Why

- **Created for**: Keep a few brief post-it-style reminders visible per worktree without leaving the Pi session.
- **Advantage**: Notes stay intentionally bounded and visible instead of becoming clipboard storage or history.

## Install

```bash
pi install npm:@henryqw/pi-notes
```

## Use

| Surface | Type | Purpose |
| --- | --- | --- |
| `/note <text>` | command | Add a note for current Git worktree (max 4). |
| `/note-rm` | command | Pick a note from current worktree to remove. |
| `/note-clear` | command | Clear current worktree's notes. |

- Each Git worktree has separate notes.
- The widget numbers notes above the editor and shows at most two lines per note.
- Each worktree has at most four notes.
- Empty worktrees show no widget.
- Stale files for removed repositories and worktrees are deleted silently when a session starts or notes change.

Each worktree file is validated as untrusted data. Malformed files are preserved. They block mutation for the affected worktree until fixed or reset with `/note-clear`.

## State

The extension generates `~/.pi/agent/config/pi-notes/<worktree-sha256>.json` for command-managed notes in one Git worktree.