Session Cleanup Skill

Purpose

Track and clean up all artifacts produced during a Claw-family agent session:
- Temporary files, demo scripts, and test outputs written to disk
- Python packages, npm packages, system software installed via pip/npm/brew/apt/winget
- Skills installed into ~/.workbuddy/skills/ or .workbuddy/skills/
- Any other transient resources that are no longer needed after the session

Lifecycle — Two Phases

Phase 1 · Tracking (activated at session start or on demand)

Trigger words (start tracking):
开启清理追踪 | 启动会话清理 | session cleanup start | track session files |
开始记录临时文件 | enable cleanup tracking

On activation:
1. Announce: "✅ 会话清理追踪已开启。我将记录本次对话中生成的所有临时文件、安装的库与 Skill。"
2. Create a persistent tracking file at <workspace>/.workbuddy/session-track.json with the following structure. If the file already exists from a previous interrupted session, load it and announce: "✅ 发现上一次会话的追踪记录，已恢复。"
json { "started_at": "ISO-8601 timestamp", "workspace": "path/to/workspace", "items": { "temp_files": [], "pip_packages": [], "npm_packages": [], "system_software": [], "skills": [], "other": [] }, "skip_list": [] }
3. After each subsequent tool call that produces a tracked artifact, append the item to the relevant array in session-track.json using replace_in_file or write_to_file. This ensures the tracking log survives token overflow, session resets, or unexpected interruptions. Do NOT announce each individual append.

What to track — detection rules:

Auto-tracking enforcement (critical — prevents missed items):

After EVERY tool call while tracking is active, perform a quick post-check on the tool call result. This is mandatory and must not be skipped:

1. write_to_file — Check if the filePath is in a temp/scratch/generated path OR if the explanation contains keywords: "temporary", "demo", "test", "example", "scratch", "临时", "演示", "测试". If yes → append to temp_files in session-track.json.

2. execute_command — Scan the command string for:
   - pip install / pip3 install / uv pip install → extract package name, append to pip_packages
   - npm install / npm i → extract package name, append to npm_packages
   - winget install / choco install / apt install / brew install / scoop install → extract package name, append to system_software
   - Any command that creates a file in a temp path (redirect to %TEMP%, /tmp, etc.) → append to temp_files

3. use_skill or init_skill.py** — If a new skill is being installed or initialized, append the skill path to skills.

4. User's explicit instruction — If the user says "track this" / "记录这个" / "add to cleanup", append to other.

This post-check should be a silent, automatic step — do NOT announce it to the user. Simply update session-track.json in the background.

Phase 2 · Cleanup (triggered on demand or session end)

Trigger words (run cleanup):
清理垃圾文件 | 结束清理 | 清理对话文件 | cleanup now | clean session |
清理临时文件 | 会话清理 | 帮我清理 | 删除临时文件 | clean up

Cleanup workflow — follow these steps in order:

Step A · Display the session log

Read session-track.json from <workspace>/.workbuddy/. Print the full tracked list as a Markdown checklist grouped by category. Format each category array as a checklist. Example output:

## 本次会话产生的资源清单

### 🗂 临时文件
- [ ] C:\Users\<user>\AppData\Local\Temp\demo_script.py
- [x] C:\Users\<user>\AppData\Local\Temp\keep_this.py (保留)
- [ ] /path/to/workspace/generated-images/test.png

### 📦 安装的 Python 包
- [ ] requests==2.31.0

### 🧩 安装的 Skills
- [ ] ~/.workbuddy/skills/my-test-skill/

If the tracked list is empty (excluding skip_list items), say: "📭 本次会话未检测到可清理的资源。" and stop.

When classifying, check skip_list in session-track.json — any item in skip_list should be excluded from cleanup and shown as "保留" in the summary.

Step B · Classify items

For each tracked item, classify it as either:

• A: Safe to auto-delete — files with no dependencies (temp files, demo scripts, test outputs, generated images). These are deleted without asking.
• B: Requires confirmation — installed packages, Skills, or system software that may have dependencies or ongoing utility. These require explicit user consent.

Step C · Auto-delete safe items (Class A)

1. List all Class A items and announce: "以下临时文件将直接清除："
2. Choose deletion strategy based on item count:
   - 5 items or fewer → Agent deletes each item individually using delete_file (workspace files) or execute_command (non-workspace files). This gives step-by-step visibility and is token-efficient for small lists.
   - 6+ items → Agent runs cleanup.py in two phases:
   1. Preview: python "<skill_dir>/scripts/cleanup.py" --track-file "<workspace>/.workbuddy/session-track.json" --dry-run
   2. Execute: python "<skill_dir>/scripts/cleanup.py" --track-file "<workspace>/.workbuddy/session-track.json"
      This leverages the script's built-in safety checks, trash-first logic, and batch efficiency.
      - User explicitly requests one-click cleanup → Use cleanup.py regardless of item count.
3. Deletion method per file (when deleting individually):
   - Files inside the workspace → use delete_file tool directly.
   - Files outside the workspace (e.g. %TEMP%, /tmp, home directory) → use execute_command with a trash-first strategy:
   • Windows — Move to Recycle Bin first; only hard-delete if trash fails:
     powershell # Try Recycle Bin first (safe, reversible) $shell = New-Object -ComObject Shell.Application $item = $shell.NameSpace(0).ParseName('<file_path>') $item.InvokeVerb('delete')
     If the above fails or the item doesn't appear in Recycle Bin, fall back to:
     Remove-Item "<file_path>" -Force
   • macOS — osascript -e 'tell app "Finder" to delete POSIX file "<file_path>"'
     Fallback: rm "<file_path>"
   • Linux — gio trash "<file_path>" or trash-put "<file_path>"
     Fallback: rm "<file_path>"
4. Confirm deletion result for each item (✅ deleted / ⚠️ failed).
5. For temp directory files (%TEMP%, /tmp), hard-delete is acceptable since these are OS-managed scratch spaces. For all other paths, always prefer trash.

Step D · Confirm before removing dependencies (Class B)

For each Class B item, present a grouped confirmation prompt:

以下资源涉及依赖关系，需要您确认是否删除/卸载：

📦 Python 包:
  • requests==2.31.0  → pip uninstall requests

🧩 Skills:
  • ~/.workbuddy/skills/my-test-skill/  → 将永久删除

请回复：
  全部删除 / 全部保留 / 逐一确认

• If user replies 全部删除 → uninstall/remove all Class B items.
• If user replies 全部保留 → skip all, close the log.
• If user replies 逐一确认 → iterate through each item and ask individually.

For package uninstalls:
- Pip: pip uninstall -y <package> via execute_command
- npm: npm uninstall -g <package> via execute_command
- winget: winget uninstall --id <id> via execute_command
- choco: choco uninstall <package> -y via execute_command
- brew: brew uninstall <formula> via execute_command
- apt: sudo apt remove -y <package> via execute_command
- scoop: scoop uninstall <app> via execute_command

For Skills uninstall:
- Delete the skill directory via execute_command:
- Windows: Remove-Item -Path "<skill_dir>" -Recurse -Force
- macOS/Linux: rm -rf "<skill_dir>"
- Do NOT use delete_file for skill directories as they are typically outside the workspace.
- Always warn: "⚠️ Skill 删除是永久性的，目录下所有文件将被移除。"

For system_software uninstall:
- Always treat as Class B (requires confirmation).
- Present the exact uninstall command that will be run so the user can verify.
- If the package was installed via winget, try winget list <name> first to find the exact ID before uninstalling.

Step E · Session log cleanup

After cleanup is complete, print a summary:

✅ 会话清理完成
  已删除临时文件: N 项
  已卸载 Python 包: N 项
  已删除 Skills: N 项
  跳过/保留: N 项

Reset the in-memory session log and delete <workspace>/.workbuddy/session-track.json.

Additional Commands

跳过 command detail:

When the user says 跳过 <X>:
1. Search all arrays in session-track.json > items for entries containing <X> as a substring.
2. If exactly one match → add the full matched string to skip_list, confirm to user.
3. If multiple matches → list them and ask user which one to skip.
4. If no match → tell user "未找到匹配项" and suggest 列出临时文件 to review.

Items in skip_list are displayed with (保留) tag in the cleanup list and excluded from actual deletion/uninstall.

Safety Rules (Non-negotiable)

1. Never auto-delete files outside temp/scratch/generated paths without explicit confirmation.
2. Never delete workspace source code, project configuration, or the .workbuddy/ directory itself. Exception: session-track.json inside .workbuddy/ is a transient session file and may be deleted by the 清除记录 command or Step E cleanup.
3. Never use rm -rf or del /S /Q on home, desktop, downloads, or project roots.
4. Skills deletion is permanent — always warn before removing Skills.
5. If a deletion fails, stop and report the error. Do NOT retry with broader paths.
6. Max 10 file deletions per batch. Verify after each batch.

Bundled Resources

• scripts/cleanup.py — Command-line cleanup utility; can be run directly to remove a list of paths.
• references/cleanup-guide.md — Full reference of uninstall commands by package manager and OS.

Changelog

v1.4.0 (2026-04-17)

• Fix: track_init() shallow copy bug — nested items dict now uses copy.deepcopy() to prevent cross-session reference sharing (P2-6)
• Fix: uninstall_pip() / uninstall_npm() now pre-check whether the package is actually installed before attempting uninstall (P2-9)
• Added: Changelog section to SKILL.md (P2-8)

v1.3.0 (2026-04-16)

• Fix: Windows path safety bug — Path("/") resolving to \ on Windows, incorrectly flagging all paths as unsafe
• Fix: skip_list partial matching — added _is_skipped() helper for substring-based matching
• Fix: send_to_trash() silent hard-delete fallback — now requires allow_hard_delete=True (only set for temp paths)
• Fix: PowerShell single-quote escaping for paths with special characters
• Added: --workspace CLI argument for --manifest mode
• Added: ALLOWED_SUBDIRS list for workspace-aware safety checks (generated-images, node_modules)
• Added: Step C decision logic in SKILL.md (≤5 items → individual delete; 6+ → script; one-click → script)
• Added: Safety Rule #2 exception for session-track.json
• Added: (保留) skip marker in Step A example output
• Added: Duplicate detection rule row fix in SKILL.md table

v1.2.0 (2026-04-15)

• Initial public release with tracking and cleanup workflows
• Trash-first deletion with OS-specific implementations
• Session-track.json with skip_list support
• cleanup.py CLI utility with --init, --add, --skip-add, --show, --dry-run