1---2name: pc-automation3description: pc-control4---56# pc-control78One stdlib-only CLI gives the agent verified hands on this Mac. No third9party Python packages, no daemon, no interactive prompts. Every verb takes10arguments, returns useful text (or `--json`), and exits nonzero on failure11with a fix suggestion.1213```bash14python3 ~/.claude/skills/pc-control/scripts/pc.py <command> [args] [--json]15```1617## Start here18191. `pc.py doctor` - capability report. Run this first in a new environment;20 it tells you exactly which verbs are live and which are blocked by21 missing permissions, with the fix for each.222. `pc.py <family> <action> --dry-run` - keystroke and URL verbs print what23 they would do without doing it. Use this when unsure.2425## Verbs2627### System state28| Command | Does |29|---|---|30| `battery` | percent, charging state, source, time remaining |31| `volume get\|set N\|up [N]\|down [N]\|mute\|unmute` | system output volume, 0-100 |32| `brightness up [steps]\|down [steps]` | display brightness via key codes (needs Accessibility) |33| `brightness get\|set V` | absolute values; works only where the DisplayServices API survives (broken on macOS 26, the command says so and points to up/down) |34| `ip [--public]` | local interface address; `--public` adds the WAN address |35| `apps [--all]` | visible apps, or every process with `--all` |36| `doctor` | environment and permission audit |3738### Apps39| Command | Does |40|---|---|41| `app open NAME` | launch by name (`open -a`) |42| `app quit NAME` | graceful AppleScript quit; no-op if not running |43| `app activate NAME` | bring to front |44| `app front` | name of the frontmost app |45| `app running NAME` | true/false |4647### Web and media sources48| Command | Does |49|---|---|50| `web NAME_OR_URL` | resolve and open: URL > cached name (assets/websites.json, 185 seeded) > https://name.com reachability guess (cached on success) > Google search page. Never scrapes search engines. |51| `youtube play QUERY` | fetches YouTube results, extracts the first videoId, opens the watch page directly; falls back to the results page offline |52| `youtube search QUERY` | opens the results page |5354### Keystroke families (need the Accessibility grant, see Permissions)55| Command | Does |56|---|---|57| `browser ACTION` | 20 actions: new-tab, close-tab, reopen-tab, next-tab, prev-tab, new-window, private-window, zoom-in/out/reset, refresh, hard-refresh, back, forward, history, bookmarks, address-bar, find, devtools, fullscreen. Sent to the frontmost app; mappings are Chrome-family, most work in every Mac browser. |58| `yt ACTION` | 22 YouTube transport actions: play-pause, mute, fullscreen, theater, miniplayer, captions, vol-up/down, back-5/fwd-5, back-10/fwd-10, prev-frame/next-frame, speed-up/down, start, end, prev-chapter/next-chapter, next-video/prev-video. Focus a browser with YouTube first. |59| `media status\|play-pause\|play\|pause\|next\|prev` | app-aware: drives Spotify or Music directly via AppleScript when running (status includes track and artist); otherwise falls back to keystrokes at the frontmost app |60| `keys COMBO` | raw hand, e.g. `keys cmd+shift+t`, `keys f11`, `keys brightness-up` |61| `type TEXT` | types literal text into the frontmost app |6263### Desktop utilities64| Command | Does |65|---|---|66| `screenshot [PATH]` | silent full-screen capture (needs Screen Recording permission) |67| `clipboard get\|set TEXT` | read or write the clipboard |68| `notify MSG [--title T] [--subtitle S]` | notification banner |69| `say TEXT [--voice V]` | speak through the speakers |7071### Hardware tests72| Command | Does |73|---|---|74| `mic-test [--seconds N]` | records via ffmpeg, reports peak, clipping %, noise floor, SNR, and a verdict (detects silent/dead/denied mic) |75| `speaker-test [--measure] [--duration S]` | plays 4 tones plus a log sweep. Without `--measure` it says so honestly: playback is not proof of sound. With `--measure` it records through the mic during playback and reports which tones were actually heard. |7677## Permissions (one-time, user must click these)7879`doctor` detects all of these and prints the same fixes.80811. **Accessibility** (keystroke families): System Settings > Privacy &82 Security > Accessibility > enable the app hosting the agent (Claude,83 Terminal, iTerm...). Without it, every keystroke verb fails with error84 1002 and prints this fix.852. **Microphone** (mic-test, speaker-test --measure): granted on first use86 prompt, or Privacy & Security > Microphone.873. **Screen Recording** (screenshot): Privacy & Security > Screen Recording.8889## Verification9091`scripts/gate.py` is the measured gate: 49 checks including negative92tests and regression locks from the 6-agent adversarial verification of932026-08-11, with volume and clipboard saved and restored. `gate.py --live` adds94a real keystroke round trip through TextEdit (type > select > copy >95compare clipboard) and requires the Accessibility grant. The gate prints a96NOT COVERED list; treat anything on that list as unverified.9798## Design notes and limits99100- Rebuilt 2026-08-11 from `AnubhavChaturvedi-GitHub/PC-Automation`. The101 original's 4,989-line phrase dictionary and fuzzy matcher were deleted:102 the calling agent is the intent recognizer now. Jokes/advice APIs and103 the file-creation parser were dropped; agents do those natively.104- macOS backend only. The code is layered so a Windows backend (the105 original's WMI/pycaw logic) can be added under the same verbs.106- Keystroke verbs act on the **frontmost app**, blind. Activate the right107 app first (`app activate NAME`) and prefer `--dry-run` when exploring.108- `browser history/bookmarks/devtools` shortcuts are Chrome-family;109 Safari differs for a few.110- Absolute brightness is an Apple API casualty on macOS 26; only stepping111 works, and only with Accessibility granted.
AnubhavChaturvedi-GitHub