HyperDU for agents

Disk usage an agent can act on: which volume is short, what is large on it, and which of that can be deleted without losing anything.

What is in here

Path	Format	What it is
`plugin.json`	Agent Plugins	The bundle manifest
`mcp.json`	Agent Plugins	Declares the `hyperdu-mcp` stdio server
`skills/disk-space-triage/`	Agent Skills	The triage procedure, driving the CLI
`skills/disk-space-triage/scripts/`	—	Setup for both binaries and the MCP server

The three surfaces are independent on purpose. The MCP server runs without the plugin, and the skill drives hyperdu-cli rather than the server, so you can adopt any one of them without the other two.

Setup

Everything here needs at least one HyperDU binary, and there is no prebuilt release yet — installation builds from source, so a Rust toolchain is required.

The bundled script installs both binaries and shows you how to register the MCP server:

skills/disk-space-triage/scripts/setup-hyperdu.sh

.\skills\disk-space-triage\scripts\setup-hyperdu.ps1

Flag	Effect
(none)	Install what is missing, print the registration command
`--check`	Report what is installed, change nothing
`--register`	Install, then register with any detected client

Registration is opt-in because it rewrites an agent's configuration. Installing a binary is undone with cargo uninstall; quietly editing someone's client config is not something a setup script should do uninvited.

Doing it by hand

cargo install --git https://github.com/automationjp/HyperDiskUsage hyperdu-cli
cargo install --git https://github.com/automationjp/HyperDiskUsage hyperdu-mcp

The binary is hyperdu-cli, not hyperdu. The shorter name exists only in the deb and rpm packages, which rename it on install.

Then register the MCP server with your client:

claude mcp add --transport stdio hyperdu -- hyperdu-mcp

codex mcp add hyperdu -- hyperdu-mcp

For any other MCP client, add a stdio server whose command is hyperdu-mcp — which is exactly what mcp.json already declares.

The MCP tools

Tool	Answers
`list_volumes`	Which volume is short on space
`scan_path`	What is large inside a directory tree
`find_reclaimable`	Which of it can be rebuilt rather than lost

find_reclaimable takes unused_for_days. Pass 1 or more before proposing any deletion: a directory an in-progress build is writing to is never idle, so that filter is what keeps a suggestion from destroying a running job.

There is no delete tool, deliberately. These report; a human decides. A wrong report can be corrected, a wrong rm -rf cannot.

Using only the skill

Copy skills/disk-space-triage/ anywhere your agent looks for skills. It needs hyperdu-cli and nothing else from this directory — not the MCP server, not the plugin manifest.

Using only the MCP server

Install hyperdu-mcp, register it, and ignore the rest of this directory. Any MCP client works: the server speaks stdio and holds no state between calls.