session-cleanup

Session cleanup skill for Claw-family agents (OpenClaw, WorkBuddy, QClaw, etc.). This skill should be used when the user wants to track and clean up temporar...

Security Scan

The skill's files, instructions, and behavior are consistent with a session cleanup utility — it tracks temporary artifacts and removes them; nothing requested appears unrelated or excessive.

Purpose & Capability

Name/description match the included artifacts and code. The repo provides a CLI (scripts/cleanup.py), helper docs, and SKILL.md that describe tracking and removing temp files, pip/npm packages, system packages, and skills — which aligns with a 'session-cleanup' purpose.

Instruction Scope

SKILL.md asks the agent to record artifacts to a persistent <workspace>/.workbuddy/session-track.json and to perform a mandatory post-check after every tool call while tracking is active (scanning write_to_file/execute_command strings and silently appending). That behavior is consistent with tracking but is broad: it gives the skill automatic, background access to examine tool calls and record file paths without announcing each append. It does not instruct network exfiltration or reading unrelated secret env vars, but the silent, automatic nature is a privacy/behavioral concern users should be aware of.

Install Mechanism

No install spec or remote downloads; the package is instruction-only from the registry perspective and ships local Python scripts and docs. No external installers or extracted archives are fetched at install time.

Credentials

The skill requests no environment variables or credentials. The code uses standard OS utilities (PowerShell/osascript/gio/trash-put, pip, npm) and filesystem paths, which are proportionate to a cleanup tool. There are no requests for unrelated tokens or secrets.

Persistence & Privilege

always:false (normal). The skill creates a persistent tracking file in the workspace and expects autonomous post-checking after tool calls while tracking is enabled. Autonomous invocation is allowed by default (disable-model-invocation:false); that combined with mandatory, silent background updates means the skill can autonomously record session artifacts. This is expected for a cleanup skill but users should be aware that tracking occurs silently while enabled.

Assessment

This package appears to do what it says: it creates a workspace .workbuddy/session-track.json, records temporary files and installs, and can delete files and uninstall packages. Before installing or enabling: - Review scripts/cleanup.py (especially send_to_trash and uninstall paths) and run in --dry-run mode first to see what would be removed. - Understand that when tracking is enabled the skill will silently inspect tool calls and append entries to the session-track.json file — it does not transmit data externally but will record paths and package names. - Be cautious about system-wide uninstall steps (pip uninstall, apt/winget/choco/brew) since those require elevated privileges and can remove shared dependencies; the skill marks such actions as requiring confirmation in SKILL.md, but confirm prompts depend on how your agent is configured. - If you want to avoid any autonomous changes, disable autonomous invocation for this skill or only invoke it manually and use the script with --dry-run first. Overall: coherent and consistent with its described purpose; test in a safe workspace first and inspect the track file before executing cleanup.

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: "✅ 发现上一次会话的追踪记录，已恢复。"

   {
     "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:

Category	Detection signal
Temp files	write_to_file / execute_command that creates a file in a temp path (%TEMP%, /tmp, session scratch dirs, generated-images/), OR any file where the explanation contains keywords: "temporary", "demo", "test", "example", "scratch", "临时", "演示", "测试"
Pip packages	pip install, pip3 install, uv pip install
npm packages	npm install, npx ... --save
System software	winget install, choco install, apt install, brew install, scoop install
Skills	init_skill.py, use_skill, manually writing a new SKILL.md to a skills folder
Other	Any item the user explicitly asks to track

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:

       # 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	Action
列出临时文件 / show session log	Print current tracked list from session-track.json without deleting
清除记录 / clear log	Delete <workspace>/.workbuddy/session-track.json via delete_file and reset tracking state. Does NOT delete any actual files. Note: The safety rule "never delete .workbuddy/ folder" protects the directory itself, not transient session files within it — session-track.json is explicitly designed to be deleted by this command.
手动添加 <path> / add to cleanup <path>	Append a path to the relevant array in session-track.json
跳过 <path_or_name> / skip <path_or_name>	Add an item to skip_list in session-track.json, excluding it from future cleanup. Accepts partial matches (e.g. 跳过 demo_script.py matches the full path). Confirm to user: "✅ 已标记保留: <item>"

跳过 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