Agent Aftercare

Your AI made the mess. Make it clean it up — without deleting your work.

繁體中文

AI coding agents are excellent at creating things and terrible at taking out the trash. Old sessions, duplicated subagent histories, and abandoned worktrees quietly grow until you need disk space right now.

You could hunt through hidden folders yourself. You could also delete the wrong thing. Agent Aftercare gives you the lazy, cowardly, sensible option:

1. see only known agent residue;
2. refuse anything recent or tied to a detected provider process;
3. compress and deduplicate what you choose;
4. restore the exact bytes if you regret it.

Important

Agent Aftercare is alpha software. Version 0.1 quarantines old session logs. It detects known worktree roots but deliberately blocks worktree removal until Git metadata can be restored safely.

The 15-second demo

$ python -m scripts.demo
scan: 4 found | 3 review | 1 blocked
  claude review   2340000 bytes
  codex  review   2340000 bytes
  gemini review    875000 bytes
  codex  blocked       12 bytes
quarantine: 5555000 original bytes -> 9494 new stored bytes
dedupe: 1 reused object
restore: exact_bytes=True

This is the real output of scripts/demo.py, using disposable fake sessions. It does not invent a 200 GB success story.

Why this exists

This is not a theoretical cleanup problem:

• a Codex user reported a .codex/sessions directory above 400 GB after image data was duplicated about 150,000 times (openai/codex#35470);
• another reported 118 untracked run copies consuming 202 GB (openai/codex#35383).

Generic disk analyzers can show a large folder. Generic cleaners can delete it. Neither knows whether an AI session is still active, whether a path is agent state, or whether the deleted bytes can be reconstructed.

Install

Download the standalone executable for Windows, macOS, or Linux from Releases. No model, API key, daemon, or account is required.

Or run from Python 3.10+:

python -m pip install git+https://github.com/leavemagic-cyber/agent-aftercare.git
aftercare --version

Use

Scanning is read-only:

aftercare scan
aftercare scan --min-age-days 60
aftercare scan --json
aftercare scan --all

Human output shows reviewable items first and stops at 50 rows by default; --all expands it and --json always returns the complete set.

Every session log is labeled review, never safe, because it contains conversation history. Recent items and items tied to an exactly named provider process detected by the operating system are blocked.

Quarantine one ID only after reviewing it:

aftercare quarantine claude-session-log-a1b2c3d4e5f6071829 --accept-review
aftercare list

Undo it:

aftercare restore q-1788020000-a1b2c3d4e5f6071829

Permanently discard the quarantine only when you no longer need undo:

aftercare purge q-1788020000-a1b2c3d4e5f6071829 --yes

Traditional Chinese output is available on every command:

aftercare --lang zh-TW scan

What version 0.1 recognizes

Provider	Read-only discovery root	Action in v0.1
OpenAI Codex	~/.codex/sessions/**/*.jsonl	Review, quarantine, restore
Claude Code	~/.claude/projects/**/*.jsonl	Review, quarantine, restore
Gemini CLI	~/.gemini/tmp/*/chats/**/*.jsonl	Review, quarantine, restore
All three	known worktrees/ roots	Visible, always blocked

Agent Aftercare never treats source code, .git, credentials, settings, AGENTS.md, CLAUDE.md, memory folders, local databases, or uploads as v0.1 cleanup candidates. It does not scan the rest of your home directory.

What “reversible” means

Before the original session is removed, Agent Aftercare:

1. streams it into a deterministic gzip object;
2. addresses that object by SHA-256 content hash;
3. decompresses and hashes the stored object again;
4. checks that the source did not change during capture;
5. writes an atomic captured manifest;
6. atomically detaches the source into a same-directory staging path, verifies that exact file again, then removes the staging link;
7. advances the manifest to quarantined.

Identical sessions share one object. aftercare list reports the new bytes actually consumed by quarantine, not just the original file size.

By default the store lives in %LOCALAPPDATA%\AgentAftercare on Windows or $XDG_DATA_HOME/agent-aftercare / ~/.local/share/agent-aftercare on Unix. Set AFTERCARE_STORE to place it on another disk.

Note

Reversible compression needs temporary free space while an object is being captured. An out-of-space or verification failure preserves the original. A crash after capture but before final manifest advancement leaves a restorable captured manifest.

Security and privacy

• local-only; no network calls or telemetry;
• read-only by default;
• exact known roots and .jsonl files only;
• symlinks are not followed;
• process enumeration and age validation fail closed; exact process-name detection is a best-effort extra guard, while recency is the hard gate;
• restore never overwrites an existing path;
• permanent purge requires both an ID and --yes.

See SECURITY.md for the threat model and reporting process.

Roadmap

• provenance-backed orphan temp-clone discovery;
• safe Git worktree removal and metadata restoration;
• checkpoint/blob adapters where formats are stable enough to fail closed;
• signed release checksums and package-manager installs.

The rule for new adapters is simple: if Aftercare cannot prove what created a path and how to undo the action, it may report the path, but it will not remove it.

Development

python -m unittest discover -v
python -m scripts.demo
python -m aftercare --help

The runtime has no third-party Python dependencies. Standalone release binaries are built with PyInstaller in GitHub Actions. Contributions that widen deletion scope must include failure-mode tests and a reversible design.

MIT licensed.