# @zle13/pi-prompt-snippets

> Mix-and-match prompt snippets that prepend or append rules to messages in Pi

Latest version **0.2.0** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @zle13/pi-prompt-snippets
pnpm add @zle13/pi-prompt-snippets
yarn add @zle13/pi-prompt-snippets
bun add @zle13/pi-prompt-snippets
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-09-24 |
| First published | 2026-08-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 37.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | zle13 |
| Maintainers | zle13 |
| Keywords | pi-package |

## Links

- npm: https://www.npmjs.com/package/@zle13/pi-prompt-snippets
- Repository: https://github.com/LeZH13/zle-pi
- Homepage: https://github.com/LeZH13/zle-pi#readme
- Issues: https://github.com/LeZH13/zle-pi/issues
- npm.io page: https://npm.io/package/@zle13/pi-prompt-snippets

## Recent versions

- 0.2.0 (latest) — 2026-09-24
- 0.1.0 — 2026-08-30

## README

# @zle13/pi-prompt-snippets

Mix-and-match single-purpose prompt rules that are prepended or appended to your message when you send it in Pi.

Unlike full skills, each snippet is a lightweight, standalone instruction — toggle exactly the ones you want for your next message.

> **Credits:** Originally created by [Amos Blomqvist](https://github.com/amosblomqvist) in [amosblomqvist/pi-config](https://github.com/amosblomqvist/pi-config).

---

## Installation

```bash
pi install npm:@zle13/pi-prompt-snippets
```

Or install locally from source:

```bash
pi install -l ./packages/prompt-snippets
```

Then restart Pi or run `/reload` in your active session.

---

## Usage

- Press **Alt+S** or run **/snippets** to open the interactive toggle menu.
  - `↑` / `↓` (or custom selection keybindings like `Ctrl+P` / `Ctrl+N`) to navigate items.
  - `Space` to toggle snippet active / inactive.
  - `Tab` to preview the highlighted snippet (shows name, placement, order, source origin, filename, and prompt body). Press `Tab` or `Esc` (or `Ctrl+G` / `Ctrl+C`) to return to the list with cursor position preserved.
  - `Enter` to apply your selection.
  - `Esc` to cancel and discard changes.
- **Keybinding Integration:** Respects custom `tui.select.*` actions from `~/.pi/agent/keybindings.json` (such as `tui.select.up`, `tui.select.down`, `tui.select.pageUp`, `tui.select.pageDown`, `tui.select.confirm`, and `tui.select.cancel`).
- **Active Snippet Indicator:** Active snippets appear as a widget above the editor:
  - `↑ prepend: ...` (accent color) — inserted before your message.
  - `↓ append: ...` (warning color) — inserted after your message.
- When you send a message, active snippets are merged in order:
  `[Prepend group (sorted by order)] → [Your message] → [Append group (sorted by order)]`, separated by blank lines.
- **Automatic Reset:** Active toggles reset to all off after every send and at session start.

---

## Audit past prompts and snippet usage

Run `/snippets-audit` (optionally `/snippets-audit this project, last 60 days`) to ask the agent to review recent prompts against your effective snippets and recommend additions or consolidation. This is an extension command, **not a globally discoverable skill**. The command injects the bundled audit instructions into one agent turn; it does not edit your sessions or snippets.

The bundled read-only Python 3 exporter scans local main-session JSONL files (not subagent transcripts). It defaults to 30 days, at most 30 recent sessions, and at most 60 qualifying prompts. Its report gives exact whitespace/case-normalized repeated prompt frequencies across sampled sessions, plus tracked snippet applications. The agent additionally reviews semantic variants and compares with bundled, global, and project snippets. To inspect the report yourself:

```bash
python3 audit/prompts.py --since-days 30 --cwd my-project
python3 audit/prompts.py --since-days 30 --cwd my-project --format jsonl
```

From this version onward, when active snippets transform an input, the extension records their filename IDs and resolved sources as non-context session metadata—**not prompt or snippet bodies**. Each application counts once per snippet per transformed input. The audit can count these records across sessions; past uses before tracking was installed remain unknown. Samples and branched session histories can affect frequencies. A zero count is a reason to review a snippet, not proof it is unnecessary. Treat exported prompts as private and approve any snippet changes explicitly.

---

## Multi-Directory Hierarchy

Snippets are discovered dynamically across three layers (in increasing precedence):

1. **Bundled package snippets:** Default rules shipped with this extension.
2. **Global user snippets:** `~/.pi/agent/snippets/*.md`
3. **Project snippets:** `.pi/snippets/*.md` (in your workspace, honored when the project is trusted).

Files are re-scanned whenever the menu opens or a message is sent, so edits take effect immediately without restarting Pi.

---

## Customizing, Overriding & Disabling Snippets

### 1. Add Your Own Snippets

Create any `.md` file in `~/.pi/agent/snippets/` (for all projects) or `.pi/snippets/` (for the current project):

```markdown
---
name: Concise Output
description: Short, direct answers without unnecessary fluff
placement: prepend
order: 10
---
Keep your response concise. Skip preamble and unnecessary explanation.
```

### 2. Override Existing Snippets

Create a file with the same filename (e.g. `.pi/snippets/ask-questions.md` or `~/.pi/agent/snippets/ask-questions.md`). Higher-precedence layers completely override lower-precedence ones.

### 3. Disable Default Snippets

You can disable default or global snippets in two ways:

#### Option A: Frontmatter `disabled: true`
Create a file with the same filename in `~/.pi/agent/snippets/` or `.pi/snippets/` and set `disabled: true`:

```markdown
---
disabled: true
---
```

#### Option B: Configuration File
Create `.pi/prompt-snippets.json` (project-level) or `~/.pi/agent/prompt-snippets.json` (global):

```json
{
  "disabled": [
    "ask-questions",
    "diagnose-report.md"
  ]
}
```

---

## Snippet Frontmatter Reference

| Field | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | Filename without `.md` | Display name shown in the menu |
| `description` | `string` | `""` | Description subtitle shown in the menu |
| `placement` | `"prepend"` \| `"append"` | `"append"` | Whether the rule is placed before or after your prompt |
| `order` | `number` | `9999` | Sort order within its placement group (lower numbers first) |
| `disabled` | `boolean` | `false` | When `true`, disables/hides this snippet ID from the list |

---

## License

MIT © zle13. Original work © Amos Blomqvist.

---
_Source: https://npm.io/package/@zle13/pi-prompt-snippets · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._