Introduction¶

In daily use of DSH, developers often face three types of local states: whether the local toolchain is available, whether temporary directories left by agent runs can be deleted, and whether changes to machine rules AGENTS.md have been backed up. Manually checking tools, browsing directories, and modifying rule files are possible, but there is a lack of a unified entry point, and accidental deletion is easy.

guo6x/dsh-housekeeper is a DSH web profile plugin that consolidates these tasks into the Web GUI Settings → Plugins → Environment Steward: toolchain inventory, cache candidate scanning, two-step cleanup, and AGENTS.md editing and backup. Below is an introduction to it following the “Check First, Plan Second, Confirm Last” approach.

What is This¶

Core Capabilities¶

The following introduces three capabilities: read-only inventory, controlled cleanup, and machine rule editing.

1. Toolchain Inventory¶

The plugin automatically detects the location and version of the following tools:

node
pnpm
git
gh
ffmpeg
Edge
Chrome

This step only produces a report; it does not create a cleanup plan, delete files, or modify machine rules.

2. Cache Scanning¶

After scanning .tmp and cache directories, the panel displays information about candidate directories:

• Size
• File count
• mtime
• 4000 file truncation marker
• Highlighted if not touched for 30 days
• Click to expand content preview

The scan has a 4000-file limit; if a directory has many files, do not treat the list as a complete inventory when you see the truncation marker.

3. Two-Step Cleanup¶

First, select the temporary directories you recognize, then generate a cleanup plan. The plan will list approved paths and rejected paths. Files will not be deleted before confirmation; after confirmation, deletion is executed, checking the whitelist and realpath again before deletion.

Whitelist rules:

• Only allow deletion of project .tmp directories and direct children of cache-root
• Reject .. escape
• Reject symbolic link escape
• Reject system paths
• Check realpath again before deletion

Cleanup confirmation token:

• One-time
• Expires in five minutes
• Used by the housekeeper_clean tool to execute cleanup

4. AGENTS.md Editing¶

The plugin can read and edit the machine rule file AGENTS.md. It automatically backs up the previous version upon saving and supports one-click recovery.

Verified materials state: the rule endpoint only reads and writes $DSH_HOME/AGENTS.md; the path is fixed with a 64KB limit. Another occurrence of ~/.dsh/AGENTS.md appears in the materials, but the equivalence is not explained, so this article does not treat it as the definitive path.

5. Agent Tools¶

The plugin provides three tools:

Installation and Activation¶

Installation from GitHub¶

dsh plugin --profile web add github:guo6x/dsh-housekeeper

After installation, restart the running dsh web process, then open:

Settings → Plugins → Environment Steward

Seeing the Toolchain inventory section indicates completion.

Check if Plugin is Installed¶

dsh plugin --profile web list dsh-housekeeper

Local Development Installation¶

Run in the repository directory:

dsh plugin --profile web add .

Typical Usage¶

Perform Read-Only Inventory First¶

First, open the panel and perform a round of checks that do not modify the system:

1. View the location and version of detected node, pnpm, git, gh, ffmpeg, Edge, and Chrome.
2. View .tmp and cache directory candidates.
3. Click a row to preview content.
4. Do not select directories, do not generate plans, and do not delete files.

If using an Agent for the same verification, you can request:

Run housekeeper_report, summarize detected toolchains and max cache candidates; do not create a cleanup plan, do not delete files, and do not modify machine rules.

Perform Cleanup Plan Next¶

When you confirm that certain temporary directories can be cleaned up:

1. Only select temporary directories you recognize.
2. Select to generate a cleanup plan.
3. Read the approved paths and rejected paths.
4. Use the one-time confirmation operation corresponding to the plan to execute deletion.

The corresponding Agent workflow is:

1. First request housekeeper_report.
2. Then request and review housekeeper_plan.
3. Only after confirming there are no errors should you be allowed to use the returned one-time token to call housekeeper_clean.

Edit Machine Rules Last¶

Modify AGENTS.md in the panel; the previous version will be automatically backed up upon saving. If you make a mistake, you can recover with one click. Note that this endpoint has a 64KB limit.

Configuration¶

Scan roots have default values based on the platform. Verified materials provide Windows default values:

D:\github
D:\environment\cache

These scan roots can be edited in the panel and overridden via environment variables. This article does not list default values for other platforms because the verified facts do not provide them.

Suitable Scenarios and Notes¶

Suitable for:

• Need to check local toolchain location and version in DSH web profile
• Need to clean up .tmp and cache directories left by agent runs, but prefer to review the plan before deleting
• Need to edit AGENTS.md and retain a backup of the previous version

Notes:

• The plugin runs with the permissions of the current dsh process; check source code, license, and local permissions before installing.
• Verified facts state: no account, API key, or additional service needed; routes only accept loopback clients; no telemetry, no external network calls.
• Cleanup whitelist only covers project .tmp directories and direct children of cache-root; system paths, .. escape, and symbolic link escape will be rejected.
• Cleanup token is one-time and expires in five minutes.
• Scanning has a 4000-file limit; truncated directories cannot be directly treated as a complete inventory.
• AGENTS.md has a 64KB limit; verified materials show both $DSH_HOME/AGENTS.md and ~/.dsh/AGENTS.md forms, but do not explain the equivalence, please verify your local environment before use.

Links¶

• GitHub: https://github.com/guo6x/dsh-housekeeper
• The directory page URL is not provided in the verified materials, so it is not listed here.