Let an AI agent drive disktree over MCP

AGENTS.md

@@ -10,6 +10,12 @@ remove it — with the volume's free space live on screen the whole time. Two
 phases: explore (treemap, breadcrumbs, the selection and status lines) and review (the marked list,
 the removal mode, the confirmation). Marking is never destructive.
 
+`disktree mcp` is the same thing for an AI agent: an MCP server over stdio
+that scans with `disktree-core`, marks, and opens the review screen in a
+window over a per-user socket (`disktree-link`). The agent marks; the
+person removes. There is no tool that deletes, and the link has no request
+that deletes.
+
 ## Commands
 
 ```sh
@@ -106,6 +112,19 @@ and `cargo build --release` directly; CI runs the gate on both systems.
    the tree, which `-X` and the media exception allow, is reported and never
    added to this volume's free space; see `space::attribution`. The final number
    comes from `statvfs` before and after.
+10. **An agent marks; a person removes.** `disktree mcp` has no tool that
+    deletes, and the window link has no request that does. `review` only
+    opens the review screen. When a window is linked it is the agent's
+    source of truth: `ls`, `find` and `scan` are answered from its tree,
+    a mark is measured from it, and its marks are the marks — every link
+    answer carries them, and the MCP session replaces its own with what
+    the window says. The session's own scans are read only while no
+    window is open. The listing and search logic is `core::query`, shared
+    by both sides, so they answer alike.
+11. **The link is a same-user socket, nothing more.** `disktree-link`
+    binds `0600` in a per-user directory and has no token, because the
+    agent already runs as the user and `disktree mcp` scans on its own.
+    Do not add a port.
 
 ## Where changes belong
 
@@ -124,6 +143,10 @@ and `cargo build --release` directly; CI runs the gate on both systems.
 | the mosaic's painting or labels | `crates/disktree-app/src/treemap_view.rs` |
 | layout of a screen | `crates/disktree-app/src/views.rs` |
 | colours derived from the theme | `crates/disktree-app/src/palette.rs` |
+| what an agent can ask of the window, and the answer | `crates/disktree-link/src/lib.rs` (messages), `crates/disktree-app/src/agent.rs` (handling) |
+| a tool, its parameters or its wording | `crates/disktree-mcp/src/server.rs` (the MCP surface), `crates/disktree-mcp/src/session.rs` (what it does) |
+| how a listing or a plan reads to an agent | `crates/disktree-mcp/src/report.rs` |
+| the procedure an agent follows | `skills/disktree-free-space/SKILL.md` |
 
 ## Verification expectations
 
@@ -132,6 +155,10 @@ and `cargo build --release` directly; CI runs the gate on both systems.
   against real temporary trees.
 * The screens are covered by window-harness tests that draw frames and press
   keys, including one that marks a directory, confirms the removal and checks
-  the files are gone while unmarked neighbours are untouched.
+  the files are gone while unmarked neighbours are untouched, and one that
+  drives the window over the real socket as `disktree mcp` does.
+* `disktree-mcp` tests every tool as a function against a temporary tree,
+  with a stand-in window on the socket for the linked cases;
+  `disktree-link` tests the socket itself.
 * Rendering was verified by those tests and by running the app against a real
   home directory; it has not been eyeballed in every theme and font size.

Cargo.toml

@@ -1,6 +1,12 @@
 [workspace]
 resolver = "3"
-members = ["crates/disktree-app", "crates/disktree-core", "xtask"]
+members = [
+    "crates/disktree-app",
+    "crates/disktree-core",
+    "crates/disktree-link",
+    "crates/disktree-mcp",
+    "xtask",
+]
 
 [workspace.package]
 version = "0.11.0"
@@ -11,6 +17,8 @@ repository = "https://github.com/tobi/disktree"
 
 [workspace.dependencies]
 disktree-core = { path = "crates/disktree-core" }
+disktree-link = { path = "crates/disktree-link" }
+disktree-mcp = { path = "crates/disktree-mcp" }
 anyhow = "1"
 rayon = "1"
 rustc-hash = "2"

README.md

@@ -131,6 +131,7 @@ disktree            # scan the home directory
 disktree --disk     # the whole disk it lives on
 disktree ~/src      # or any directory
 disktree --help     # options: apparent size, follow links, skip hidden, …
+disktree mcp        # serve an AI agent over stdio; see "With an AI agent"
 ```
 
 ### The screen
@@ -246,6 +247,53 @@ first (git work that exists nowhere else, a tool's own clean command) and
 touching nothing else. A name holding a newline is left out of the list and
 escaped in the prompt, so it cannot pass for another path.
 
+## With an AI agent
+
+disktree is also an [MCP](https://modelcontextprotocol.io) server, so an
+agent such as Claude Code or Codex can do the looking while you keep the
+deciding. One command connects it, and there is nothing to configure, sign
+in to or approve: the agent runs `disktree mcp` as you, over stdio, and can
+do no more than your shell can.
+
+```sh
+claude mcp add --scope user disktree -- disktree mcp
+```
+
+(Codex: `codex mcp add disktree -- disktree mcp`. Any other client: a
+server named `disktree` with the command `disktree` and the argument
+`mcp`. The window's **Work with an AI agent** line, under the disk, and
+**Help › Work with an AI Agent…** on macOS, show each command with the
+binary's full path and a Copy button.)
+
+Then ask it what is eating your disk. The agent walks the tree largest
+first, lists every cache, build directory and package store at once, and
+marks what can go. Marking is all it can do: `disktree_review` opens
+disktree's review screen, and you press Enter there. There is no tool that
+deletes.
+
+When a disktree window is open, its tree is what the agent reads. `ls`,
+`find` and `scan` are answered from the mosaic on screen, a mark is
+measured from it, and the two of you see the same numbers. The agent's
+marks appear in the mosaic and in the free-space meter as it makes them,
+`show` moves the view to what it is looking at, a scan it asks for runs in
+the window, and the header names the agent and its last action while it is
+connected. With no window open the agent scans on its own, in seconds for a
+home directory, and can open a window for the review. Without a display it
+works headless and says so.
+
+The tools: `disktree_status`, `disktree_scan`, `disktree_ls`,
+`disktree_find`, `disktree_show`, `disktree_mark`, `disktree_unmark` and
+`disktree_review`. Each `mark` answers with the real plan: what the guards
+below keep back and why, what another mark already covers, and the free
+space it gives back on the volume, counted the way the meter counts it.
+The prompt `free-space` (in Claude Code, `/mcp__disktree__free-space`) and
+the resource `disktree://skills/free-space` carry the procedure the agent
+should follow, from `skills/disktree-free-space/SKILL.md`.
+
+The window listens on a socket only you can reach: `$XDG_RUNTIME_DIR` or
+`$TMPDIR`, or `DISKTREE_LINK` to choose. On Windows the agent works
+headless for now; the window link needs a named pipe there.
+
 ## What it measures
 
 - **Disk usage** by default: `st_blocks × 512`, the number `du` reports and the
@@ -401,6 +449,9 @@ gone while their neighbours are not.
 | path | what lives there |
 | --- | --- |
 | `crates/disktree-core` | scanning, the tree, the squarified layout, free space and removal — no UI |
+| `crates/disktree-mcp` | `disktree mcp`: the agent's tools over stdio, on `disktree-core` |
+| `crates/disktree-link` | the socket between a window and an agent, and its messages |
+| `skills/` | the free-space procedure the MCP server hands an agent |
 | `crates/disktree-app/src/state.rs` | every action the interface can take, and the key map |
 | `crates/disktree-app/src/views.rs` | the screens |
 | `crates/disktree-app/src/treemap_view.rs` | painting the mosaic and its labels |

crates/disktree-app/Cargo.toml

@@ -17,6 +17,8 @@ workspace = true
 gpui-kit = { version = "=0.6.6", default-features = false, features = ["assets"] }
 gpui-omarchy = "0.1.3"
 disktree-core = { workspace = true }
+disktree-link = { workspace = true }
+disktree-mcp = { workspace = true }
 anyhow = { workspace = true }
 dunce = "1.0.5"
 rustc-hash = { workspace = true }