Repository navigation
feat(mcp): let an AI agent drive PwrDisk over MCP, with embedded skills (port of tobi/disktree#102) - #14
Merged
Conversation
`disktree mcp` serves the Model Context Protocol over stdio, so Claude Code, Codex or any MCP client can scan, walk the tree and mark what can go, and the person removes it on the review screen. One command connects it and there is nothing to configure, sign in to or approve: the agent runs disktree as the user, and can do no more than the user's shell can. Eight tools: status, scan, ls, find, show, mark, unmark and review. Each mark answers with the real 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. There is no tool that deletes. A window follows along over a per-user socket (disktree-link): marks land in the mosaic and the meter, `show` moves the view, `review` opens the review screen, and the top bar names the agent and its last action while it is connected. When no window is open the agent can start one. Without a display it works headless. Windows is headless for now; the link needs a named pipe there. The free-space procedure ships as a prompt and a resource from skills/disktree-free-space/SKILL.md.
When a disktree window is open it is now the agent's source of truth. disktree_ls, disktree_find and disktree_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 server's own scans are read only while no window is open, so an agent in a terminal still needs nothing else. The listing and search logic moves into disktree-core (query) so both sides answer alike; the link gains Scan, Ls and Find requests, a Marked answer that says what the window refused, and a tree summary with the panel's findings in every State. The window applies the agent's scan options, and a scan it is asked for lands as any other.
The line under the disk meter is easy to miss; Help is where a person looks for how to hook something up. One item, the same overlay.
…H and Windows guards The server now carries its own skills, compiled in from skills/: pwrdisk-explain-usage (read-only: never marks) and pwrdisk-free-space (agree the list with the user before marking unless a standing instruction covers it; never delete by other means), with macOS, Linux and Windows references for what each system hides from a scan and what never to propose. They are served as skill:// resources, through the io.modelcontextprotocol/skills extension's skills/list and skills/get, and as the prompts free-space and explain-usage, which add this system's reference. pwrdisk_status names the system and its reference. What a person or agent sees is PwrDisk: `pwrdisk mcp`, the pwrdisk_* tools, the server name, and the link socket (pwrdisk.sock, PWRDISK_LINK), so a PwrDisk agent never drives an upstream disktree window on the same machine. A window showing an SSH host answers only hello and state, and the session works headless and says why: an agent's paths are this computer's. On Windows, where there is no window link yet, show and review no longer start a window that can never answer; they say how the user takes the list over. The review message names the trash in use, or says removal is permanent where there is none. skills/ now runs full CI: the server compiles those files in.
A client may call a tool as soon as initialize is answered, before the initialized notification arrives; the window then took its name from the first hello as "an agent". Record the name while answering initialize.
…, versions - An agent's scan, mark or show leaves a window still on the source chooser and scans the root it names; start_scan only reopened the chooser, so the agent waited on a scan that never started. A window with no root no longer counts as covering every path. - A window that answers hello with an error (another link version) or refuses the marks made before it linked is not followed. One reason, `unlinked`, replaces the SSH-only field; the marks stay in the session and the agent is told why, instead of losing them silently. - pwrdisk_ls keeps its listing when show: true cannot reach a window. - pwrdisk_find with no path skips a scan nested inside another held scan instead of counting its entries twice. - The window's suggested first prompt asks for a proposal, not a standing instruction to mark. - skills/ is checked out with LF everywhere, so frontmatter and digests do not change under Git for Windows' autocrlf.
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.
Ports the MCP server from huntharo#7 (upstream tobi#102) onto PwrDisk and makes it ready to ship: embedded skills with each platform's cautions and confirm-first rules, PwrDisk naming throughout, and guards for SSH windows and Windows.
The first five commits are the original ones, with authorship kept. Their conflicts with PwrDisk's main were resolved: custom window chrome, the Updates panel, and the FSEvents/Spotlight categories. The last two commits are new.
What users get
pwrdisk mcpis an MCP server over stdio, with no port, token or sign-in. An agent such as Claude Code or Codex scans, walks the tree largest first, finds caches and build output, and marks what can go. It cannot delete anything:pwrdisk_reviewopens the review screen, and the person presses Enter. When a PwrDisk window is open, the agent reads that window's tree, its marks show up live, and the header names the agent.Embedded skills
Compiled in from
skills/and served three ways: asskill://resources, through theio.modelcontextprotocol/skillsextension (skills/list,skills/get, with sha256 digests, following PwrSuiteLab Control's contract), and as the promptsfree-spaceandexplain-usage, which add the reference for the system the server runs on.pwrdisk-explain-usagepwrdisk-free-spacesudo, no Full Disk Access, no system-setting changes; Trash frees nothing until emptiedreferences/macos.mdreferences/linux.mdreferences/windows.mdpwrdisk_statusnames the system and the reference to read before marking. The server instructions carry the confirm-first rules too, for clients that never open a skill.Fixes found while getting it ready
helloandstate. The session works headless and says why.showandreviewstarted a window that could never link, then started another on every retry. They now say how the user takes the list over.pwrdisk.sock(orPWRDISK_LINK), so PwrDisk's agent never drives an upstream disktree window on the same machine.initializedarrived. The name is now recorded duringinitialize.skills/**now runs full CI, since the server compiles those files in.Screenshots
pwrdiskon a contrived tree on a 600 MB disk image named Fixtures, macOS 27. For the after shots, a scripted MCP client namedclaude-codemarked two directories. The binary ran from/tmp/PwrDisk.appso no real paths appear.Before (main)
After: an agent connected, two marks
After: Help › Work with an AI Agent…
Verification
cargo xtask lintandcargo xtask testpass on macOS. New tests: the skills catalog (frontmatter, everyskill://link resolves, exact-match reads only, digests), theskills/list/skills/get/resources contract, refusing an SSH window on both the session and window sides, and the Windowsshow/reviewpath.node --test scripts/ci/classify-changes.test.cjspasses.initialize(extension declared),tools/list,resources/list/read(traversal refused),skills/list/get,prompts/getandpwrdisk_status.