Skip to content

Let AI agents drive DiskHound over a local MCP server - #71

Merged
tzarebczan merged 3 commits into
tzarebczan:mainfrom
huntharo:codex/diskhound-mcp-patterns-5e1b95
Oct 14, 2026
Merged

tzarebczan merged 3 commits into
tzarebczan:mainfrom
huntharo:codex/diskhound-mcp-patterns-5e1b95

Conversation

@huntharo

@huntharo huntharo commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

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:

    • Disk Explorer can only read.
    • Cleanup Guide, the default, can also run scans and steer the window.
    • Cleanup Operator can also ask to move items to the Trash.
    • Cleanup Admin can also ask for a permanent delete.

    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.

    • Codex speaks HTTP and OAuth itself.
    • Claude Code runs diskhound-mcp, a small bundled Rust stdio helper that signs in on its behalf and keeps the token in the OS credential store.
    • Claude Desktop's chat can't run a command, so Add to Claude builds an MCP Bundle (.mcpb) from that same helper, and Claude installs it.
    • DiskHound never writes another app's configuration. The setup prompts ask the agent to add DiskHound to its own configuration.
  • Finding and managing it.

    • The header has an agent button that is always there. After an agent acts, it becomes a pill naming that agent.
    • The drive picker, the app menu and the tray menu link to setup.
    • Settings → AI Agents has a tab for each client, a live connection status, sessions with role pickers, and lists of blocked requests and recent agent actions.
  • 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_removal measures 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-removal in the native scanner and isn't offered on Windows.
    • Comparisons between scans carry the same caveats as the Changes tab, so an agent doesn't mistake an accounting change for freed space.
  • 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:

    • on macOS, APFS clones and Time Machine local snapshots;
    • on Windows, shadow copies and .vhdx disks;
    • on Linux, hardlinks and btrfs/ZFS snapshots.

User docs are in docs/mcp.md.

Commits

  1. Let AI agents drive DiskHound over a local MCP server. The server, OAuth, the tools, the skills and the guards for protected folders, plus E2E specs, I/O budgets and scaling tests.
  2. Add a bundled stdio bridge for DiskHound MCP clients. The native/diskhound-mcp crate, plus the CI and release steps that build it.
  3. Make AI agents easy to find, connect, approve and manage. The UI above, the Claude Desktop extension, Cleanup Admin, diskhound_measure_removal, and the per-client approvals in the helper.

Not done yet

  1. A review list before agents' destructive actions are applied. This is the main gap, and the reason this PR is a draft.
    • Today each Trash or delete request brings DiskHound to the front with a native dialog, and Cancel is the default. The agent's call waits, with no timeout, until someone answers. The user can approve or cancel the whole request, but can't skip one item.
    • The plan, decided but not built yet:
      • Removal calls add items to a review list in DiskHound and return at once.
      • The header counts what's waiting, and the user reviews the list when they're back.
      • The user can untick items to skip them, and can turn a permanent delete into a move to the Trash.
      • DiskHound checks each item before offering the Trash: the volume has a Trash, the item fits the Recycle Bin, and no other volume is mounted inside it. So a folder is never shown as "moved to the Trash" when part of it can't go there.
      • DiskHound checks everything again on approval, and each agent sees the outcome on its next diskhound_status.
    • This also gives folders outside every scan a size. Today the dialog says "size unknown" for them.
    • I'd like it in this PR or right after it, before anyone relies on Cleanup Admin.
  2. Confirming in the agent's chat instead (MCP elicitation) is for later, as a setting. Claude Code and Codex support elicitation, but Claude Desktop doesn't. It would also need stateful HTTP sessions in DiskHound and the helper relaying the question.
  3. Tool lists can go stale after a role change.
    • The HTTP server is stateless, so Codex keeps its old tool list until it reconnects. In the meantime, calls to tools the role lost are refused and logged.
    • Claude Desktop reads an extension's tools once, when it connects. After a role change the user has to turn the extension off and on, and diskhound_status and the role toast say so.
    • The stdio helper sends tools/list_changed, so Claude Code updates at once.
  4. The Claude Desktop extension can go out of date. Claude keeps its own copy of the helper, so after a DiskHound update the user has to click Add to Claude again. Nothing flags an outdated copy yet. The bundle is also unsigned.
  5. Linux AppImage. The helper's path changes on every launch, so the steps tell the user to copy diskhound-mcp somewhere stable first.

Needs more testing

  • Sign-in and client registration, compared with PwrSnap, the app this design was ported from. Some parts are better than PwrSnap's and some are weaker. All of them deserve a closer look.
    • Better:
      • There is a real stdio path for outside agents, and each client name gets its own credential-store entry, so approving Claude Code never lets Claude Desktop in.
      • A health check such as claude mcp list never opens a sheet.
      • The request is withdrawn if the client hangs up.
      • A request is marked stale if the client stops waiting.
      • A login that loads its authorize URL twice gets one sheet.
      • Requests wait in one queue, at most 8.
      • Approved registrations survive a restart.
    • Weaker:
      • Token hashes sit in plain JSON with mode 0600. PwrSnap uses OS-encrypted storage.
      • Every unapproved registration is written to disk, up to 256, with no expiry. PwrSnap keeps them in memory until approval.
      • Redirect URIs aren't limited to loopback.
    • Shared with PwrSnap:
      • Client names are self-asserted. Any local process that runs the helper and claims to be Claude Code reuses Claude Code's saved approval, and the "stdio" badge comes from a software_id any client can send.
      • Tokens don't expire and there are no refresh tokens.
  • Windows and Linux with real clients. Hands-on testing was all on macOS. CI covers the helper and E2E on all three OSes, but nobody has signed in through Credential Manager or Secret Service by hand.
  • A signed release.
    • The release workflow's new steps haven't run yet: per-target helper builds, and lipo into a universal binary on macOS.
    • The dev helper is unsigned, so macOS asks for Keychain access after every rebuild. A signed helper should keep its Keychain access across updates, but that isn't confirmed.
  • Claude Code tool calls. Headless claude -p runs weren't available on the test machine. Its sign-in and claude mcp list were tested for real, and its tool calls only through the helper with Claude Code's clientInfo.
  • Long measurements against client timeouts. One walk of 13.3M files took 88 s, which is past Codex's default 60 s tool timeout. DiskHound finishes the walk anyway and answers the same call from memory for 5 minutes, but that hasn't been tested with Codex.

Risks

  • Size.

    • About 20k lines in 83 files, including a 2.3k-line Cargo.lock for the new crate.
    • New npm dependencies: @modelcontextprotocol/sdk 1.30, express 5 and zod 4. They are bundled separately, in dist-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:

    • only Cleanup Admin gets the tool;
    • every request needs the native confirmation;
    • protected folders, drive roots, the home folder and its standard folders, and DiskHound itself are always refused, checked on the requested path and on the resolved path, and checked again after the user confirms;
    • the dialog lists anything it left out.

    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.

    • Any local process can register and ask for approval, but only the native sheet can grant access.
    • Requests must come from loopback, with Host exactly 127.0.0.1:<port> and a loopback Origin. That blocks DNS rebinding and cross-site requests.
    • Bodies are capped at 256 KB, and each token can have at most 16 requests pending.
  • SDK workaround. SDK 1.30 rejects a tools/call without arguments, 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

  • Fork CI passed on Linux, Windows and macOS for this exact tree before the history cleanup (run). That run covered typecheck and unit tests, cross-OS vitest, Rust checks (including the helper's tests) and the Playwright E2E suite. It is running again on the cleaned-up head.
  • E2E drives the built app the way the clients do: register, authorize, the real approval sheet, then MCP calls. It covers:
    • the window following an agent;
    • the Trash for Operators only and permanent delete for Admins only, with refusals logged;
    • Deny, restart and Revoke;
    • the stdio sign-in, a role change that reloads the tool list, and a hang-up that closes the sheet;
    • Add to Claude's bundle connecting as Claude Desktop;
    • diskhound_measure_removal over clones (macOS) or hardlinks (Linux).
  • Real clients on macOS.
    • Codex 0.153.4: login, approval as Cleanup Operator, and a "what's using the most space" run that the window followed. Asked to delete permanently, Codex had no tool for it.
    • Claude Code 2.1.278: added and connected, with no sheet for claude mcp list.
    • Claude Desktop 2.16120.0: the extension installed with no restart, the user approved it, and a chat started a scan through DiskHound.
  • Measure mode on real data. On 544 Codex and Claude worktrees (13.3M files), the walk took 88 s with a peak RSS of 385 MB. The worktrees take 578 GB by size, and removing them all frees 175.7 GB. The rest is clone blocks counted more than once, and 7.1 GB stays held by package-manager caches.
Screenshots

Header button, popover and drive picker link:

Header button, popover, and drive picker link

Connect guide:

Connect guide with the setup prompts

Approval sheet, with Cleanup Admin picked:

Approval sheet with Cleanup Admin picked

Sessions:

Sessions

Blocked requests and recent actions:

Blocked requests and recent actions

@huntharo
huntharo force-pushed the codex/diskhound-mcp-patterns-5e1b95 branch from 880eb40 to 232797d Compare October 13, 2026 03:35
@huntharo
huntharo marked this pull request as ready for review October 14, 2026 01:27
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-14T01:36:17.200061Z 232797d Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

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
huntharo force-pushed the codex/diskhound-mcp-patterns-5e1b95 branch from 232797d to de9cdaf Compare October 14, 2026 17:25
@tzarebczan

Copy link
Copy Markdown
Owner

Merging as is for now, and we can polish up next! Thanks again for this @huntharo, everyone will love it!

@tzarebczan
tzarebczan merged commit 2ac189b into tzarebczan:main Oct 14, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants