Skip to content

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):

WindowsmacOSLinux
Install withScoop, the install.ps1 script (winget in review)Homebrew, the install.sh scriptthe install.sh script
Checks for expiry every 5 minutesresident tray process, Task Scheduler as a fallbackuser launchd agentsystemd --user timer; a user crontab without systemd
CLI, graveyard and resurrection, automatic registration (optional), delete guard, agent integration (hooks, Skill, MCP), Docker containers, folder policiesyesyesyes
Tray, small window, context menus, burial dates in Explorer, Start menu and desktop shortcutsyesthe CLI instead: obit list, obit graveyard, obit resurrectas on macOS
Recycle Bin modeyesgraveyard onlygraveyard 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:

text
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:

bash
brew install --cask woodfishhhh/tap/obituary

Or download and read the install script, then run it (macOS and Linux):

bash
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-run

The 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 ​

powershell
scoop bucket add obituary https://github.com/woodfishhhh/scoop-bucket
scoop install obituary
powershell
# In review, available once approved
winget install woodfishhhh.Obituary
powershell
# 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.exe needs 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:
powershell
obit doctor              # read-only check: PATH, obitd, runner, Claude Code / Codex integration, data directory, ledger, config (--json)

2. Connect your agents ​

powershell
obit init -g                 # Claude Code, all projects; also the Skill (and desktop integration on Windows)
obit init -g --agent codex   # Codex

Restart 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:

bash
obit daemon enable --dry-run
obit daemon enable
obit doctor

macOS 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.

powershell
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 deletion

Everything else: Commands.

Next ​

To find outRead
How registering, burying, resurrecting and purging work, and where the graveyard isHow it works
Connecting Claude Code, Codex and other agentsConnect agents
What goes in: agent registrations, the context menu, optional automatic registrationWhat goes in
Turning an agent's rm -rf into a burial you can undoDelete guard
What happens when an agent reaches for a buried fileGrave notices
Lifespans for folders such as Downloads and DesktopFolder policies
Using Obituary without the command lineWindow, tray and context menu
Docker containers started in a sessionDocker containers
Every commandCommands
Removing ObituaryUninstall
Anything elseFAQ

Released under the MIT license.