English |
简体中文 |
繁體中文 |
日本語 |
한국어 |
Español |
Français |
Deutsch |
Português (Brasil) |
Русский
Obituary — the trash bin for AI agents
What your AI leaves behind leaves on its own when it expires; what your AI deletes comes back for seven days.
Why Obituary · Install · Quick start · User guide · Docs
Obituary is the trash bin for AI agents: the agent and you decide what goes in. An agent gives the debug scripts, logs and screenshots it writes a lifespan as it writes them, and you add your own files from the right-click menu; whatever is in is buried when its time is up and can be restored as it was for 7 days. Nobody has to remember to clean up, and an agent's rm -rf no longer destroys anything for good. How it works inside: docs/architecture.md (Chinese).
Why Obituary
Agents pushed us into writing it. As soon as version 0.0.1 ran we installed it on our own machines, and every version since was written by agents in repositories it was watching.
- Agents make mess faster than people clean it up. Rotate between Claude Code, Codex, DeepSeek and WorkBuddy and a project soon fills with debug scripts, logs, screenshots and
test-results/. Nobody can say which of it still matters, so nobody dares delete any of it. Obituary leaves the call to whoever knows best: an agent knows which debug scripts and logs it wrote and gives them a lifespan withobit markas it writes them; you add your own files from the right-click menu. Once in, they are buried when due, and nobody has to remember to clean up. - Not sure it's still needed? Bury it.
obit burymoves it into the graveyard, where it stays restorable as it was for seven days before it is really deleted. If an agent reaches for it during those seven days, Obituary tells it on the spot: it is in the graveyard, here is its number, andobit resurrectputs it back. The rest of the time it stays out of the way: an agent starts work knowing only that Obituary is there, without reading a list first. - Afraid of one
rm -rf. Agents wiping a home directory or a whole drive is no longer hypothetical; people have posted it more than once. With the delete guard on, an agent'srm -rf,git cleanorRemove-Itemis stopped and replaced by the equivalentobitcommand: things go to the graveyard instead of disappearing. Detours such asfind -deleteandxargs rmare stopped too. - Afraid the command changes on the way. Between the command an agent means and the one that runs sit shell quoting, escaping and sometimes a proxy that rewrites commands. Lose one character and
rm -rf "$OUT"/becomesrm -rf /. So Obituary does not trust the command text alone: beforeobit rmtouches anything it checks the real path on disk, refuses drive roots, system directories and the user profile itself, and buries everything else where it can be resurrected. On Windows, Codex passes the command through another shell where quoting may fail, so a deletion inside backticks or$(…)in its commands is stopped even when it sits in quotes.
What it does
- Give files and folders a lifespan.
obit add debug.log 2hburies it when time is up. Pick a moment with--at, extend it any time (extend), or spare it (spare). - The agent decides what goes in.
obit initadds Obituary to the agent's instructions (OBIT.md, an Agent Skill, MCP optional). The agent gives the debug scripts, logs and screenshots it writes a lifespan withobit mark, takes scratch space fromobit mktemp, buries what it is unsure about withobit bury, and registers the*.bakfiles it leaves while editing. - You add your own. On Windows, right-click files or folders in Explorer (several at once is fine), choose "Add to Obituary" and then 1, 7 or 30 days, or "Bury now (recoverable)"; or give a folder such as Downloads a policy.
- Automatic registration when you want it. Off by default: nothing goes in by itself. Turned on in Settings, it registers by rule (
.playwright-mcp/,test-results/,*.log, the*.bak,*.origor*~backups left when editing, and so on) and from the writes the hooks see, in one of three modes: tiered (what the agent created this session goes straight in, files that were there before wait for you), fully automatic, or ask about everything. Dependencies, build output and caches are never registered automatically in any mode, and files tracked by Git are never touched. - End-of-session tidy-up. When an agent is about to stop, Obituary lists the files it created this session that nothing has sorted yet and asks it to give debug scripts, logs and screenshots a lifespan or bury them, keeping the deliverables. At most once per session.
- Anything an agent deletes can come back. With the delete guard on, an agent's
rm -rf,git cleanand similar commands are stopped and the agent is told the equivalentobitcommand. It uses that instead, and things go to the graveyard rather than disappearing. - Bury first, purge later. The graveyard keeps everything for 7 days by default;
obit resurrectputs it back where it was and never overwrites what is there now. - Files are tracked by identity, not by name. Every record keeps the volume serial number and the 128-bit file ID, so a renamed or moved file is still found, and a different file that now sits at the old path is left alone.
- Claude Code and Codex.
obit initregisters hooks and an Agent Skill; an MCP server is optional;--uninstallremoves only what Obituary added. - Lives in the tray, like Everything (Windows).
obit initstarts a tray icon at login. Its menu shows recent burials (click one to resurrect it), lets you pause automatic cleanup, and opens Obituary's small window. A Windows scheduled task remains as a fallback. - A small window (Windows / Ubuntu 24.04 amd64). Expiring, Graveyard, For you, Settings and Logs: resurrect files, approve proposals and change settings without the command line (
obit-gui.exe, or "Open Obituary" in the tray menu). Chinese and English, eight looks. On Ubuntu, open Obituary from Applications. - Context menu and dates in Explorer (Windows). Right-click files or folders (several at once is fine) → "Add to Obituary" → 1, 7 or 30 days, or "Bury now (recoverable)"; on Windows 11 it is under "Show more options". Tracked items in Downloads and on the Desktop show as "name (11-13 burial)" while the real file name stays the same.
- Docker containers.
obit docker add <container> 3dgives a container a lifespan; at expiry it is stopped withdocker stop(obit resurrectstarts it again) and removed withdocker rmonly after the retention period. Volumes and images are never touched. With automatic registration on, containers an agent session started for the project are registered too, and you are told afterwards. - Folder policies.
obit watch Downloads 2w: every file that lands there is buried two weeks later. An expired subfolder only produces a proposal and is buried after you approve it. The policy itself needs your approval too.
Install
Windows 10 / 11, macOS and Linux (x64 and ARM64). Send this sentence to the agent you use. It installs Obituary, connects it to itself and stops wherever a decision is yours:
Read https://obituary.woodfish.site/agent-install.md and follow it to install Obituary and connect it to yourself.
Each platform at a glance:
| Windows | macOS | Linux | |
|---|---|---|---|
| Install with | Scoop, the install.ps1 script (winget in review) | Homebrew, the install.sh script | the install.sh script |
| Checks for expiry every 5 minutes | resident tray process, Task Scheduler as a fallback | user launchd agent | systemd --user timer; a user crontab without systemd |
| CLI, graveyard and resurrection, automatic registration (optional), delete guard, agent integration (hooks, Skill, MCP), Docker containers, folder policies | yes | yes | yes |
| Tray, small window, context menus, burial dates in Explorer, Start menu and desktop shortcuts | yes | Window and tray on macOS (universal DMG); no context menu yet | Window and tray on Ubuntu 24.04 amd64 (deb) |
| Recycle Bin mode | yes | graveyard only | graveyard only |
Installing by hand, updating and uninstalling: see the install guide.
Switch language
Obituary currently supports English and Simplified Chinese in the command line, tray, small window and Explorer menu.
- Temporary: set OBIT_LANG=en or OBIT_LANG=zh-CN before a command.
- Save it: run obit config --language en, obit config --language zh-CN or obit config --language auto.
- Automatic choice: remove OBIT_LANG and keep ui.language = auto; Obituary checks the configuration, LC_ALL, LC_MESSAGES, LANG and the operating system UI language.
- Translated in this phase: list, bury and resurrect output and help, plus the Windows tray and native menu text. Hook and MCP protocol text stays English and stable.
Quick start
Common commands (replace <id> with the number from an obit add or obit bury receipt, or from obit list / obit graveyard):
obit add debug.log 2h # bury it in 2 hours (alias: mark)
obit add output\shots 1d12h # folders work too
obit add report.zip --at "2026-12-01 18:00" # at a given moment
obit list # what is left and for how long
obit extend <id> 1d # one more day
obit spare <id> # stop tracking, keep the file (alias: cancel)
obit reap # bury everything that is due now (alias: sweep; --dry-run previews)
obit bury old-build # bury right away
obit graveyard # what is in the graveyard and when it will be purged (--here: this folder only)
obit resurrect <id> # put it back; if the name is taken, it comes back renamed, never overwriting
obit resurrect --last # undo the last deletion: everything one obit bury / obit rm buried comes back
obit purge # purge what is past retention (--all for everything, after confirming; --dry-run previews)
obit purge <id> # purge this grave now (permanent; asks first, --yes outside a terminal); also abandons an unverifiable interrupted resurrect
obit stats # eulogy: how much was buried, space freed, resurrections (alias: eulogy)
obit log # the full record of everything done
Background running, connecting each agent, the delete guard, MCP and the Skill are covered in the user guide.
Documentation
- User guide: every feature in detail
- Install guide: installing by hand, updating and uninstalling
- Agent coverage: how far each of the 30 agents connects
- Docs index: every document, including the architecture and code conventions
- Code signing policy: Free code signing provided by SignPath.io, certificate by SignPath Foundation
- Privacy policy
Build Obituary with us
Issues and pull requests are welcome. The most welcome is an issue that comes with its fix: you found it, you fixed it, and once it is merged your avatar shows up here. CONTRIBUTING.md says how to start; report anything that could delete the wrong file privately, as SECURITY.md describes.
Chinese-speaking users also chat in the QQ group 1135603207 and on the LINUX DO community.
