Stash

claude-stash

A lightweight stash for Claude Code. Capture ideas mid-task without losing focus, then pop them back when you're ready. Single-session, no context loss.

You're deep in a refactor, an idea pops up, you /stash:push it, you keep working. When you're done, /stash:pop continues with the next thing — same Claude session, no context loss.

Distributed as a Claude Code plugin — one-line install, automatic updates, works in every project.

Install

In Claude Code:

/plugin marketplace add AmirSoleimani/claude-stash
/plugin install stash@claude-stash

That's it. The commands and Stop hook are available immediately in every project. Updates come via /plugin update.

Local development

To hack on the plugin without pushing to GitHub:

git clone https://github.com/AmirSoleimani/claude-stash.git
claude --plugin-dir ./claude-stash

Use /reload-plugins after edits to pick up changes.

Commands

Command	What it does
/stash:push <text>	Push an idea onto the stash (does not start work on it)
/stash:list	Show all stashed items, numbered
/stash:show N	Print item N alone (for reading or copying)
/stash:edit N <new text>	Replace text of item N inline (preserves original timestamp)
/stash:edit N	Open .claude/stash.md in $EDITOR for free-form editing
/stash:pop or /stash:pop N	Pop an item and continue working on it in the current session
/stash:drop N	Remove item N without doing it
/stash:log	Show history of popped and dropped items

Plus a Stop hook that reminds you of pending items every time Claude finishes a turn — passively, never auto-popping.

Philosophy

• Single session by default. /stash:pop keeps your current context. For a fresh context, run /clear first.
• Plain markdown files as the source of truth. Order in the stash = priority. Edit with your editor anytime.
• Two files, two concerns. .claude/stash.md is the queue (transient). .claude/stash.log.md is the history (permanent). Popped and dropped items leave the queue and appear in the log.
• Numbers are display-only. They shift after every operation. Don't store them.
• The hook nudges, never decides. You always explicitly /stash:pop when ready.

Usage walk-through

You're mid-refactor, an idea pops up:

> /stash:push switch the auth middleware to the new guardian proxy
Pushed to stash (1 items total).

A few more:

> /stash:push add rate-limit headers to /v1/deploy
> /stash:push investigate why berth_logs truncates on long runs

You finish the refactor. The Stop hook fires:

📦 Stash: 3 items waiting. Top → switch the auth middleware to the new guardian proxy
   /stash:pop to continue, /stash:pop N to skip ahead, /stash:list to review.

Glance at the list:

> /stash:list
Stash (3 items):
1. switch the auth middleware to the new guardian proxy
2. add rate-limit headers to /v1/deploy
3. investigate why berth_logs truncates on long runs

Realize item 2 has a typo — read the current text:

> /stash:show 2
Item 2 (captured 2026-05-14 09:34):

add rate-limit headers to /v1/deploy

Fix it inline:

> /stash:edit 2 add rate-limit headers to /v1/deploy and /v1/destroy
Edited item 2.

Or for free-form editing of any item, open in your editor:

> /stash:edit 3
[opens .claude/stash.md in $EDITOR with cursor on item 3]

berth_logs feels more urgent — pop it directly:

> /stash:pop 3
Popped from stash: investigate why berth_logs truncates on long runs
[Claude starts working on it in the same session]

Decided an item is no longer relevant:

> /stash:drop 1
Dropped: switch the auth middleware to the new guardian proxy
(1 items remaining)

Review history later:

> /stash:log
Stash log (2 entries):
- [2026-05-14 15:30] POPPED  investigate why berth_logs truncates on long runs
- [2026-05-14 15:35] DROPPED switch the auth middleware to the new guardian proxy

For reordering, edit the file directly:

$EDITOR .claude/stash.md

File format

.claude/stash.md — the queue. Top of file = position 1.

# Stash

- [2026-05-14 09:12] switch the auth middleware to the new guardian proxy
- [2026-05-14 09:34] add rate-limit headers to /v1/deploy
- [2026-05-13 18:02] investigate why berth_logs truncates on long runs

.claude/stash.log.md — the history. Appended to on every pop and drop.

# Stash log

- [2026-05-14 09:45] POPPED  fix the deploy webhook
- [2026-05-14 11:12] DROPPED rename the YAML rubric format
- [2026-05-14 15:30] POPPED  investigate why berth_logs truncates on long runs

Both are human-editable. Grep, sed, vim — all fair game.

Editing flow tips

Three ways to fix or refine an item, pick what fits:

• Type-it-out: /stash:edit N <full new text> — fastest if you know the full new text.
• Read first, then edit: /stash:show N to see the current text (select-and-copy from your terminal), modify it, then /stash:edit N <modified text>.
• Free-form: /stash:edit N (no arguments) opens the whole stash file in $EDITOR for any kind of change — a single character, multiple lines, reordering, whatever.

How the Stop hook works

The hook fires when Claude finishes a turn and prints a one-line reminder if items are waiting. It does not auto-pop or auto-continue. You always type /stash:pop yourself.

The hook is shipped inside the plugin but reads .claude/stash.md from your project (via $CLAUDE_PROJECT_DIR), so each project has its own stash.

If the reminder feels noisy, you can disable just the hook in /plugin settings while keeping the commands.

How the commands work

Each command is a markdown file under commands/. The plugin name (stash) becomes the namespace, so commands/push.md → /stash:push. The body is a prompt that tells Claude what to do — no code. Claude itself reads and writes the stash file when you invoke a command.

This means:

• Zero runtime dependencies (just bash for the hook).
• Commands are auditable and editable in plain English.
• If a command misbehaves, you tweak the prompt.

Trade-off: command reliability depends on Claude following the instructions. In practice this is fine for simple file ops, but you can tighten the language in any command if you see edge cases.

Why "stash" and not "inbox" or "todo"?

push and pop are the right verbs — concrete, familiar to engineers, more natural than add/take. "Stash" is the noun that fits those verbs. It evokes the right feeling: set something aside, come back to it later.

A note on the obvious comparison: this isn't really like git stash. Git stash saves work-in-progress code; this saves future work as descriptions, while you keep doing your current task. Different mechanic, similar vibe. The shared spirit is "set aside, come back to" — that's where the name comes from, not from any deeper mechanical analogy.

This also isn't a todo list (too formal, implies prioritized refined tasks) or an inbox (too email-y, too corporate). It's a scratch space for "I had a thought mid-flow, deal with it after."

Gotchas

• /stash:pop cannot clear context mid-turn. Use /clear then /stash:pop for a fresh session.
• .claude/stash.md and .claude/stash.log.md are project-local. I recommend committing them to git — your stash is project state.
• First time you install, Claude Code shows a trust dialog for the plugin. Approve it.
• This plugin does NOT interact with git stash in any way. The name is just a metaphor.

Contributing

Issues and PRs welcome. Ideas not built yet:

• Voice capture integration (transcribe → /stash:push)
• /stash:undo to restore the last popped/dropped item
• Smarter Stop hook (cooldown, only fire on logical task end)
• Cross-worktree visibility

License

MIT