Powder Room

Context-aware snapshot manager for Claude Code.

Because refreshing your context should be as natural as excusing yourself to the powder room.

The Problem

When using Claude Code for long sessions, the context window fills up and compact kicks in — automatically summarizing and compressing your conversation. Each time this happens, working context is lost. Repeat it enough times, and the agent loses track of what it was doing, what was agreed upon, and what comes next.

The Solution

Powder Room takes a different approach: treat your context window as a volatile cache, not as memory.

Instead of fighting compact, you work with it:

1. Save your working context as lightweight JSON snapshots
2. Freshen up — when the session gets large, /clear on your own terms
3. Resume — your context is automatically restored from the latest snapshot

Quick Start

npx powder-room init

That's it. Powder Room will:

• Monitor your session size
• Remind you when it's time to freshen up
• Restore your context after /clear or compact

How It Works

Snapshots

Your AI agent saves its own working context as a JSON snapshot. This isn't mechanical extraction — the agent summarizes what matters:

npx powder-room save '{"goal":"Build auth system","next_action":"Write login tests","agreements":["Use JWT","No session cookies"]}'

The recommended schema has 11 fields, but only next_action or goal is required:

| Field | Purpose | |-------|---------| | goal | Why you're doing this (1 line) | | current_task | What you're working on right now | | working_set | Files, features, resources in play | | agreements | What was decided with the user | | decisions | What was decided and why | | open_questions | Unresolved questions | | constraints | What must not be violated | | last_actions | Recent steps taken (3-10) | | next_action | What to do next (most important) | | mode | Working mode (execution/design/debug) | | emotional_context | User's current situation (1 line) |

Monitoring

A UserPromptSubmit hook monitors your transcript size. At 50MB, you'll see:

[Powder Room] Time to freshen up (52MB). Save your snapshot and /clear.

Restoration

After /clear or compact, a SessionStart hook reads the latest snapshot and injects a summary:

[Powder Room] Welcome back.
Next action: Write login tests
Goal: Build auth system
Agreements: Use JWT / No session cookies

Commands

| Command | Description | |---------|-------------| | npx powder-room init | Install hooks and set up directories | | npx powder-room save '<json>' | Save a context snapshot | | npx powder-room load | Load the most recent snapshot | | npx powder-room list [n] | List recent snapshots | | npx powder-room uninstall | Remove hooks (keeps snapshots) |

Philosophy

See docs/philosophy.md for the ideas behind Powder Room.

Storage

Snapshots are plain JSON files stored in ~/.powder-room/snapshots/. No database, no external dependencies. You can read, edit, or back them up with standard tools.

Older snapshots are automatically pruned (keeps the latest 20).

Uninstall

npx powder-room uninstall

This removes the hooks from Claude Code but keeps your snapshots intact.

Requirements

• Node.js >= 18
• Claude Code

License

MIT