pi-stash

A per-session stash of reusable prompt fragments for the Pi coding agent.

Jot a prompt down whenever you think of it mid-task, then pop it into the editor when you actually need it. Think of it as a stack-like scratchpad for prompts — the ad-hoc, mutable companion to static prompt templates.

Why

You're deep in a task and a thought hits you: "oh, I should also have it rename that module" or "remember to ask for tests after this."

What do you do with that thought right now?

• Queue it as a follow-up? Too eager — follow-ups fire automatically the moment the current turn ends, whether or not you're ready, and in an order you don't fully control.
• Keep it in your head? You'll forget it the second the agent comes back with something interesting.
• Paste it into a scratch file? Now you're juggling another window.

Sometimes you just want to park a prompt somewhere and then pull it out whenever you feel like it — on your own timing, by hand. Not auto-run, not queued the instant the turn ends, just stashed and waiting until you decide it's time.

That's the whole point of pi-stash:

• Push the thought the moment it strikes, so you don't lose it or break flow.
• Pop it back into the editor at exactly the moment you want it — not a second sooner.
• Pick any one, in any order. Your stash is a menu, not a queue. Pop the third thing first, skip the rest, come back for them later — follow-ups can't do that.

You stay in control of what gets said, when, and in what order.

Install

pi install npm:@yusukeshib/pi-stash

Commands

| Command | Action | |---------|--------| | /stash <text> | Push — save the given text onto the stash. | | /stash | Pop — pick a saved entry, insert it into the editor, and remove it from the stash. Run repeatedly to stack several fragments together. | | /stash-clear | Delete every stashed entry in this session (with confirm). |

Shortcut

| Key | Action | |-----|--------| | Alt+S | If the editor has text, push it onto the stash and clear the editor. If the editor is empty, pop a saved entry into it. |

Alt+S is the one-key way to do what /stash does: park the prompt you're halfway through typing, or pull one back — without typing the command. Rebind it in ~/.pi/agent/keybindings.json if it clashes with another shortcut.

While the stash is non-empty, a red stash:N badge is shown in the footer so you never forget you have prompts parked.

How it works

pi-stash is not a set of predefined /name templates. It is a backlog you build up by hand during real work:

1. While working, you think "I should also ask it to update the docs" — instead of derailing now, run /stash update the docs and changelog.
2. Later, when you're ready, run /stash, pick that entry, and it drops into the editor. The entry is popped (removed) so the stash stays current.
3. Pop multiple entries in a row to compose a larger prompt from fragments.

Storage

Each change (push, pop, or clear) is recorded as a custom session entry and written immediately to an atomic per-session backup at <session-dir>/pi-stash/<session-id>.json. The backup contains the prompt text; protect your session directory accordingly. On restart, the stash is restored for that same session (pi --continue, pi --resume, or /resume). A plain pi starts a new, empty session. Branching (/tree, /fork, /clone) uses the stash state on the selected branch or fork point, not another branch's backup. The stash does not participate in the LLM context.

Pi does not write a new session file until the first assistant response. Before then, the backup is written, but pi --continue/--resume cannot find that unsaved session after Pi exits. If you used an explicit --session-id, restarting with the same ID can recover the backup; otherwise use an existing saved session if you need ordinary resume. --no-session is likewise not resumable. Backups are scoped to session IDs; they are not shared between sessions. Removing a session file does not automatically remove its backup; delete the matching <session-id>.json if you no longer want it stored.

License

MIT © yusukeshib