Quick start
Obituary gives files and folders a lifespan. When it runs out they are buried in a graveyard; you can resurrect them at any time during the retention period (7 days by default), and only after that are they really deleted. It is built for AI agents: the debug scripts, logs, screenshots and test output an agent produces carry a lifespan from the moment they are created. Nobody has to remember to clean up, and an agent's rm -rf no longer destroys anything for good.
1. Install
Windows 10 / 11, macOS and Linux (x64 and ARM64):
| 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 | the CLI instead: obit list, obit graveyard, obit resurrect | as on macOS |
| Recycle Bin mode | yes | graveyard only | graveyard only |
Easiest: let your agent do it. Send this sentence to the agent you use (Claude Code, Codex, Cursor…). 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.By hand: choose your operating system below, then run obit doctor to check the installation.
macOS / Linux
On macOS, Homebrew installs it in one line:
brew install --cask woodfishhhh/tap/obituaryOr download and read the install script, then run it (macOS and Linux):
curl -fsSL https://raw.githubusercontent.com/woodfishhhh/obituary/main/install.sh -o install.sh
bash install.sh
# Custom directory: --install-dir "$HOME/bin"; preview only: --dry-runThe script installs the latest release by default (--version <version> picks another). The archive downloads in four parts at once (some routes cap the speed of each connection) and falls back to one connection when that does not work. It detects the OS and architecture, verifies SHA-256 from the same download source, and installs obit and obitd into ~/.local/bin. Follow its PATH instructions, then run obit --version. Use --mirror cn for the mainland China mirror; its script is at https://cn.obituary.woodfish.site/install.sh.
On first use in macOS, run obit --version and obitd --help. If Gatekeeper asks for approval, open System Settings → Privacy & Security, choose Open Anyway for each executable whose source you verified, then retry the command.
In WSL, keep projects and agent configuration on the Linux filesystem (for example, under ~/projects). Windows mounts such as /mnt/c may not support the safe renames required for installation; the operation reports an error and preserves the original configuration. You can also use the Windows edition of Obituary directly.
Windows
scoop bucket add obituary https://github.com/woodfishhhh/scoop-bucket
scoop install obituary# In review, available once approved
winget install woodfishhhh.Obituary# Install script: download it, read it, then run it
# (installs to %LOCALAPPDATA%\Programs\obituary, adds it to your user PATH, creates a Start menu shortcut)
irm https://raw.githubusercontent.com/woodfishhhh/obituary/main/packaging/install.ps1 -OutFile install.ps1
.\install.ps1 # installs the latest release; -WhatIf previews, -NoPath leaves PATH alone- All three download the same archive from the GitHub release and check its SHA-256 before unpacking; a mismatch stops the install.
- Code signing: Free code signing provided by SignPath.io, certificate by SignPath Foundation. See the code signing policy and the privacy policy.
- Obituary is not code-signed yet. If you download the archive with a browser, Windows may show "Windows protected your PC"; choose "More info → Run anyway". Scoop, winget and the install script usually do not trigger this.
- The small window
obit-gui.exeneeds the WebView2 runtime (built into Windows 11 and present on most Windows 10 machines) and is x64 only; the ARM64 build has the command line and the tray. Then check the installation:
obit doctor # read-only check: PATH, obitd, runner, Claude Code / Codex integration, data directory, ledger, config (--json)2. Connect your agents
obit init -g # Claude Code, all projects; also the Skill (and desktop integration on Windows)
obit init -g --agent codex # CodexRestart the agent afterwards. Other agents, the MCP server and the Agent Skill: Connect agents.
On macOS / Linux, Claude Code uses ~/.claude, Codex uses ~/.codex, and shared Skills use ~/.agents/skills. CLAUDE_CONFIG_DIR and CODEX_HOME overrides are also respected.
Enable the user scheduler to check expiries every 5 minutes:
obit daemon enable --dry-run
obit daemon enable
obit doctormacOS uses the signed-in user's launchd; Linux uses systemd --user. On Linux without systemd, schedule obitd --once every 5 minutes in the user's crontab, supplying absolute paths for obitd, the --home data directory and the --config-dir configuration directory. Agent hooks also start a background check when work is due.
3. 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 list # what is left and for how long
obit extend <id> 1d # one more day
obit bury old-build # bury right away
obit graveyard # what is in the graveyard and when it will be purged
obit resurrect <id> # put it back, never overwriting
obit resurrect --last # undo the last deletionEverything else: Commands.
Next
| To find out | Read |
|---|---|
| How registering, burying, resurrecting and purging work, and where the graveyard is | How it works |
| Connecting Claude Code, Codex and other agents | Connect agents |
| What goes in: agent registrations, the context menu, optional automatic registration | What goes in |
Turning an agent's rm -rf into a burial you can undo | Delete guard |
| What happens when an agent reaches for a buried file | Grave notices |
| Lifespans for folders such as Downloads and Desktop | Folder policies |
| Using Obituary without the command line | Window, tray and context menu |
| Docker containers started in a session | Docker containers |
| Every command | Commands |
| Removing Obituary | Uninstall |
| Anything else | FAQ |