Install and verify Agent Trash Guard.

Block recognized permanent deletes from coding agents. Move a file to local trash, inspect its entry, and restore it by ID.

View source ↗Product overview →

Read-only verificationafter native install

$ agent-trash --version
$ agent-trash list

§ 01

Prerequisites and installation

Choose one host

Use Python 3 and bash. Choose one released host adapter below. Do not install both the portable Claude plugin and the legacy Claude-only adapter: that can report each blocked command twice.

CLAUDE CODEInstall the portable plugin

$ claude plugin marketplace add hermes-labs-ai/agent-trash-guard && claude plugin install agent-trash-guard@hermes-labs

CODEX CLI · 0.145+Install the Codex adapter

$ codex plugin marketplace add hermes-labs-ai/agent-trash-guard && codex plugin add agent-trash-guard@hermes-labs

Run it through Codex's Bash tool after the explicit /hooks trust review.

GEMINI CLIInstall the repository extension

$ gemini extensions install https://github.com/hermes-labs-ai/agent-trash-guard --ref main

Restart Gemini CLI, then use its run_shell_command tool.

For a checkout you want to inspect first, clone https://github.com/hermes-labs-ai/agent-trash-guard, run ./tests/run.sh, and use the host's local-plugin workflow documented in the repository README.

§ 02

First safe check

A real move and restore

This walkthrough is for the released Claude Code plugin, which exposes agent-trash on Claude's Bash-tool PATH. It does not promise a globally installed command in an unrelated terminal. For Codex or Gemini CLI, use the exact quoted path printed when the guard blocks a delete, or run python3 <plugin-or-extension-root>/bin/agent-trash.

STEP 01 · CLAUDE BASH TOOLCreate a disposable file

$ scratch_dir=$(mktemp -d); printf 'recover me\\n' > "$scratch_dir/recover-me.txt"; printf '%s\\n' "$scratch_dir/recover-me.txt"

Copy the printed absolute path as FILE_PATH. Run each remaining step as a separate Claude Bash-tool call.

STEP 02 · CLAUDE BASH TOOLConfirm the hook blocks a delete

$ rm "FILE_PATH"

The hook blocks rm; the file remains at FILE_PATH.

STEP 03 · CLAUDE BASH TOOLMove it into trash and inspect the receipt

$ agent-trash put "FILE_PATH"
$ agent-trash list

list shows a timestamped entry and the original path. Copy its identifier as ENTRY_ID.

STEP 04 · CLAUDE BASH TOOLRestore the entry

$ agent-trash restore <ENTRY_ID>
$ cat "FILE_PATH"

Replace both placeholders with the copied values. The final command prints recover me.

agent-trash --version is useful for diagnosing an install, and agent-trash list is read-only. In Codex, trust the hook through /hooks before using delete interception.

§ 03

Recover, retain, and update

Inspect before any permanent action

Use agent-trash put path to create a timestamped entry, agent-trash list to inspect entries, and agent-trash restore ENTRY to restore one. Restore refuses to overwrite a newer file unless --force is explicitly supplied.

Set AGENT_TRASH_DIR to relocate the local trash. agent-trash empty --older-than 7 --yes is a permanent delete. agent-trash gc reports by default; it only collects with --collect and keeps protected, unknown, reachable, and too-young work. Update through your host's plugin or extension command, then repeat the checks above.

§ 04

Troubleshooting and limits

Recognized shell deletes only

If the CLI is missing, repeat the host readback in the repository README and restart the host where its documentation requires it. If a delete was not blocked, check that the host adapter is installed and trusted, then compare the command against the documented supported patterns.

The guard fails open on unparseable hook events and excludes overwrites, truncations, cloud/API deletion, and unsupported command forms. Read the supported-command boundary, v0.1.3 release, and MIT license.