Install • Ways to use it • How it keeps you safe • FAQ
Delete what your AI coding agents remember about a folder — Claude Code, pi and Hermes — partly or completely, with a preview first and a one-click restore after.
Important
Please read Tiers before your first wipe, and paste the agent instructions into your agent's instructions file. Tiers 4 and 5 can delete files in your project. The pasted text makes your agent explain the tiers the same simple way every time and steer you to the safe one.
- Its transcript, subagents, tool results, file history, background jobs and temporary folder
- Its lines in the shared prompt history, and pasted texts no other prompt uses
- Files it created in your project, but only ones no other session touched
- The sessions that came from it: continuations, background jobs, forks, Hermes delegates and compression chains
- Five tiers, from "transcript only" to "every session in this folder"
- Pick single sessions or a whole folder, with a different tier per session if you like
- An optional handoff note first: where the work lives, the decisions made, the last requests
- Everything goes to the Recycle Bin, which is tested with a small file first. If the bin might not hold it, a quarantine copy is kept too.
- An undo log is written before every step, so even an interrupted wipe can be put back
- Restore moves every file back unchanged, and merges prompt history without losing prompts typed since
- Sessions that are running, or were written in the last 5 minutes
- Anything on your protect list,
.gitfolders, and files outside the agent's own folders - A session can't wipe itself.
/wipequeues the wipe, and it runs after Claude Code closes.
- A window app, an Explorer right-click entry, a
/wipecommand inside Claude Code, and a terminal command - Light or dark theme, following your Windows setting
- An activity log of every wipe, refusal and restore
Windows 10 or 11. Everything installs for your user only; no admin rights needed.
Choose one of the following methods:
One-line installer (recommended)
Open PowerShell and paste:
irm https://raw.githubusercontent.com/astqh/session-wipe/main/install.ps1 | iexIt installs uv if you don't have it, installs Session Wipe, then asks which entry points to add: the Start menu shortcut, the Explorer right-click entry, and Claude Code's /wipe.
To uninstall:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/astqh/session-wipe/main/install.ps1))) -UninstallDownloadable installer
Download Install-SessionWipe.cmd from the latest release and double-click it. It does the same as the one-line installer.
Windows may warn about a downloaded file. You can open it in Notepad first to read it, then choose More info → Run anyway. To uninstall, run it from a terminal with -Uninstall.
Manual install with uv
uv tool install "session-wipe[app] @ https://github.com/astqh/session-wipe/releases/download/v1.0.0/session_wipe-1.0.0-py3-none-any.whl"
wipe-setupOr straight from the source, if you have git: uv tool install "session-wipe[app] @ git+https://github.com/astqh/session-wipe@v1.0.0".
wipe-setup asks which entry points you want. wipe-setup --all adds all of them, and wipe-setup --status shows what's installed. To uninstall: wipe-setup --uninstall --all, then uv tool uninstall session-wipe.
Open Session Wipe from the Start menu (or type wipe-app). It lists every session from all three agents, grouped by folder or by agent, with search and an age filter.
- Tick the sessions to wipe. Sessions marked IN USE can't be ticked; use Wipe after it closes for those.
- Pick what to remove in each row's Remove column (see Tiers).
- Press Preview. The right side lists exactly what will be deleted, rewritten and kept.
- Press Delete, then again to confirm.
The Restore tab lists past wipes by session name; select one and press Restore. History shows everything the tool has done, and Protect list holds paths no wipe may touch. The theme follows Windows, or choose it under View.
Right-click a folder, or the empty space inside one, and choose Wipe agent sessions here. A terminal opens with a checklist for that folder:
↑↓to move,Spaceto tick a session or choose a tier,ato tick all,Enterto continue,Escto cancel- You get the preview, then type
WIPEto confirm
Type /wipe in a Claude Code chat. The agent shows what the folder has and recommends a tier, with the reason: it checks whether the folder is in git, which project files tier 4 would delete, and whether you'll come back to the session. It also lists anything the session installed or changed outside the folder, which no wipe undoes. Then it asks which sessions, which tier, and whether to write a handoff note (it writes its own notes on how things work and what was decided), and queues the wipe. You always make the final choice.
Exit Claude Code (/exit). A SessionEnd hook starts a background runner that waits until Claude Code has closed and the chat has been quiet for 5 minutes, then wipes and saves a summary.
wipe --dry-run # what would go and what stays, for the current folder
wipe # checklist, preview, then type WIPE
wipe --tier 2 --session 1a2b3c4d --yes # without the checklist
wipe --restore # undo the latest wipe
wipe --history # what the tool has doneThe folder is the current one, else its git root, else you're asked. Add --path to name it, --handoff to write a handoff note, or --keep-copies to keep quarantine copies as well as the Recycle Bin.
wipe-setup writes %LOCALAPPDATA%\session-wipe\install.json, which holds the version, the paths of wipe.exe and wipe-app.exe, and which entry points are installed. A launcher or tray app can read it, and show a "Session Wipe" button only when the tool is installed.
A tier sets how much of a session goes. Each tier removes everything the one before it does, plus one more thing.
| When | Tier |
|---|---|
| Almost always. You're done with a session, or you're not sure | 3 |
| A session where everything it created is junk, like a test folder | 4 |
| You'll come back to the session | Don't wipe it |
| A project is finished for good, and you want all its sessions gone | Every session at tier 3, or tier 5 if everything is committed to git (example) |
| Tiers 1, 2 and 5 | Rarely, if ever |
Not sure? Type /wipe in Claude Code: it recommends one and says why.
| Tier | What goes | Your project files |
|---|---|---|
| 1 | The chat itself. It's gone from claude --resume and can't be reopened. |
Safe |
| 2 | Plus the agent's hidden working files for it: logs, backups of edited files, tool results, subagent chats, tasks, background jobs, its temp folder | Safe |
| 3 | Plus your typed messages in the ↑ history, and pasted texts only they used. The session is completely gone. The default. |
Safe |
| 4 | Plus new files the session created in your project (see the rules) | Can be deleted |
| 5 | All of the above for every session in the folder, from every agent (Claude Code, pi and Hermes), not just the one you picked | Can be deleted |
Tiers 1 to 4 only touch the sessions you pick. Tier 5 resets the folder, as if no agent had ever worked there.
- "Tier 1 lets me continue in a new session." It doesn't. A wiped chat can't be continued; a new session only knows what's in your project files. To pick work up later, don't wipe, or have the session write its key decisions into the project first.
- "Tier 4 removes temporary files." It removes every file the session created, temporary or not. The tool can't tell a scratch file from real work.
- "Tier 4 deletes my project." It doesn't. Files committed to git are never removed. If you want nothing left on your PC, push to GitHub, wipe at tier 3, then delete the folder yourself.
- "Tier 4 catches every leftover." It doesn't. It only knows files the session wrote directly, or named as a shell command's output (
echo hi > notes.txt). Build output, downloaded packages, files a script wrote while running, and empty folders stay behind. - "Restore is how I come back to a session." Restore is for undoing mistakes. For work you'll return to, don't wipe.
- "Wiping removes my local copy of the project." It doesn't. No tier removes the project folder, so a local app you run from it keeps working. To remove it, delete the folder yourself.
- "Projects without git are as safe as ones with git." Not at tiers 4 and 5. Git is what protects your files: without it, every file an agent created counts as "created by the session" and can be deleted. In a folder without git, use tier 3, or first create a file named
.wipe-protectin it containing the single line*, which protects every file in the folder. - "Wiping undoes what the session installed." It doesn't. Programs, global packages, settings changes and files outside the project folder all stay. Ask the session what it installed or changed before you wipe (
/wipelists it for you), because afterwards nobody can tell you. Uninstall what you don't need the normal way.
Tier 3 never touches your project, so leftovers can only be stray files in the project folder. Now and then, in a git project, run git status: it lists every file that isn't committed, including ones tier 4 would miss. Delete what you don't want, or ask your agent to list the likely leftovers and delete only the ones you approve.
You've finished a project for good. It won't be updated again, and several sessions in its folder need clearing. Rather than wiping them one by one:
- Commit everything to git and push it, so it's safe on GitHub.
- Clear every session at once:
- Every session at tier 3 (safest): in the app, tick them all and set tier 3; in the right-click checklist, press
ato tick all, then choose tier 3. The project's files aren't touched. - Tier 5 also removes stray new files the sessions made. Only use it when everything you want is committed, because uncommitted files the sessions created can go too.
- Every session at tier 3 (safest): in the app, tick them all and set tier 3; in the right-click checklist, press
- If you don't need it on your PC any more, delete the folder yourself.
A file in your project is only removed if all of these are true:
- The session created it. Files that existed before and were only edited are kept.
- Nothing changed it after the session ended.
- No other session (from any agent) that you're keeping wrote to it.
- Git doesn't track it. Remove tracked files with git if you want them gone.
- It isn't protected.
Files made with shell commands count too, as long as the command names the file and its creation time falls within the session's start and end. Folders and links are never removed. The preview lists every kept file with the reason it was kept.
The /wipe command already follows these rules in Claude Code. Paste the text below into your agent's instructions file as well (for Claude Code, ~/.claude/CLAUDE.md), so the agent gives the same advice whenever you ask about wiping, even outside /wipe. It works for any agent that reads an instructions file.
# Session Wipe tiers
When I ask about wiping sessions with Session Wipe (`wipe`, `/wipe`, the app or the
Explorer entry), explain the tiers in plain words. Each tier removes everything the
one before it does, plus one more thing.
Project files always safe:
- Tier 1: the chat itself. It can't be reopened or continued afterwards.
- Tier 2: plus the agent's hidden working files for it: logs, backups of edited files,
tool results, subagent chats, tasks, background jobs, its temp folder.
- Tier 3: plus my typed messages in the up-arrow history. The session is completely
gone. This is the default and the everyday choice.
Can delete project files:
- Tier 4: plus every new file the session created in the project folder, temporary or
not. It spares files that are git-tracked, protected, only edited, or touched by
another session. It misses files made indirectly (build output, downloaded packages,
files a script wrote) and empty folders.
- Tier 5: all of the above, for every session in the folder from every agent.
No tier removes the project folder itself, programs or packages a session installed,
settings it changed, or files outside the project folder. Without git, tiers 4 and 5
can delete real work.
My rule: tier 3 for almost everything; tier 4 only when everything the session created
is junk; don't wipe a session I'll come back to. Tiers 1, 2 and 5 are rarely needed.
Rules:
- Always recommend one tier with a one-line reason, then let me choose. Check first:
will I come back to the session, is the folder in git with everything committed, and
which project files tier 4 would delete.
- Recommend tier 3 unless every file tier 4 would delete is junk. For a finished
project, recommend every session at tier 3, or tier 5 only if everything is committed.
- Before wiping, list anything the session installed or changed outside the project
folder; the wipe doesn't undo it.
- A wiped session can't be continued. If I want to pick the work up later, suggest not
wiping, or writing the key decisions into the project first.
- Before I confirm tier 4 or 5, list by name the project files it would delete, and
warn me about new files I haven't committed to git.
- To find leftovers after tier 3, use `git status` and let me approve each deletion.
- Never pick the tier or sessions for me; ask.wipe --restore [id](or the Restore tab) puts back what a wipe removed: from the Recycle Bin, or from the quarantine copy if the bin was emptied.- Prompt-history lines are merged back. Prompts typed since the wipe are kept, in order.
- Hermes sessions are re-imported from their export. Hermes gives them a new id; the folder and title are kept.
- Every wipe, refusal and restore is recorded in
%LOCALAPPDATA%\session-wipe\activity.jsonl, with the time, folder and session names, never their contents.
- Preview first: Delete does exactly what the preview listed, nothing worked out afterwards.
- Recycle Bin, proven: a small test file goes to the bin first. If it isn't found, the bin is turned off by policy, or the wipe might not fit, everything gets a quarantine copy. Files with paths near Windows' 260-character limit always do, because the bin deletes those outright.
- Shared files backed up: Claude Code's
history.jsonlis backed up and checked byte for byte before it's rewritten, under Claude Code's own lock. - Exact paths only: every path must be one of the chosen sessions' own files, inside the agent's folder. Links and junctions are refused, and so is anything protected.
- Live check before every item, not just once, so a session that starts mid-wipe stops it and everything is put back.
- Hermes through its own CLI only: each session is exported to JSONL, Markdown and a re-importable trace before
hermes sessions delete. The database is never opened. Pinned sessions are kept. - Local only: the tool makes no network requests. Nothing about your sessions leaves your PC.
What each agent keeps, and where, is described in docs/ADAPTERS.md.
A session I closed still shows "IN USE"
The tool waits until a session hasn't been written to for 5 minutes. Wait a moment, then press Rescan.
All my pi sessions show "IN USE"
pi doesn't record which session is open, so while any pi window runs, all pi sessions count as in use. Close pi first.
A restored Hermes session has a different id
Hermes can't import a session under its old id. The messages, folder and title come back; links to delegates don't.
The window takes a few seconds to fill
It reads every session from all three agents when it opens. The window stays usable while it scans.
Does it delete anything permanently?
Not by itself. Files go to the Recycle Bin, with quarantine copies when needed. Emptying the Recycle Bin afterwards makes a wipe permanent, unless it kept quarantine copies (--keep-copies always does).
Can it wipe the Claude Code chat I'm typing in?
Not while it's open. Use /wipe, which wipes it after you exit.
Which agents and versions?
Claude Code (tested on 2.1.x), pi (0.85) and Hermes Agent (0.21), on Windows. Other agents can be added as adapters; see ARCHITECTURE.md.
macOS or Linux?
Not yet: the Recycle Bin, the registry entry and the Start menu shortcut are Windows features. The core is mostly portable.
Requirements: uv (it fetches Python 3.12 by itself).
git clone https://github.com/astqh/session-wipe
cd session-wipe
uv sync --extra app
uv run pytest -q
uv run wipe-appuv build makes the wheel in dist/. To try your copy as the installed tool: uv tool install --editable ".[app]", then wipe-setup.
Issues and pull requests are welcome. Read CONTRIBUTING.md first: the tests must never touch your real agent folders, and every change to what gets deleted needs a test that proves it. ARCHITECTURE.md explains how the pieces fit.