mac-debug
Skill0 starsChanged 2 months agoMITView on GitHub
Diagnose a Mac automation that is failing, especially one failing silently. Use when a click does nothing, typing does not appear, the accessibility tree is empty, an AppleScript hangs or errors, coordinates land in the wrong place, or something that worked before stopped working.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- calebnewtonusc/Chewbaccaedited, first seen Aug 11, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- calebnewtonusc/Chewbacca★ 895% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- mac-actSkill
- mac-appsSkill
- mac-controlSkill
- mac-followupsSkill
- mac-permissionsSkill
- mac-seeSkill
- nova-briefSkill
- nova-runtimeSkill
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
- Very specific: line 48
If that returns kAXErrorAttributeUnsupported (-25208) on a non-Chromium app, the app genuinely has no tree and you are at layer 5.
- Very specific: line 97
When nova click "Save" cannot find something, the element is probably not called what it looks like it is called.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Debugging Mac automation
Most of these fail with no error, which is what makes them expensive. Diagnose before you retry, and never respond to a failure by escalating to a screenshot. A failing layer-3 read almost always means one specific fixable thing.
Triage
nova doctor # grants, host app, tools
nova doctor --secure-input # is the keyboard being blockedBy symptom
Typing does nothing, no error
Secure Input. A password field has focus somewhere, and macOS discards synthetic keystrokes with no error. It is a process-global reference-counted flag, so one stuck app starves the whole system.
ioreg -l -w 0 -d 1 -k IOConsoleUsers | grep -o 'kCGSSessionSecureInputPID"=[0-9]*'Nonzero is the pid holding it. Fix: open -a Finder, retry. If an app is stuck, focus
and unfocus it, or quit it.
Clicks do nothing from inside an app
App Sandbox silently blocks CGEvent.post. No error. No fix inside the sandbox;
this is why every serious macOS automation tool ships outside the App Store.
Accessibility tree is empty or all elements unnamed
Chromium builds it lazily. Chrome, Edge, VS Code, Slack, Discord, Notion, Figma, Spotify.
nova see --app Slack --force-axSets AXManualAccessibility, waits ~400ms, re-reads. The wait matters: an immediate
re-read still looks empty.
If that returns kAXErrorAttributeUnsupported (-25208) on a non-Chromium app, the app
genuinely has no tree and you are at layer 5.
Clicks land at double the offset
Retina. Screenshots are 2x device pixels; CGEvent takes screen points. Halve the
coordinate, or stop using coordinates and use refs.
Clicks land on the wrong monitor
Multi-display origins go negative. Use CGGetActiveDisplayList geometry, do not assume
0,0.
Clicking a ref hits the wrong element
Stale ref. It was scoped to a snapshot from before the UI changed. Re-snapshot after any sheet, navigation, resize, or scroll.
AppleScript errors
| Code | Meaning | Fix |
| -1743 | Not authorized | tccutil reset AppleEvents, retry in the foreground |
| -600 | App not running | open -a "App", then poll until System Events sees it |
| -1712 | Timeout (~2min) | with timeout of 300 seconds. Check for a blocking modal |
| -1728 | Object does not exist | Not permissions. Read the app's dictionary |
| -1750 | errOSASystemError | Usually TCC, reported uselessly |
defaults write had no effect
Apps cache preferences in memory and rewrite on quit. Write with the app closed, or
restart it. killall cfprefsd if a read looks stale.
chat.db rows have NULL text
Bodies moved to attributedBody on Ventura and later. Decode the typed stream, or use
mac_messages_mcp.
"database is locked"
Open read-only (file:...?mode=ro) or copy to /tmp first.
do JavaScript fails in Safari
Develop > Allow JavaScript from Apple Events is off by default. Enable the Develop menu in Safari > Settings > Advanced first.
The web task dies at a login page
A fresh Playwright browser has no profile. Attach to the user's running Chrome:
open -a "Google Chrome" --args --remote-debugging-port=9222.
It worked yesterday
Almost always: the TCC prompt was dismissed once and never returns, or the host app
changed (different terminal, an update that re-signed the binary). nova doctor.
Inspecting an element by hand
When nova click "Save" cannot find something, the element is probably not called
what it looks like it is called. Apple's Accessibility Inspector (bundled with
Xcode) shows the real role, title, and available actions.
The stop rule
Three failures on the same action: stop and report what you tried and what you saw. Do not loop, and do not switch layers to route around a diagnosis you have not made.
Full list with detectors: docs/WORKAROUNDS.md and data/failure-modes.json.
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.