Repository navigation
Let AI agents drive DiskHound over a local MCP server - #71
Merged
tzarebczan merged 3 commits intoOct 14, 2026
Merged
Conversation
huntharo
force-pushed
the
codex/diskhound-mcp-patterns-5e1b95
branch
from
October 13, 2026 03:35
880eb40 to
232797d
Compare
huntharo
marked this pull request as ready for review
October 14, 2026 01:27
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Settings → AI Agents turns on a loopback-only MCP server (http://127.0.0.1:51733/mcp) so Claude Code, Codex, or any MCP client can read scans, run scans, and steer the window while it helps the user free up space. The window follows the agent, and a header pill plus a Settings feed show what each agent did. - OAuth 2.1 with dynamic client registration, PKCE, and a resource indicator. Approval happens only in a native DiskHound window, where the user names the session and picks a role (Disk Explorer, Cleanup Guide, Cleanup Operator). Tokens are stored hashed; every tool call re-reads the policy, so revokes and role changes apply on the next call. - Host, peer, and Origin checks block DNS rebinding and cross-site requests. The SDK and Express load from their own bundle only when the feature is first turned on. - 15 tools with MCP annotations and structured results. The only destructive one asks the user to move items to the Trash / Recycle Bin in a native dialog; paths are resolved on disk before the protected-folder check, and home, standard folders, drive roots, and DiskHound itself are refused. - Scan comparisons carry the Changes tab's caveats when two scans counted sizes, hardlinks, or the macOS Data volume differently, so an agent doesn't read an accounting change as freed space. - Two cleanup skills (free up space, investigate growth) served as SEP-2640 skill:// resources plus prompt fallbacks, with per-OS notes on space deleting doesn't free: APFS clones and Time Machine local snapshots, shadow copies and .vhdx disks, hardlinks and btrfs/ZFS snapshots. - The Folders tab now marks trashed folders until the next scan. Protected folders from Settings apply to agents too: they are checked on the requested path, the resolved path, and again after the user confirms, since Settings can change while the dialog is open. Folder listings report the real folder count when the result is capped, and duplicate groups report what removing each copy frees, clones and hardlinks included. Three E2E specs drive the built app the way Claude Code does: register, /authorize, the real approval window, then MCP tool calls. They cover the window following an agent, the Operator-only Trash with the user's Cancel and Move, the home-folder refusal, Deny, restart, and Revoke. DISKHOUND_AGENT_PORT moves the server off 51733, and the fixture gives each launch a free port, so a run never collides with a DiskHound the developer has open. The Trash confirmation and shell.trashItem are stubbed in main, as the folder picker already is. Session and token saves, the activity feed and tool calls have I/O budgets, and the tool handlers have operation-count scaling tests. Docs: docs/mcp.md.
diskhound-mcp is a small Rust helper shipped in resources/native. A client that only launches stdio servers runs it with no arguments; it bridges stdio to DiskHound's loopback HTTP endpoint, signs in with OAuth on the client's behalf, and keeps the token in the OS credential store, so later launches reuse the user's approval. DiskHound still owns consent and the tools. CI builds and tests it on all three OSes, and the release workflow builds it per target (a universal binary on macOS) for electron-builder to pick up. Its token and lock-file writes have an I/O budget, and an E2E spec drives it against the built app.
Finding it: the header gets an agent button that is always there. Its popover explains the feature when agents are off and lists sessions, waiting sign-ins and blocked requests when they are on. After an agent acts, the button becomes a pill naming it. The drive picker and the app and tray menus link to Settings too. Connecting: Settings → AI Agents leads with a prompt to paste into any agent, which adds DiskHound to its own configuration. DiskHound never writes another app's config. A tab per client (Claude Code, Claude Desktop, Codex, others) has that client's prompt, the command behind a Show button, a Turn on button when agents are off, and a last step that shows the connection live. Claude Desktop's chat can't run commands, so Add to Claude builds an MCP Bundle (.mcpb) from DiskHound's own helper and opens it in Claude, which asks the user to install it. Claude Desktop isn't offered on Linux. Approving: the sheet sits over the main window and names the client and transport. Role cards show each permission; a role above the default says what it adds, in red for permanent delete, and scrolls into view. Requests wait in line, a client that stopped waiting is marked, and a reloaded authorize URL reuses its request. Managing: sessions show the client, transport, permission chips, last action and blocked count. Role changes apply on the next call; the stdio helper announces the new tool list itself. Removing files: Cleanup Operator can ask for the Trash, and the new Cleanup Admin role can ask for a permanent delete. The user confirms every request. A session sees only the tools its role grants. Calling another is refused before it runs, logged to agent-security.log (capped and throttled; see the I/O budgets) and shown in Settings. The stdio helper answers initialize at once, names the client (Claude Desktop, Claude Code, Codex), asks the user only on a tool call or once the client stays connected, and withdraws its request if the client hangs up, so health checks never open a sheet. Each client saves its own approval, so approving one never lets another in. Claude Desktop keeps the tool list it got when it connected, so the helper holds that first list (up to 45 s) until the user decides, and diskhound_status tells it how to reload a list that went stale. Agent text and confirm dialogs use the app's size units. The server moves to port 51735. Answering: Claude Desktop passes an extension's tools on to its chats and Code sessions, but not its resources, so diskhound_read_skill serves the skills as a tool too. diskhound_dev_artifacts says what removing each tree frees once APFS clones are counted, and gives a range for removing the listed trees together. Measuring: diskhound_measure_removal tells an agent what removing a set of files and folders frees, measured on disk now, so it never has to read the index or call getattrlist itself. The scanner's new measure-removal mode walks the paths, reads metadata only, and counts each APFS clone group and hardlinked file once. Their blocks come back only when every clone or name is in the set, including copies outside it and outside any scan. A rewritten clone's shared part is reported as uncertain. The tool returns the set's total and what each path frees alone. The call blocks until the walk is done. If the client stops waiting first, the walk finishes anyway, and the same call made within 5 minutes gets that result without another walk. Windows scans already count each file once, so the tool isn't offered there.
huntharo
force-pushed
the
codex/diskhound-mcp-patterns-5e1b95
branch
from
October 14, 2026 17:25
232797d to
de9cdaf
Compare
Owner
|
Merging as is for now, and we can polish up next! Thanks again for this @huntharo, everyone will love it! |
This was referenced Oct 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fork PR: huntharo#5. It has the full test notes and more screenshots.
Summary
DiskHound can now run a local MCP server, so an AI agent such as Claude Code, Claude Desktop or Codex can help the user find where space went. The agent reads scans, runs scans, and moves the DiskHound window to whatever it is looking at, so the user follows the investigation in the app instead of reading paths in a terminal. It is off by default.
This is a draft because the flow for removing files isn't final (see Not done yet). Everything else is ready for review.
Server. It is loopback only, at
http://127.0.0.1:51735/mcp. The agent signs in with OAuth 2.1: dynamic client registration, PKCE and a resource indicator. The user approves each agent in a sheet over DiskHound's main window. The browser never approves anything.Roles. There are four:
A session lists only the tools its role grants. A call to any other tool is refused before it runs, logged to
agent-security.log, and shown in the app. Role changes and revokes apply on the agent's next call.Clients.
diskhound-mcp, a small bundled Rust stdio helper that signs in on its behalf and keeps the token in the OS credential store..mcpb) from that same helper, and Claude installs it.Finding and managing it.
Tools. There are 18 (17 on Windows), with MCP annotations and structured results. They cover drives and scans, folders, search, cleanup suggestions, duplicates, Dev Artifacts, history and comparisons, and steering the window.
diskhound_measure_removalmeasures on disk what removing a set of paths frees. It counts APFS clone groups and hardlinks once, including copies outside the set. It uses a new--mode=measure-removalin the native scanner and isn't offered on Windows.Skills. Two cleanup procedures ("free up space" and "investigate growth") ship as MCP skill resources, with prompt and tool fallbacks for clients that don't read resources. They cover space that deleting files doesn't free:
.vhdxdisks;User docs are in
docs/mcp.md.Commits
native/diskhound-mcpcrate, plus the CI and release steps that build it.diskhound_measure_removal, and the per-client approvals in the helper.Not done yet
diskhound_status.diskhound_statusand the role toast say so.tools/list_changed, so Claude Code updates at once.diskhound-mcpsomewhere stable first.Needs more testing
claude mcp listnever opens a sheet.software_idany client can send.lipointo a universal binary on macOS.claude -pruns weren't available on the test machine. Its sign-in andclaude mcp listwere tested for real, and its tool calls only through the helper with Claude Code'sclientInfo.Risks
Size.
Cargo.lockfor the new crate.@modelcontextprotocol/sdk1.30,express5 andzod4. They are bundled separately, indist-electron/mcp/agentRuntime.cjs(about 100 KB), which loads only when agents are first turned on.Destructive tools. A permanent delete can't be undone. The guards:
Not guarded yet: a permanent delete doesn't stop at a volume mounted inside the folder, so it would delete into that volume too. The review list's mount check closes this.
The review list will change this flow.
Local attack surface.
Hostexactly127.0.0.1:<port>and a loopbackOrigin. That blocks DNS rebinding and cross-site requests.SDK workaround. SDK 1.30 rejects a
tools/callwithoutarguments, which the spec allows and rmcp clients send, so the HTTP layer defaults it to{}. A test pins this, so the shim can go after an SDK upgrade.Disk writes. Every per-event write has an I/O budget in
src/test/io-budgets.json. The security log is throttled: at most 288 appends and about 0.5 MB in a day of nonstop refusals.Testing
diskhound_measure_removalover clones (macOS) or hardlinks (Linux).claude mcp list.Screenshots
Header button, popover and drive picker link:
Connect guide:
Approval sheet, with Cleanup Admin picked:
Sessions:
Blocked requests and recent actions: