drive-installed-app
Skill1 starsChanged 2 months agoApache-2.0View on GitHub
Drive the REAL installed /Applications/Mill.app for verification -- the real global hotkey, real window/tray behavior, real Accessibility-gated interactions -- instead of falling back to the command palette or struggling with a dropped Accessibility grant. Use whenever a change needs verifying on the installed app, not run-mill's server mode.
- Installs packages
- Sends data out
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- userdocs/llms-full.txtllms.txt
- userdocs/llms.txtllms.txt
- briefSkill
- build-briefSkill
- manual-checksSkill
- run-millSkill
- mill-devSkill
- mill-useSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 84
Before quitting the installed app, classify the pass as either isolated or owner-profile.
- Very specific: line 99
Do not launch the fixture until each seam is proven to reach the installed startup path: inspect the current main.go resolution plus …
- Distinctive: line 227
After the isolated fixture quits, clear its exported profile inputs before any owner-profile launch:
≈ “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
Driving the installed app
run-mill's server mode (.claude/skills/run-mill/SKILL.md) covers Go
bindings and DOM state fast, but it has no native run loop: no real
global hotkey delivery, no real window floating/Space behavior, no
Accessibility-gated interaction. This skill is what closes that gap on
the REAL /Applications/Mill.app -- the setup and procedure that goal
0381 exists to make routine, after an agent burned ~25 minutes and 30+
screenshots on exactly the two failures below.
Why this exists (read once)
task install:app's ad-hoc signature drops Mill's own Accessibility grant on every reinstall. Ad-hoc (codesign --sign -) has no Team Identifier, so TCC keys the grant to the binary's own code digest -- different every rebuild (confirmed live: an ad-hoc binary's own designated requirement iscdhash H"...", content-hash-based; a "Mill Dev Signing"-signed one iscertificate leaf = H"<cert-hash>", stable regardless of content). The fix is a stable local signing identity (below) -- not a driving-tool problem.- A scripted
osascript -e 'quit app "Mill"'can report "User canceled" even on a genuinely clean quit. Mill's own leave handshake (goal 0295 S2b) answers the synchronous AppleEventfalsewhile a background goroutine finishes the real quit -- the bridge'squitdoor (below) sidesteps this by calling the quit method directly over HTTP, no AppleEvent involved.
The updater will never overwrite this build automatically
A task install:app build always stamps its channel as source at
compile time. SettingsService's auto-download policy (goal 0403 S2d)
checks that build-time stamp, not the resolved channel a user
preference can override, before ever triggering an automatic download-
and-install -- so a background auto-update tick (or the manual "Check
for updates" button's own found-result) can never download and stage a
newer release over the exact build this skill just installed and is
driving. CheckForUpdates (detection) still answers normally, and an
explicit "Update now" click still installs -- only the AUTOMATIC apply
is skipped. No manual toggle of the update policy is needed before or
after a driving pass.
One-time machine setup
- the repo root's
scripts/setup-dev-signing.sh-- creates and imports "Mill Dev Signing", a local self-signed code-signing certificate, then tries to trust it for code signing. If that needs an interactive confirmation it can't give non-interactively, it prints the exactsecurity add-trusted-certcommand to run once and exits 2; re-run the script afterward to confirm (idempotent). - The FIRST time
codesignactually uses the new key, macOS may show a one-time "codesign wants to access key ... enter the login keychain password" dialog -- choose Always Allow; it does not ask again for this key. MILL_DRIVE_BRIDGE=1 EXTRA_TAGS=mcp task install:apponce, then grant Accessibility to the newly-signed Mill.app in System Settings > Privacy & Security > Accessibility (the OS still needs a human to click Allow the FIRST time a given identity asks -- what changes is that this grant now SURVIVES every later reinstall, confirmed by the stable designated requirement above). Also confirm the driving terminal/host itself has Accessibility there (a different grant --scripts/check-drive-setup.sh's own probe).cliclickon PATH (brew install cliclick) for native drags/clicks.
Steps 1-2 run once per machine. Step 3's grant survives every future reinstall from here on; re-run it only if the identity itself is ever regenerated (a new machine, or the keychain item was deleted).
Per-run procedure
Two concurrent installed-app passes clobber the same bundle mid-install and can kill each other's launched process (goal 0403 S2c) -- this whole procedure runs under ONE machine-wide lock, held from the quit step through the final relaunch:
scripts/with-install-lock.sh --acquireBefore quitting the installed app, classify the pass as either isolated or owner-profile. A worktree that can change a durable schema uses an isolated profile unless the check specifically requires owner data. The isolated launch sets every mutable profile seam together, all beneath one throwaway directory:
MILL_VERIFY_PROFILE="$(mktemp -d /Users/ali/code/mill-scratchpad/installed-profile.XXXXXX)"
export MILL_SETTINGS_PATH="$MILL_VERIFY_PROFILE/settings.json"
export MILL_EXECUTION_DB_PATH="$MILL_VERIFY_PROFILE/execution.db"
export MILL_EXECUTION_DATABASE_URL="sqlite:$MILL_VERIFY_PROFILE/execution.db"
export MILL_SECRETS_PATH="$MILL_VERIFY_PROFILE/secrets.kdbx"
export MILL_BACKUP_DIR="$MILL_VERIFY_PROFILE/backups"
export MILL_PLUGINS_DIR="$MILL_VERIFY_PROFILE/plugins"Do not launch the fixture until each seam is proven to reach the installed
startup path: inspect the current main.go resolution plus
pluginsvc.ResolveDir, then run the existing smoke self-test below.
internal/webviewbridgesmoke already supplies these exact values and verifies
the isolated-data badge; its
TestIsolatedAppEnvironmentReplacesEveryMutablePath self-test guards against a
caller-owned value leaking through. If a new or changed startup path bypasses
one of them, stop and report the unisolated path before the fixture runs.
go test ./internal/webviewbridgesmoke -run TestIsolatedAppEnvironmentReplacesEveryMutablePath -count=1An owner-profile pass records the retained profile's schema consequence before
installing a different build. It finishes, while this same lock is still held,
by installing and launching a build proven to read that retained schema. Record
the final executable's exact git SHA and origin (source, daily, or beta),
the profile schema, and the update state. Prefer a distributed daily/beta only
after its supported schema is proven compatible. Otherwise restore the known
compatible source build and report the distributed-release blocker. Never
restart into a known-incompatible target to test this path.
Wails v3.0.0-beta.18 exposes no public staging-discard operation. Do not call an
unexported method, guess-delete wails-update-* paths, or stage a target known
to be incompatible with the retained profile. A fixture process must quit
without exposing an in-memory ready state for such a target.
A bounded wait (default 20 min, MILL_INSTALL_LOCK_WAIT) exits 75 with
a one-line message when another pass is already running -- report
"installed pass pending", never retry in a loop. task install:app
(step 3 below) acquires this SAME lock internally; that inner acquire
detects the outer hold and no-ops through rather than deadlocking on
itself.
- Preflight: the repo root's
scripts/check-drive-setup.sh(<10s). Fix whatever it names before continuing -- never guess past a failing line. - Quit the running Mill through the bridge door, not an AppleEvent
(see "Why this exists" #2). If a bridge is already listening on the
port you intend to reuse:
The response may itself report an error ("application shutting down") or never arrive -- both are the expected shape of a clean quit racing its own HTTP response, not a failure to react to. Fallback (no bridge running, e.g. the last install predates this goal): resolve the PID from the installed app's own path --curl -sS -m 3 -X POST http://127.0.0.1:9099/mcp -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"call_bound_method","arguments":{"name":"github.com/alicoding/mill/internal/services/settingssvc.SettingsService.DevBridgeQuit","args":[]}}}'pgrep -f '/Applications/Mill\.app/Contents/MacOS/mill'-- thenkill -TERM <pid>, never a broaderpkill/killalland neverpgrep -x mill(matches by bare process name, so it can just as easily hit an unrelated dev build). Akill -TERMskips the leave handshake entirely; any unsaved state the durable execution engine tracks reconciles on the next start, same as an OS-forced quit today. - Reinstall with the bridge, from this goal's own worktree or
whichever checkout you're verifying:
Omit both vars for a plain, bridge-free reinstall (the everyday owner-driver rebuild) -- this skill only needs them when actually driving the app afterward.MILL_DRIVE_BRIDGE=1 EXTRA_TAGS=mcp task install:app - Launch by full path, never
open -a(a stray dev bundle can hijack that -- project memory), with the bridge env:MILL_SMOKE_MCP_PORT=9199 WAILS_MCP_PORT=9199 /Applications/Mill.app/Contents/MacOS/mill &WAILS_MCP_PORTis what the bridge itself reads (Wails' ownmcp_enabled.go);MILL_SMOKE_MCP_PORTonly matters tointernal/webviewbridgesmoke's own harness, not a plain launch -- set both so either reading applies. Pick a port other than 9099 if a separate Mill instance already holds it. Launching the binary directly vsopen -a, tested live: on this machine,MILL_SMOKE_MCP_PORT=9198 WAILS_MCP_PORT=9198 open -a /Applications/Mill.appreached the bridge on port 9198 exactly like the direct binary above --openDOES forward the invoking shell's env vars into the launched app here, contrary to the commonly assumed rule. Either form is a genuine, full-run-loop launch (same AppKit lifecycle, no stripped-down context); the direct binary above is still preferred as the simpler, one-fewer-moving-part form and the one this skill's own examples use throughout. NeverTaskStop/kill the shell that launched Mill for you -- a plain trailing&still ties the process to that shell, and ending or recycling it takes Mill down too. Prefix withnohup(e.g.nohup /Applications/Mill.app/Contents/MacOS/mill … &ornohup open /Applications/Mill.app &) so Mill fully detaches, and quit it only through step 2'sDevBridgeQuitdoor, never by stopping the launching shell. - Wait for the bridge, then drive command-first. A bounded loop,
never
until ... ; do sleep; done(the session rule against unbounded loops):for i in $(seq 1 20); do curl -sS -m 2 -X POST http://127.0.0.1:9199/mcp -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"app_info","arguments":{}}}' | grep -q '"os"' && break sleep 0.3 donerunCommandfirst (window.__millRunCommand, present only in aMILL_DRIVE_BRIDGE=1build) -- the samefindCommand+runpath a real click/keystroke/palette row already goes through:
Returnscurl -sS -X POST http://127.0.0.1:9199/mcp -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"js_eval","arguments":{"window":"main","js":"return await window.__millRunCommand(\"settings.open\", undefined);"}}}'{"ok":true}or{"ok":false,"error":"..."}-- anisErrorJSON-RPC envelope means the command itself threw.- Native gestures second, only for what
runCommandgenuinely can't reach (a real global hotkey, a real window drag):cliclickfor drags/clicks (cliclick dd:x,y...du:x,y); for a global hotkey,osascript'skey code, neverkeystroke-- tested live:tell application "System Events" to keystroke "0" using {command down, shift down}delivered to whatever app was frontmost as literal text instead of firing Mill's registered global hotkey, while the raw-keycode form actually triggered it:tell application "System Events" to key code 29 using {command down, shift down}(key code 29 is0; needs the driving terminal's own Accessibility grant, step 3 of setup). - Window resize: the bound
SetSizeGo method errors when called through the bridge (js_eval/runCommand), confirmed live -- resize via System Events instead:osascript -e 'tell application "System Events" to tell process "Mill" to set size of window "Mill" to {W,H}' screencapture -xfor evidence, into the session scratchpad.
- Relaunch (step 2's quit door, then steps 3-5 again) to confirm a second pass needs no re-grant -- the Acceptance this goal is proving.
- After the isolated fixture quits, clear its exported profile inputs before
any owner-profile launch:
Finish withunset MILL_SETTINGS_PATH MILL_EXECUTION_DB_PATH MILL_EXECUTION_DATABASE_URL unset MILL_SECRETS_PATH MILL_BACKUP_DIR MILL_PLUGINS_DIR MILL_VERIFY_PROFILEscripts/check-drive-setup.shagain and leave the compatible build recorded above running on the owner profile (a plain relaunch, real data, no throwaway env vars). Confirm no isolation variable survives in the final process environment and report the exact SHA/origin, profile schema, and update state. Verification traffic is allowed to leave the app open per project convention; quitting a running Mill is not itself destructive. - Release the lock acquired at the top of this procedure, now that
the pass -- including the confirmation relaunch -- has genuinely
finished:
scripts/with-install-lock.sh --release
What stays manual-only
Real focus/Space/full-screen window ordering, HideOnFocusLost, native
notification banners, and the real Trust/SMAppService/
LocalAuthentication system sheets are unaffected by this skill --
.claude/skills/manual-checks/SKILL.md is still the registry for those.
This skill only replaces the SETUP/PROCEDURE cost of reaching the
installed app in the first place; it adds no new capability to what a
human still has to eyeball.
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.

