drive-plume
Skill0 starsChanged 12 days agoApache-2.0View on GitHub
Drive and inspect a running debug build of Plume from an agent — read what is on screen as text, click, type, hover, and screenshot — without stealing focus or needing an Accessibility grant. Use whenever verifying a UI change, reproducing a UI bug, or checking what the app shows, before reaching for a screenshot or a process tree.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- implementSkill
- release-cycleSkill
- roadmapSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 12
Never drive the instance the user is working in.
- Very specific: line 29
When done, kill the instance by the $PID captured above — never pkill -f on the app's path, which also matches a developer's own debug …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Drive the debug app
A debug build serves a Unix-socket control server; scripts/debug/plume-control.py is the client. docs/control-server.md is the reference for the wire format, every command and the limits. This skill is the working recipe.
Launch a scratch instance
Never drive the instance the user is working in. Give the scratch instance its own PLUME_APP_SUPPORT so it has its own store, and its own socket path so the client finds it without guessing.
--env HOME=... does not isolate a scratch instance. URL.applicationSupportDirectory resolves from the process's security context, not $HOME, so an instance launched with a fake HOME still opens ~/Library/Application Support/Plume.debug* (the primary checkout's, or a worktree's Plume.debug-<worktree>) — the user's real tasks and terminals. PLUME_APP_SUPPORT is a #if DEBUG-only override built for exactly this; it redirects the whole Application Support directory (store, hooks, events, control socket) in one shot. docs/control-server.md has the reference.
APP=$(xcodebuild -scheme Plume -destination 'platform=macOS' -showBuildSettings 2>/dev/null | awk '/ BUILT_PRODUCTS_DIR/{print $3}')/Plume.app
BEFORE=$(pgrep -f "$APP/Contents/MacOS/Plume")
open -g -j -n --env PLUME_APP_SUPPORT=/tmp/plume-scratch --env PLUME_SEED_TASKS=1 \
--env PLUME_CONTROL_SOCKET=/tmp/plume-scratch.sock "$APP"
sleep 1
PID=$(comm -13 <(echo "$BEFORE" | sort) <(pgrep -f "$APP/Contents/MacOS/Plume" | sort))
c() { scripts/debug/plume-control.py --socket /tmp/plume-scratch.sock --assert-frontmost "$@"; }
c --wait 30 hierarchyopen -j launches the app hidden, so its window never appears on the user's screen at all; that is the default, because a new window lands on the user's current Space and in front of every other inactive app. Everything works hidden except screenshot, which needs the window server to hold an image of the window. Drop -j when a screenshot is the only way to answer the question, or when the user wants to watch the overlay pointer, and say so. -g keeps the app from activating either way. --assert-frontmost fails any call that changes the frontmost app; run every call with it, because never disturbing the user's focus is the point of this system. Synthetic clicks never reorder windows; the frontmost check plus a hidden launch is the whole focus story.
When done, kill the instance by the $PID captured above — never pkill -f on the app's path, which also matches a developer's own debug Plume launched from the same DerivedData build:
kill "$PID"Inspect before you screenshot
Each step is cheaper than the next to read. Stop at the first one that answers the question.
hierarchy— the whole window as an indented outline: every text view with its text, every control with its enabled state and frame. Passtarget=to scope it.readText target='{"kind":"composer"}'or'{"kind":"chatList"}'— one surface's text, row by row.list plumeID=<id>/describe— one control's frame, label, value and enabled state.screenshot— only for a question about layout or rendering that text cannot answer. Passtarget=to crop to one control. Read the PNG in a sub-agent, never in the main conversation.
Act
c invoke target='{"id":"composer-send-button"}'
c setValue target='{"kind":"composer"}' value="hello"
c clickSpan matching=hello
c click x=120 y=80
c pointerDrag fromX=100 fromY=300 toX=400 toY=340 steps=12
c hover target='{"id":"group-header","index":0}'
c key key=j modifiers='["option"]'
c menu
c selectText from=hello to=world
c selection
c clearselectText selects transcript text by substring (matching=, or from= and to= across pieces) and selection reads back {markdown, plainText, anchor, focus}, the way a copy would produce it. invoke runs the control's registered closure (via: "closure") or clicks its center (via: "click"). A task row and a tab chip report value: "selected" when selected, so list plumeID=task-row tells you which conversation is open; check it after selecting rather than assuming the click took. Task rows and settings panes also carry an invoke closure, which selects without moving the pointer. pointerDrag posts mouse-down, .leftMouseDragged steps and mouse-up (add clickCount=2 for a word-wise drag), e.g. to drag-select chat text; read it back with selection. hover reveals hover-only controls such as a row's trailing buttons; regions in its result is how many hover regions the pointer is now inside, so 0 means the target has none. Every click and hover moves an overlay pointer in the window so a person watching can follow; clear un-hovers everything and removes it. Read the state back after every action rather than assuming it took.
Confirm which tab is selected before every chat-list or composer read. A hidden agent tab renders nothing, so its controls read disabled and readText on its chat list returns "not found". That is a correctly hidden tab, not a broken one. Forking selects the new tab on its own. Run c list plumeID=tab-chip, find the chip with value: "selected", and say which tab each reading came from.
key posts a real NSEvent down the whole dispatch path, so it is how a keyboard shortcut gets tested. Its handledBy names the menu item that owns the chord, and menu dumps every item with the chord AppKit actually holds — which is the thing to check when a shortcut does nothing, not what the source asked for.
Never drive a repro with CGEventPostToPid, cliclick, or by exec'ing the binary from a shell. All three activate the app and take over the user's pointer and frontmost window. For a click the control server can't express, synthesize it inside the process: post NSEvents through NSApp.postEvent after window.makeKey(). Post mouse-down and mouse-up about 150 ms apart, so AppKit's tracking loop pumps the run loop. LinkClickHarness is the shipped example and docs/selectable-text-link-hang.md has the recipe.
Only one agent may screenshot at a time. Parallel screenshot attempts fail, so when several agents run at once, give screenshot duty to at most one or run visual checks as a single pass afterwards.
When a control is missing
The server sees only what registers with it. A SwiftUI control with no plumeID(_:) is invisible to list and invoke, and a bare .onHover never sees the synthetic pointer. Add plumeID (with label: on repeated rows) or plumeHover at the site and rebuild; never fall back to .accessibilityIdentifier or a coordinate click at a guessed position.
What this cannot tell you
Whether a menu command ran. SwiftUI fills a focusedSceneValue only while the app's scene is active, and a hidden instance's never is, so the whole Tab menu and most of the File menu read disabled and their chords do nothing — including chords that work fine for the user. key still proves which item owns a chord; handledByEnabled tells you the item was disabled, so read a no-op there as the harness, not a bug.
Typed text in a field. A hidden instance never becomes active, so window.makeKey() is a no-op and posted key-downs reach the window, not the composer. setValue assigns the composer's string directly and skips its input rules. Neither proves typing is broken; verify typed composer behavior with a test that hosts a real MarkdownComposerTextView in an NSWindow and sends it keyDown events.
Terminal liveness. A tab's PTY is a real process, so whether it survived a switch is answered by the process tree, not by the window. The "Verifying terminal behavior" section of CLAUDE.md has that recipe; use both together when a change touches terminals.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

