Source: ~/Code/steipete/imsg (we own it — modify freely)
Build binary: ~/Code/steipete/imsg/bin/imsg
Launch binary: /Applications/imsg-rpc.app/Contents/MacOS/imsg
Socket: /tmp/imsg.sock
launchd plist: ~/Library/LaunchAgents/com.joel.imsg-rpc.plist
Logs: /tmp/joelclaw/imsg-rpc.{log,err}
Gateway channel: packages/gateway/src/channels/imessage.ts

Status Check

launchctl print gui/$(id -u)/com.joel.imsg-rpc | rg "state =|pid =|runs =|last exit code"
lsof -p "$(launchctl print gui/$(id -u)/com.joel.imsg-rpc | awk '/pid =/{print $3; exit}')" | rg "imsg.sock|chat.db"
lsof -nP -U | rg "imsg.sock|com.joel.gateway|/tmp/imsg.sock"  # gateway socket peer
tail -10 /tmp/joelclaw/gateway.log | rg imessage

Healthy state: PID present, exit code 0, gateway shows watch.subscribe OK.

Restart

launchctl unload ~/Library/LaunchAgents/com.joel.imsg-rpc.plist
launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

Rebuild imsg

Always use build-local.sh — NOT make build — so signing stays stable and /Applications/imsg-rpc.app stays in sync with source builds:

cd ~/Code/steipete/imsg && ./build-local.sh

build-local.sh now:

builds bin/imsg
signs with imsg Local Signing
refreshes/signs /Applications/imsg-rpc.app via scripts/install-rpc-app.sh

FDA Setup (new machine)

The imsg binary needs Full Disk Access. macOS requires a verifiable code signature to accept it.

1. Create local signing cert (once per machine)

cat > /tmp/imsg-ext.cnf << 'EOF'
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
[req_distinguished_name]
[v3_req]
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, codeSigning
basicConstraints = CA:FALSE
EOF

openssl req -x509 -newkey rsa:2048 \
  -keyout /tmp/imsg-key.pem -out /tmp/imsg-cert.pem \
  -days 3650 -nodes \
  -subj "/CN=imsg Local Signing/O=Joel Hooks" \
  -config /tmp/imsg-ext.cnf -extensions v3_req

openssl pkcs12 -export \
  -out /tmp/imsg-sign.p12 \
  -inkey /tmp/imsg-key.pem -in /tmp/imsg-cert.pem \
  -passout pass:imsg123 -name "imsg Local Signing" \
  -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1

security import /tmp/imsg-sign.p12 \
  -k ~/Library/Keychains/login.keychain-db \
  -P imsg123 -T /usr/bin/codesign

security add-trusted-cert -d -r trustRoot \
  -k ~/Library/Keychains/login.keychain-db /tmp/imsg-cert.pem

security find-identity -v -p codesigning  # should show "imsg Local Signing"

2. Build and sign

cd ~/Code/steipete/imsg && ./build-local.sh

3. Grant FDA in System Settings

open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Click +
Press ⌘⇧G, paste /Applications/imsg-rpc.app, Enter
Toggle ON

4. Load service

launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

Verify: tail -f /tmp/joelclaw/gateway.log | grep imessage — should show watch.subscribe OK.

Troubleshooting

`permissionDenied` in imsg-rpc.log

FDA is missing or csreq mismatch. Check:

sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT client, auth_value FROM access WHERE client LIKE '%imsg%';"
# auth_value 2 = allowed, 0 = denied

/usr/bin/log show --last 10m --style compact \
  --predicate 'process == "tccd" && (eventMessage CONTAINS "com.steipete.imsg" || eventMessage CONTAINS "kTCCServiceSystemPolicyAllFiles")' \
  | tail -80

If denied (0): go to System Settings → Full Disk Access → toggle imsg ON. If missing: redo FDA setup step 3. If tccd shows AUTHREQ_RESULT ... authValue=2 for /Applications/imsg-rpc.app/Contents/MacOS/imsg, FDA is granted.

Socket exists but gateway can't subscribe

imsg-rpc crashed after accepting. Check /tmp/joelclaw/imsg-rpc.err. Restart service.

`connect ENOENT /tmp/imsg.sock` but launchd says running

The daemon process can stay alive while the Unix socket path is unlinked. Gateway cannot connect until the socket path is recreated.

launchctl kickstart -k gui/$(id -u)/com.joel.imsg-rpc
ls -l /tmp/imsg.sock

Gateway now attempts this heal automatically on repeated ENOENT, but manual kickstart is the fastest recovery during incidents.

FDA toggle didn't help after rebuild

You likely rebuilt without refreshing the app bundle. Re-run:

cd ~/Code/steipete/imsg && ./build-local.sh

imsg-rpc keeps restarting (exit code 1)

Likely FDA denial. Run from terminal to test:

/Applications/imsg-rpc.app/Contents/MacOS/imsg chats --limit 1

If that works but launchd still fails → FDA entry is for wrong path or wrong signature.

JSON-RPC Protocol Reference

The gateway uses these methods over /tmp/imsg.sock:

// Subscribe to incoming messages
{"jsonrpc":"2.0","method":"watch.subscribe","params":{"participants":["handle"]},"id":1}

// Send a message
{"jsonrpc":"2.0","method":"send","params":{"to":"handle","text":"..."},"id":2}

// Inbound notification format
{"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{...}}}

Files

Path	Purpose
`~/Code/steipete/imsg/`	imsg source (we own)
`~/Code/steipete/imsg/bin/imsg`	built binary
`/Applications/imsg-rpc.app`	FDA target app bundle for launchd process
`~/Code/steipete/imsg/build-local.sh`	build + sign + app sync
`~/Code/steipete/imsg/scripts/install-rpc-app.sh`	creates/signs `/Applications/imsg-rpc.app`
`~/Library/LaunchAgents/com.joel.imsg-rpc.plist`	launchd service (not in git)
`packages/gateway/src/channels/imessage.ts`	gateway socket client
`apps/web/content/adrs/0121-imsg-rpc-socket-daemon.md`	ADR

imsg-rpc

imsg-rpc Skill

Architecture (ADR-0121)