Let an AI agent drive disktree over MCP

[huntharo]

disktree mcp turns disktree into an MCP server, so an AI agent can find what is eating a disk and mark it, while the person removes it on the review screen. One command connects it:

claude mcp add --scope user disktree -- disktree mcp

(Codex: codex mcp add disktree -- disktree mcp.) The window's Work with an AI agent line under the disk meter, and Help › Work with an AI Agent…, show the commands with the binary's full path and a Copy button.

In practice

Claude Code, asked "what is eating my disk?" against a live window. It scanned the home directory, noticed 900 GiB of the volume was outside it, scanned the whole volume, and marked a conservative set: dev-tool caches, stale build output, long-idle node_modules. The review screen in the window is where the person decides.

What it left out, with the reasoning and the command to use instead where one exists:

What the agent gets

Eight tools over stdio: disktree_status, disktree_scan, disktree_ls, disktree_find, disktree_show, disktree_mark, disktree_unmark, disktree_review. A free-space prompt and a disktree://skills/free-space resource carry the procedure (skills/disktree-free-space/SKILL.md). Answers are short aligned tables with the share bar, size, kind of data, whether the space can be had back and why, and the age, so a listing costs few tokens.

There is no tool that deletes. disktree_mark returns the real plan from removal::plan: what the guards keep back and why, what another mark covers, and the free space it gives back on the volume, counted the way the meter counts it. disktree_review opens the review screen, and the person presses Enter there.

The window follows, and is the source of truth

When a disktree window is open, it is what the agent reads. ls, find and scan are answered from the tree on screen, a mark is measured from it, and a path outside its root is an error that tells the agent to scan from higher up, which the window follows. The agent's marks appear in the mosaic and the free-space meter as it makes them, show moves the view, and the header names the agent and its last action while it is connected. Marks made before a window opened are handed over when one does.

With no window the server scans on its own, so an agent in a terminal needs nothing else, and it can open a window for the review.

The link is a per-user Unix socket ($XDG_RUNTIME_DIR or $TMPDIR, DISKTREE_LINK to override), 0600, one JSON line per request. No token, no port: it is the same trust boundary the shell has, and nothing over it deletes. On Windows the agent works headless for now; the link needs a named pipe there.

Layout

• crates/disktree-core/src/query.rs: listing and search, shared by both sides so they answer alike. Category::name/named, Finding::describe, Node::descend.
• crates/disktree-link: the messages and the socket.
• crates/disktree-mcp: the MCP surface (rmcp), the session, and how a listing or plan reads.
• crates/disktree-app/src/agent.rs: the window's end of the link. views.rs: the header pill, the line under the disk, the overlay.
• AGENTS.md invariants 10 and 11 record the rules: an agent marks, a person removes; the link is a same-user socket, nothing more.

Verification

• cargo xtask lint green on macOS; the link and MCP crates pass clippy for x86_64-pc-windows-msvc too.
• 73 app, 149 core, 6 link, 11 mcp tests. The window-harness test drives the window over the real socket as disktree mcp does: hello, mark (measured from the tree, a missing path refused), ls, find, show, scan, review, unmark, hang up. The mcp tests run every tool as a function against a temporary tree, with a stand-in window on the socket for the linked cases.
• Driven end to end over JSON-RPC against a real window on a fixture, and against a home-directory scan.