Repository navigation
Let AI agents drive DiskHound over a local MCP server - #5
Merged
Merged
Conversation
huntharo
force-pushed
the
codex/diskhound-mcp-patterns-5e1b95
branch
14 times, most recently
from
October 1, 2026 16:17
5069e2b to
b8c892a
Compare
huntharo
force-pushed
the
codex/diskhound-mcp-patterns-5e1b95
branch
2 times, most recently
from
October 13, 2026 03:21
2b9e6e4 to
880eb40
Compare
huntharo
force-pushed
the
codex/diskhound-mcp-patterns-5e1b95
branch
from
October 13, 2026 03:35
880eb40 to
232797d
Compare
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
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.
Upstream PR: tzarebczan#71 (draft)
Summary
DiskHound can now act as a local MCP server, so an AI agent such as Claude Code, Claude Desktop, or Codex can work alongside the user to find where space went. The agent reads scans, runs scans, and moves the DiskHound window to whatever it is looking at, so the user watches the investigation in the app instead of reading paths in a terminal.
http://127.0.0.1:51735/mcp. The old port, 51733, is PwrSuiteLab Control's.agent-security.log, and shown in the app.diskhound_read_skilltool for clients that pass on only tools (Claude Desktop). They cover space that deleting files doesn't free: APFS clones and Time Machine local snapshots on macOS, shadow copies and.vhdxdisks on Windows, and hardlinks and btrfs/ZFS snapshots on Linux.diskhound_measure_removalmeasures what removing a set of files and folders together frees, on disk now. It counts APFS clones and hardlinks once, including copies outside the set and outside any scan. The call blocks until the walk is done. If the client stops waiting first, DiskHound finishes the walk and answers the same call from memory for 5 minutes. Not offered on Windows.User docs are in
docs/mcp.md. The design review (numbered turns, as-built specimens, options, a prototype and the build list) is in the Claude Design project as "AI Agents (MCP) - Connect & Manage".Finding it
The header's agent button is always there. With agents off, its popover explains the feature and offers Set up…. The drive picker adds "Using Claude or Codex? Connect an AI agent ›". The app menu has Connect an AI Agent… and the tray has AI Agents….
With agents on, a green dot means DiskHound is listening, and an amber badge counts sign-ins waiting for the user. For ten minutes after an agent acts, the button becomes a pill naming it: blue while it works, red when a call failed or was blocked. In windows 1,100 px wide or less, the pill shows only its dot; the name stays in its tooltip. The popover lists each session, its last action and role, waiting sign-ins with Review, and blocked requests today.
Connecting
Set up… lands on the connect guide. With agents off, its last step has a Turn on button, since the toggle is scrolled out of view. The last step then waits live and shows the connection as soon as the agent signs in. Tabs get a green dot for clients that are connected. The guide folds away once something is connected.
The prompts follow PwrSuiteLab's wording: "Add diskhound to my Claude Code user configuration using the stdio executable "…", with no arguments. Preserve my other MCP servers, then help me connect and approve access in DiskHound." Codex's and other clients' prompts use the HTTP endpoint with OAuth. DiskHound never writes another app's configuration. The CLI command is behind a Show button for doing it by hand.
Claude Desktop is different: its chat can't run a command, and
claude mcp addonly reaches Claude Code (including Code sessions in the Claude app). Claude Desktop installs local servers from MCP Bundles, so Add to Claude zips DiskHound's own helper with a manifest intoDiskHound.mcpbin temp and opens it. Claude shows its install dialog, and after Install it connects without a restart. The bundle uses the app's version, and passes--portwhen DiskHound isn't on the default. If Claude can't be opened, the tab says so and offers Show file. The extension serves the Claude app's chats and its Code sessions. Linux has no Claude Desktop, so the tab isn't shown there.Claude Desktop reads an extension's tool list once, when it connects, and keeps it. It does re-fetch the list after
tools/list_changed, but it never passes the new list on to chats. So for Claude Desktop the helper holds that firsttools/listuntil the user decides, for up to 45 s (Claude gives up on a request after 60 s), and Claude gets the tools of the granted role. If Claude still ends up with an out-of-date list (the user answered late, or changed the role),diskhound_statustells the agent to have the user turn DiskHound off and on in Claude's Settings → Extensions, and the role-change toast says the same.Each client now saves its own approval. The Keychain account is
<origin>#<client>, with a lock file per client, so approving Claude Code never lets Claude Desktop in, and one client's pending approval doesn't block another's.Approving
The sheet is attached to the main window. It names the client (the helper maps
clientInfoto Claude Desktop, Claude Code or Codex; Claude Desktop sendsclaude-ai, orlocal-agent-mode-<extension>from an extension) and the transport. Role cards show each role's permissions as chips, with destructive ones in red.Picking a role above the default says what it adds, in red for permanent delete, and scrolls that note into view above the buttons. If several requests arrive, they wait in line. A request whose client stopped waiting is marked, and only Deny is left. Loading the same authorize URL twice (Codex opens it in the browser and prints it too) reuses the request instead of queuing a second one.
Managing and revoking
Each session in Settings → AI Agents shows its client, transport, approval age, permission chips, last action and blocked count. From there the user can change the role, revoke the session, or forget revoked sessions. After a role change, the stdio helper sees the new permissions on its next call and sends
tools/list_changed. An HTTP client picks up the change when it reconnects.Removing files, and what happens when an agent isn't allowed to
diskhound_move_to_trashdiskhound_move_to_trash,diskhound_delete_permanentlyBoth removal tools show a native confirmation that lists every item and its size. Cancel is the default button. Protected folders, drive roots, the home folder and its standard folders, and DiskHound itself are always refused, and the dialog says what it left out.
A tool the role doesn't grant is missing from the session's
tools/list. A call to it anyway (a stale list, or a guess) is refused before any tool runs:The user sees a red pill and a notification, and the attempt is listed under Blocked requests and Recent agent actions.
Refusals are kept in
agent-security.log(NDJSON, 0600), which Show file reveals. Identical refusals within a minute are counted instead of repeated. At most 60 lines an hour reach disk; after the first append, appends are at least 5 minutes apart; and the file rotates at 256 KB. An agent refused nonstop for a day therefore costs at most 288 appends and about 0.5 MB.How it works
McpServerper POST bound to that request's token. Each server registers only the tools, and theshowInApparguments, that the session's role allows.DiskHound-Capabilitieslets the stdio helper notice a role change.diskhound-mcp).initializeat once and asks for approval in the background, so a client's connect timeout can't cut the user's decision short. Until then it shows one tool,diskhound_status, which says approval is pending.claude mcp list) lists tools and hangs up, so it never opens a sheet.POST /authorize/cancel) and the sheet closes.--ephemeralsaves nothing.Hostheader must be exactly127.0.0.1:<port>, and the peer andOriginmust be loopback./mcpis POST only, bodies are capped at 256 KB, a token can have at most 16 requests pending, and errors are always JSON.dist-electron/mcp/agentRuntime.cjs. It loads only when agents are first turned on. If it fails to load, Settings shows the error with Try again; it no longer shows "Off".--mode=measure-removalwalks the given paths with dua-core and reads metadata only. On APFS it takes each file's clone id fromgetattrlistbulk, and the clone reference count and private size once per clone group. A group's shared blocks are freed only when the set removes at least as many clones as APFS counts; a hardlinked file only when every name is in the set. A clone that was rewritten after copying reports its own blocks, and the rest isuncertainBytes. Main runs one walk at a time, keeps up to 8 results for 5 minutes, and drops them after a removal.Testing
bun run typecheckis clean, and 1,161 tests pass (4 skipped). New since the last push:diskhound_measure_removal: de-duplicated paths, ranking by what each frees alone, totals and summary, the not-APFS, uncertain and missing notes, the limit, a refused drive root or relative path, and no tool on Windows; a scaling case;diskhound_read_skilllists the skills, returns a file's text (the same textresources/readserves), lists a folder, and errors on an unknown URI;diskhound_dev_artifactsreports each tree'sfreesAlone, shared bytes andsharedWithwhen APFS clones were measured, alisted.freesTogetherrange, and a path hint for unmeasured trees;.exeon Windows, a non-default port, and a missing helper;securityLog.ioBudget.test.ts: one refusal is 1 append; a 20-path burst is 1 append; an hour of a looping agent is 3 appends; loading the log is 1 read.renderer.agents.ioBudget.test.ts, on the real main process and preload: browsing the popover, tabs and links is 0 IPC and 0 reads. A blocked HTTP delete is 1 security-log append plus the crash.log line, pushed to the UI with 0 IPC. A role change or revoke is one atomic policy write each. Add to Claude reads the helper, the icon and (unpackaged)package.json, then makes 1 mkdir and 1 write of the ~0.7 MB bundle, on a click made about once per setup.cp -cclones on disk.tools/listwaits for the decision, a stale list or a role change adds the reconnect note todiskhound_status, each client gets its own lock,initializeanswers at once, listing doesn't start approval, hanging up withdraws the request, a role change triggerslist_changed, and client names. Clippy is clean.freesAlone, the nested and missing paths, and a second call in another order answered from the first walk;diskhound_read_skillreturns the cleanup skill, and the guide's last step ticks (skipped on Linux);codex mcp login diskhoundasked for all five scopes. I approved it in the sheet as Cleanup Operator.codex execthen answered "what's using the most space" throughdiskhound_statusanddiskhound_list_folder, while the window followed it to the folder.claude mcp listreports✔ Connectedwithout opening a sheet. Its headless prompt runs aren't available on this machine, so tool calls went through the helper withclientInfoclaude-code.local-agent-mode-DiskHound, which DiskHound showed raw and didn't match to the guide; that's fixed here.diskhound_status: Claude listed tools before the approval and never took the new list into chats. After a reinstall, the helper found its saved approval, and Claude announced all 16 tools, which a new Code session used. That's why the helper now holds the first list.Connected to DiskHound (16 tools). A new chat asked what's using the most space and started a scan through DiskHound.resources/readfailed with "does not support resources": Claude passes an extension's tools on, not its resources. Dev Artifacts found 1 of about 530 worktrees, and no tool says what removing a set frees. The agent read the scan index and asked APFS for clone IDs itself. The pushes since adddiskhound_read_skill, the freed-space fields anddiskhound_measure_removal; worktree detection is a follow-up.Notes
tools/callorprompts/getthat omitsarguments. The spec makes it optional, and rmcp clients leave it out, so the HTTP layer defaults it to{}. A test pins the SDK behavior, so the shim can go after an upgrade.DISKHOUND_AGENT_PORTmoves the server off 51735. The E2E fixture gives each launch a free port with it.