imsg-permissions
Skill3 starsChanged yesterdayMITView on GitHub
Grant the imsg CLI its macOS privacy permissions (Full Disk Access, Automation → Messages, Contacts) and prove each one from every parent that runs imsg; on a SIP-off Mac, also deploy its IMCore bridge. Use when setting up imsg on a Mac, after `brew upgrade imsg` or a node upgrade, when imsg fails with "unable to open database file", "Not authorized to send Apple events" or "(Contacts unavailable)", or when typing indicators, read receipts or `imsg status` need the IMCore bridge.
- Installs packages
In this repository31 other files it gives its agents.
- affix-domainsSkill
- apple-designSkill
- apwcli-pairSkill
- ask-always-on-agentSkill
- asus-esc8000-firmware-upgradeSkill
- asus-esc8000-gpu-bios-tuningSkill
- build-stealth-rustdeskSkill
- chrome-cdp-setupSkill
- cua-macos-lume-sandboxSkill
- deploy-kimi-k26-on-rtx-pro-6000Skill
- deploy-kimi-k3-on-rtx-pro-6000Skill
- deploy-stealth-rustdeskSkill
- ghostty-terminfoSkill
- herdr-rename-hookSkill
- llm-inference-benchmarkSkill
- lxd-docker-firewall-conflictSkill
- mac-mini-as-headless-serverSkill
- macos-app-multi-instancesSkill
- macos-smb-serverSkill
- mac-smb-automountSkill
- openclaw-diagnoseSkill
- paseo-profilesSkill
- private-fork-syncSkill
- refresh-claude-accountSkill
- ssh-claude-authSkill
- sync-claude-accountsSkill
- to-featuresSkill
- trusted-publishSkill
- ubuntu-lxd-gpu-serverSkill
- ubuntu-nvidia-gpu-enablementSkill
- ubuntu-zfs-mirror-installSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Very specific: line 33
Fill the rows: Keep the terminal apps installed on this host.
- Distinctive: line 47
Write output to files and read them back.
- Distinctive: line 57
When no prompt shows, read tccd's log (macos-tcc.md).
- Distinctive: line 65
Re-test the whole table: Remove test files, and quit apps you started.
≈ “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
imsg-permissions
imsg (openclaw/imsg, Homebrew) needs three macOS privacy grants; upstream lists them in
docs/permissions.md. How TCC
grants work, and the backup-first steps for a TCC.db edit, are in
macos-tcc.md. Read it before step 3.
The work centres on the grant table: one row per parent that runs imsg, one column per gate. A cell is ✅ only when a real command from that real parent passed.
| Parent | Full Disk Access | Automation → Messages | Contacts |
| SSH | |||
| Terminal.app, Ghostty, iTerm2 (each one installed) | |||
paseo daemon (charged to its LaunchAgent's first program, /bin/zsh, or node on hosts in macbook-provision's paseo_node_launch_hosts (mac-mini-m6); with SIP on, node under a zsh job is denied, personal-agent Q284–Q285) | |||
| imsg as its own process (LaunchAgent) | |||
openroutine daemon (charged to ~/.cargo/bin/openroutine, its LaunchAgent's program; cargo install leaves it ad-hoc signed, so each rebuild drops the grant until coding-agent's devops/openroutine/resign.sh re-signs it with a self-made certificate, coding-agent Q710; its tcc-probe task checks daily) |
Scripts
probe.sh <own-address> [--keep-ssh]tests all three gates from the parent that runs it, and sends nothing.--keep-sshonly in the SSH row.as-imsg.sh [--tty] <imsg args…>runs imsg once as its own process (a one-shot gui LaunchAgent) and prints its output and exit code.--ttyputs a tty on stdin.
Steps
- Fill the rows. Keep the terminal apps installed on this host. Find paseo's launch line with
plutil -extract ProgramArguments json -o - ~/Library/LaunchAgents/sh.paseo.daemon.plist; macOS charges the first program, even afterexec(personal-agent Q283). Done when each row names a real parent. Test every cell with
probe.sh(<own-address>is the user's iMessage address) from its parent:- SSH: run it in this shell with
--keep-ssh. - Terminal: a
.commandfile that runs it, viaopen -a Terminal <file>. - Ghostty:
open -na Ghostty --args -e <file>. - paseo:
launchctl submit -l <label> -o <log> --plus paseo's exact launch line, withexec paseo daemon runswapped forexec <probe.sh> <own-address>; thenlaunchctl remove <label>. - imsg itself:
as-imsg.sh chats --limit 1 --jsonandas-imsg.sh nickname --local --address <own-address> --json. Its Automation cell waits for step 5.
Write output to files and read them back. Done when every cell holds pass or fail with output.
- SSH: run it in this shell with
Grant each failing cell.
- Full Disk Access: System Settings +, adding the parent app, or for imsg itself the real
binary
/opt/homebrew/Cellar/imsg/<ver>/libexec/imsg(bin/imsgis a bash wrapper). - Automation: rerun the parent's probe. When "
<parent>wants access to control Messages.app" shows, click Allow with System Events, as macos-tcc.md shows. - Contacts: imsg asks only with a TTY on stdin and no
SSH_CONNECTION/SSH_CLIENT;chatsandhistorynever ask. For imsg itself, runas-imsg.sh --tty nickname --local --address <own-address> --json. A terminal app asks only when its own code asks.
When no prompt shows, read tccd's log (macos-tcc.md). Done when each cell passes, or tccd names why it cannot.
- Full Disk Access: System Settings +, adding the parent app, or for imsg itself the real
binary
- Take each blocked cell to the user, with tccd's reason and the options: leave it, change the
host, or a direct
TCC.dbedit. Do the edit only on the user's yes, by macos-tcc.md's steps. - Test imsg's own Automation only on the user's yes. It needs a real send: ask for the
recipient, then
as-imsg.sh send --to <address> --text "imsg permission test (ignore)"once, and click Allow on the prompt. Onmay_have_completed … retry is not safe, find the message before any retry (gotchas). - Re-test the whole table. Remove test files, and quit apps you started. Done when every cell is ✅, or marked with its blocker and the user's choice.
- Report the table, and log each grant and each
TCC.dbedit withlog-decisionsin the repo you work from.
IMCore bridge (SIP-off hosts)
Typing indicators, read receipts, polls and the other private sends of upstream docs/advanced-imcore.md need imsg's helper dylib injected into Messages.app. These are not privacy grants: finish the grant table first. mac-mini-m2 runs the bridge (Q86).
- Check the gates.
csrutil statussays disabled./opt/homebrew/opt/imsg/libexec/imsg-bridge-helper.dylibexists (Homebrew ships it).defaults read /Library/Preferences/com.apple.loginwindow autoLoginUsernames the Messages user, because the bridge agent starts only after login. mac-mini-m2 also hasamfi_get_out_of_my_way=1innvram boot-args, against macOS 26+ library validation. A gate that fails goes to the user: SIP and boot-args need Recovery and a reboot. - Inject.
IMSG_LAUNCH_READY_TIMEOUT=60 imsg launch --jsonrestarts Messages with the helper. - Keep it across reboots.
/opt/homebrew/opt/imsg/libexec/imsg launch --install-agent --jsonwrites~/Library/LaunchAgents/org.openclaw.imsg.bridge.plist, which re-injects every 300 s when the helper is missing or stale. Install it through theoptpath: the agent saves the path of the binary that ran, andbin/imsgis a wrapper that runs the versioned Cellar binary, whichbrew cleanupdeletes.
Done when imsg status --json has advanced_features, typing_indicators and read_receipts
true and helper_version equal to version, and launchctl print gui/$(id -u)/org.openclaw.imsg.bridge
shows last exit code = 0. Before you use a bridge command, check its selectors entry in that
JSON: on macOS 27 some are false (editMessage, deleteChat, leaveChat).
Gotchas
- SSH needs no Contacts grant. Over SSH, imsg reads the AddressBook SQLite files through
sshd's Full Disk Access. Judge Contacts by
contacts_unavailable;sourcesayslocal-addressbookeither way. openfrom SSH leaksSSH_*into the app, and imsg then takes the SSH path.probe.shunsets them.- Terminal.app never asks for Contacts. Its
Info.plisthas noNSContactsUsageDescription. Its Contacts cell needs aTCC.dbrow (macos-tcc.md). - "Policy disallows prompt." On mac-mini-m2 (SIP off) tccd refused every Contacts prompt, for
every parent. All four Contacts cells there came from
TCC.dbrows (personal-agent Q263, Q264). On every host,nodegets the same refusal: its hardened runtime lacks the Contacts entitlement, so the node row's Contacts cell needs aTCC.dbrow (m6 test, 2026-10-27). That row is possible only with SIP off. With SIP on, when paseo's program has Full Disk Access, a~/.local/bin/imsgwrapper ahead of/opt/homebrew/binon paseo's PATH that setsSSH_CLIENT(when unset) makes imsg read names from the AddressBook files. On m6 it gives node's imsg calls names; mark that cell ✅ (fallback) (personal-agent Q281). - A self-send can land in the phone-number thread. A send to the user's email address was
filed under their phone number, so imsg exited 1 with
may_have_completed … retry is not safe, though the message went out. Find it withimsg chats --limit 5(newestlast_message_at) andimsg history --chat-id <id>; send again only if it is missing (personal-agent Q266). - Upgrades drop path grants. Grants on
libexec/imsgand on mise'snodematch by path, sobrew upgrade imsgor a new node version needs this skill again. The bridge agent handles its own upgrade: a helper whose version differs from the CLI's is replaced at the next check.
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.

