Trash

delete_file, move_file overwrites, and apply_patch's *** Delete File operations are recoverable by default. Instead of unlinking the target, they compress the file into a per-workspace .tar.gz archive containing the file at its original workspace-relative path and a metadata.json record. Permanent deletes are an explicit opt-in.

Location

The trash root lives in the shared CommaAgents data directory:

<dataDir>/trash/<sha256(workspaceRoot)>/<timestamp>-<sessionId>-<runId>-<basename>.tar.gz

dataDir is resolved by resolveDataDir() to ~/.comma on every platform.

Each workspace has its own subdirectory keyed by sha256(workspaceRoot) so multiple workspaces on the same host do not collide. The leaf name includes the timestamp, truncated session ID, run ID, and original basename for identification.

Archive contents

Every trash archive is a .tar.gz containing:

• metadata.json — { sessionId, runId, agentName, trashedAt, originalPath, originalSha256 }
• The original file at its workspace-relative path (e.g., src/utils/helper.ts)

This preserves the directory structure so the file can be restored to its exact original location.

User-managed lifecycle

There is no automatic garbage collection. Trash entries persist until explicitly cleared. The daemon exposes protocol messages for listing, restoring, and clearing trash per workspace, which the TUI (and any client) can use to present a trash management interface.

Restoring a deleted file

Use the built-in restore_file tool to recover a trashed file from its archive. Pass the absolute trash archive path (from delete_file's data.trashedTo or the audit log) and optionally a targetPath override:

{
  "trashedPath": "/Users/.../trash/<hash>/2026-05-16T...-a1b2c3d4.tar.gz",
  "targetPath": "src/recovered.ts"
}

The archive is removed from the trash directory after a successful restore.

Clearing trash

Trash can be cleared from the daemon protocol (trash_clear message) or by removing the workspace's trash directory directly. The daemon protocol also supports listing trash entries (trash_list) for inspection before clearing.

Permanent delete

Passing permanent: true to delete_file skips the trash entirely. The bytes are unlinked in place; there is no recovery path. Use this only when the file is genuinely disposable (build output, temp scratch files).

Related

• delete_file — uses the trash by default.
• restore_file — recovers files from trash archives.
• Audit log — records the trashed-to path for every recoverable delete.