---
slug: "pi-mind-queue"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/sanif/pi-mind-queue@main/README.md"
repo: "https://github.com/sanif/pi-mind-queue"
source_file: "README.md"
branch: "main"
---
# Mind Queue for Pi

![Mind Queue](https://github.com/sanif/pi-mind-queue/raw/HEAD/docs/screenshot.png)

Mind Queue is a project-wide scratchpad for thoughts you do not want to lose while working in [Pi](https://github.com/earendil-works/pi). Thoughts persist across sessions, retain a short creation-session label, and can be moved back into Pi's editor when they become relevant.

**Images and files are supported.** Drop them into the Add screen to save local
`@path` references alongside a thought without copying their contents.

## Install

From npm (latest stable release):

```bash
pi install npm:pi-mind-queue
```

From GitHub (default branch):

```bash
pi install git:github.com/sanif/pi-mind-queue
```

Restart Pi or run `/reload`, then open Mind Queue with `/mind` or `Ctrl+Shift+M`.

If you previously installed a local development copy at `~/.pi/agent/extensions/mind-queue`, remove or rename that directory before installing the package. Loading both copies registers duplicate commands and shortcuts.

## Use

### Available from Pi

| Action | Command |
| --- | --- |
| Toggle Mind Queue | `Ctrl+Shift+M` |
| Open Mind Queue | `/mind` |
| Add while Pi is working | `/mind <thought>` |
| Review stale thoughts | `/mind cleanup` |
| Focus a thought in the status bar | `/mind focus <id>` |
| Clear the focused thought | `/mind focus` |
| Clear completed thoughts | `/mind clear-done` |
| Undo the latest change | `/mind undo` |

### Change the shortcut

Create `~/.pi/agent/extensions/mind-queue.json` and set `shortcut` to any
[Pi key combination](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/keybindings.md):

```json
{
  "shortcut": "ctrl+shift+q"
}
```

Run `/reload` after changing the file. The configured shortcut opens Mind Queue,
closes its overlay, and appears in the overlay hint. `/mind` remains available.

### While Mind Queue is open

These keys are handled only while the Mind Queue overlay is open. They do not
change the normal Pi editor outside the overlay.

| Action | Key |
| --- | --- |
| Add a thought or drop local files/images | `A` |
| Filter thoughts by text | `/` |
| Edit in Pi's multiline editor | `E` |
| Copy the selected thought | `Y` |
| View the complete thought | `V` |
| Move the thought to Pi's editor | `Enter` |
| Mark open or done | `X` or `Space` |
| Focus in the status bar | `F` |
| Clear all completed thoughts | `C` |
| Remove | `D` or `Delete` |
| Undo this session's latest change | `U` |
| Move selection | arrow keys or `J`/`K` |
| Close | `Esc` or the configured shortcut |

`/mind <thought>` saves immediately, including while the agent is working.
It does not interrupt the agent or send the command to the model; it only
updates the local project queue. If the same text is already open, Mind Queue
keeps the existing thought and tells you its ID instead of creating a duplicate.

Each thought row shows its `#id` and age (for example `3d` or `2w`)
right-aligned, so they stay visible even when the text is long. The IDs match
the ones the agent tool and `/mind cleanup` use, and the `V` detail view shows
the thought's ID, open/done status, and full relative time. Press `/` to
filter the list by thought text as you type; `Enter` or `Tab` keeps the
filter, and `Esc` inside the filter clears it. Press `F` or run
`/mind focus <id>` to pin one open thought in Pi's status bar; it stays there
until you clear it with `/mind focus`, or it is completed, moved, or removed.
The status bar refreshes after each agent turn, so a focus set in another Pi
session appears without reloading.
`C` removes every completed thought in one step, and `U` (or `/mind undo`)
restores them.

The status-bar display uses Pi's extension-status API (`ctx.ui.setStatus`). If
you use a custom footer or statusline extension, it must render extension
statuses (for example via `footerData.getExtensionStatuses()`) for the open
count and the focused thought to appear.

In the `A` screen, drag local files or images into the terminal to add them as
absolute `@path` references. Mind Queue does not copy or read the dropped file;
the reference stops working if the original file is moved or deleted.

## Agent collaboration

When explicitly asked, the agent can use the `mind_queue` tool to:

- list open, completed, or all thoughts;
- add a thought;
- mark a thought open or done;
- remove a stale thought after you explicitly confirm its ID.

For example: “Show my Mind Queue,” “Save this in my Mind Queue,” or “Mark
thought #3 done.” The tool never captures ordinary conversation or injects the
queue automatically. Agent tool results may contain thought text, making that
text visible to the current model provider. Agent-driven edit and move-to-editor
actions are intentionally unavailable.

`/mind cleanup` starts an agent review of open thoughts against relevant Git
history and current project features. The agent presents likely completed or
stale thoughts with evidence and asks which IDs to remove. Nothing is removed
until you explicitly confirm the specific IDs.

Moving a thought removes it from the queue and inserts it at the current Pi editor cursor. `U` restores both the queue entry and the inserted editor text when the editor has not changed around that insertion.

Mind Queue detects stale dialogs. If another Pi session changes a thought before you edit, remove, move, or toggle it, the stale action is rejected and the queue refreshes instead of overwriting newer work.

## Storage and privacy

Mind Queue stores one JSON file per project under:

```text
<pi-agent-dir>/state/mind-queue/
```

The directory is mode `0700` and files are mode `0600`. Writes use a process lock, a temporary file, `fsync`, and atomic rename. The repository itself is never modified.

Stored data includes:

- thought text and completion state;
- creation time and session ID;
- a session name or a sanitized first-prompt label capped at 46 characters;
- one undo snapshot for the latest change.

Thoughts may contain sensitive information. Back up or remove the state directory according to your own data-retention needs. Uninstalling the package does not delete saved thoughts.

Older session-local Mind Queue snapshots are imported once when a project store is first created. The migration reads Pi's default session catalog and an active custom session directory, if configured.

## Requirements

- Pi with Node.js `>=22.19.0`.
- Interactive TUI mode for the `/mind` overlay and shortcut.
- macOS with `/usr/bin/lockf`, or Linux with `flock` in `/usr/bin`, `/bin`, or `/usr/local/bin`.

Mind Queue fails safely with an actionable error when no supported kernel lock utility is available. Windows is not currently supported.

Pi extensions run with the same system access as Pi. Review extension source before installation.

## Development

```bash
bun install
bun run verify
```

`verify` runs strict TypeScript checks, the complete test suite, and a package dry run. CI runs the same checks on macOS and Linux.

## License

MIT