pi-imessage 0.2.0

package/dist/DOCS.md

@@ -0,0 +1,591 @@
+# iMessage — Full Documentation
+
+iMessage channel for Pi. Reads your Mac's Messages database directly, sends replies via AppleScript. No external server, no API keys, no background process to keep alive.
+
+macOS only.
+
+---
+
+## Table of Contents
+
+1. [What It Does](#what-it-does)
+2. [Installation](#installation)
+3. [macOS Permissions](#macos-permissions)
+4. [Quick Start](#quick-start)
+5. [How It Works](#how-it-works)
+6. [Environment Variables](#environment-variables)
+7. [Access Control](#access-control)
+   - [Self-Chat](#self-chat)
+   - [DM Policies](#dm-policies)
+   - [Handle Addresses](#handle-addresses)
+   - [Allowlisting People](#allowlisting-people)
+   - [Pairing Mode](#pairing-mode)
+   - [Group Chats](#group-chats)
+   - [Mention Patterns](#mention-patterns)
+8. [Slash Commands](#slash-commands)
+   - [/imessage:status](#imessagestatus)
+   - [/imessage:access](#imessageaccess)
+9. [Tools Exposed to the Assistant](#tools-exposed-to-the-assistant)
+10. [Configuration File](#configuration-file)
+11. [Delivery Settings](#delivery-settings)
+12. [Limitations](#limitations)
+13. [Troubleshooting](#troubleshooting)
+
+---
+
+## What It Does
+
+iMessage connects your Pi coding assistant to iMessage. Once installed:
+
+- **Inbound**: Polls `~/Library/Messages/chat.db` (your Messages database) once per second for new messages.
+- **Outbound**: Sends replies via `osascript` (AppleScript) to Messages.app.
+- **History**: Reads full conversation history directly from `chat.db` via SQLite — not just messages since the server started.
+- **Attachments**: Inbound images are surfaced as local file paths. Outbound files send as separate messages.
+
+No external server. No API token. No webhook. It all runs locally on your Mac.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- macOS (iMessage / Messages.app)
+- Pi installed (see below for different setup scenarios)
+
+### Three ways to run Pi with iMessage
+
+How you install and load iMessage depends on how you run Pi:
+
+---
+
+#### Option A — Running from the Pi monorepo (development)
+
+If you cloned the [pi-mono](https://github.com/badlogic/pi-mono) repo and are running Pi from source, iMessage is already a package in the workspace. Pi discovers it automatically through workspace linking.
+
+**No install command needed. No flags needed.** The extension, tools, and skills are available as soon as you start Pi from the monorepo root.
+
+Just start Pi and verify:
+
+```
+/imessage:status
+```
+
+This should tab-complete and show the current state.
+
+---
+
+#### Option B — Running from a global npm install of Pi
+
+If you installed Pi globally via npm (`npm install -g @mariozechner/pi-coding-agent`), iMessage is a separate npm package you install as a plugin.
+
+**Step 1 — Install the plugin.**
+
+Start a Pi session:
+
+```sh
+pi
+```
+
+Inside the session, run:
+
+```
+/plugin install imessage
+```
+
+This fetches the package from npm and registers it in `~/.pi/agent/settings.json`. No environment variables required at install time.
+
+**Step 2 — Relaunch with the channel flag.**
+
+The iMessage server does not start unless you pass the `--channels` flag. Exit your session and relaunch:
+
+```sh
+pi --channels plugin:imessage
+```
+
+**Step 3 — Verify.**
+
+Inside the new Pi session, type `/imessage:status` — it should tab-complete and show the current state (DM policy, allowed senders, self-chat addresses).
+
+---
+
+#### Option C — Running from a local build (no npm registry)
+
+If you built Pi from source but are not using the monorepo workspace, or you have a custom build, you can load the extension directly by file path.
+
+**Step 1 — Build iMessage.**
+
+```sh
+cd /path/to/imessage
+npm run build
+```
+
+**Step 2 — Launch Pi with the extension flag.**
+
+```sh
+pi -e /path/to/imessage/dist/extensions/imessage.js
+```
+
+Or use the `--extension` flag multiple times to load several extensions:
+
+```sh
+pi --extension /path/to/imessage/dist/extensions/imessage.js
+```
+
+**Step 3 — Verify.**
+
+Inside the Pi session, type `/imessage:status` — it should tab-complete and show the current state.
+
+---
+
+### Quick comparison
+
+| | Monorepo (A) | Global npm (B) | Local build (C) |
+|---|---|---|---|
+| Install command | None | `/plugin install imessage` | None (build manually) |
+| Launch flag | None | `--channels plugin:imessage` | `-e /path/to/imessage.js` |
+| npm registry needed | No | Yes | No |
+| How Pi finds it | Workspace linking | Plugin registry | Direct file path |
+
+---
+
+## macOS Permissions
+
+iMessage needs two macOS permissions:
+
+### Full Disk Access
+
+`chat.db` is protected by macOS TCC (Transparency, Consent, and Control).
+
+When Pi first tries to read `chat.db`, macOS shows a prompt asking if your terminal can access Messages. Click **Allow**.
+
+If you dismissed the prompt or it never appeared, grant it manually:
+
+**System Settings → Privacy & Security → Full Disk Access →** add your terminal app (Terminal.app, iTerm, Ghostty, your IDE, etc.)
+
+Without this, the server exits immediately with `authorization denied`.
+
+### Automation (for sending)
+
+The first time iMessage sends a reply, macOS prompts: *"Terminal wants to control Messages"*. Click **OK**.
+
+This prompt only appears once. If you denied it, go to **System Settings → Privacy & Security → Automation** and re-enable it for your terminal.
+
+---
+
+## Quick Start
+
+After installation, the fastest path to a working setup:
+
+**1.** Launch Pi with the channel flag:
+```sh
+pi --channels plugin:imessage
+```
+
+**2.** Check status:
+```
+/imessage:status
+```
+
+**3.** Text yourself. Open Messages on any device signed into your Apple ID, start a conversation with yourself, and send a message. It reaches the assistant immediately — self-chat bypasses all access control.
+
+**4.** (Optional) Allow other people. Nobody else's texts reach the assistant until you add their handle:
+```
+/imessage:access allow +14155551234
+/imessage:access allow friend@icloud.com
+```
+
+That's it. The default policy (`allowlist`) silently drops messages from anyone not on the list.
+
+---
+
+## How It Works
+
+| Component | Mechanism |
+|---|---|
+| **Inbound** | Polls `chat.db` once a second for `ROWID > watermark`. The watermark initializes to `MAX(ROWID)` at boot — old messages are never replayed on restart. |
+| **Outbound** | `osascript -e 'tell application "Messages" to send …'`. Text and chat GUID pass through `argv` to avoid shell escaping issues. |
+| **History** | Direct SQLite queries against `chat.db`. Full history from the database, not limited to messages since server start. |
+| **Attachments (inbound)** | `chat.db` stores absolute filesystem paths for attachments. The first image per message is surfaced to the assistant as a local path. |
+| **Attachments (outbound)** | Files are sent as separate messages after the text, via AppleScript's `POSIX file` syntax. |
+| **Echo suppression** | To prevent the assistant from processing its own replies (both appear in `chat.db` as "from me"), it maintains a 15-second window of recently sent text and matches incoming messages against it. |
+| **State** | All access control state lives in `~/.pi/agent/imessage/access.json`. The server re-reads this file on every inbound message, so changes take effect without a restart. |
+
+---
+
+## Environment Variables
+
+All optional. No environment variables are required.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `IMESSAGE_APPEND_SIGNATURE` | `true` | Appends `\nSent by iMessage` to outbound messages. Set to `false` to disable. |
+| `IMESSAGE_ALLOW_SMS` | `false` | Accept inbound SMS/RCS in addition to iMessage. **Off by default because SMS sender IDs are spoofable** — a forged SMS from your own number would bypass access control. Only enable if you understand the risk. |
+| `IMESSAGE_ACCESS_MODE` | — | Set to `static` to disable runtime pairing and lock the access config to what was on disk at boot. Changes to `access.json` are ignored until restart. |
+| `IMESSAGE_STATE_DIR` | `~/.pi/agent/imessage` | Override where `access.json` and pairing state live. |
+| `IMESSAGE_DB_PATH` | `~/Library/Messages/chat.db` | Override the path to the Messages database. |
+
+Set them before launching Pi:
+
+```sh
+IMESSAGE_APPEND_SIGNATURE=false pi --channels plugin:imessage
+```
+
+Or export them in your shell profile.
+
+---
+
+## Access Control
+
+### Self-Chat
+
+Texting yourself always works with zero configuration. The server learns your own addresses at boot by reading `message.account` and `chat.last_addressed_handle` from `chat.db`. Messages from those addresses skip the gate entirely.
+
+Open Messages on any device signed into your Apple ID, start a conversation with yourself (just your name at the top), and text. The message reaches the assistant.
+
+To distinguish your input from the assistant's own replies — both appear in `chat.db` as from-me — the server maintains a 15-second echo suppression window.
+
+### DM Policies
+
+`dmPolicy` controls how texts from senders **other than you** (not on the allowlist) are handled.
+
+| Policy | Behavior |
+|---|---|
+| `allowlist` (default) | Drop silently. No auto-reply. The safest default for a personal Mac that reads your personal `chat.db`. |
+| `pairing` | Auto-reply with a 6-character pairing code, then drop the message. The sender must tell you the code, and you run `/imessage:access pair <code>` to approve them. **Warning**: every contact who texts this Mac gets an auto-reply. Only use on a dedicated line with very few contacts. |
+| `disabled` | Drop everything except self-chat. Nobody else gets through regardless of the allowlist. |
+
+```
+/imessage:access policy allowlist
+/imessage:access policy pairing
+/imessage:access policy disabled
+```
+
+### Handle Addresses
+
+iMessage identifies senders by **handle addresses** — either a phone number or an Apple ID email. The format must match exactly what appears at the top of the conversation in Messages.app.
+
+| Type | Format | Example |
+|---|---|---|
+| Phone number | `+countrycode` + number, no spaces or dashes | `+14155551234` |
+| Email | Full email address | `friend@icloud.com` |
+
+Keep the `+` prefix on phone numbers. No spaces, no dashes.
+
+If you're unsure of the exact format, check the `chat_messages` tool output — it shows raw handle IDs from `chat.db`.
+
+### Allowlisting People
+
+Under the default `allowlist` policy, add anyone you want to reach the assistant:
+
+```
+/imessage:access allow +14155551234
+/imessage:access allow partner@icloud.com
+```
+
+Remove them:
+
+```
+/imessage:access remove +14155551234
+```
+
+List everyone currently allowed:
+
+```
+/imessage:access
+```
+
+### Pairing Mode
+
+Pairing is an alternative to manually allowlisting. When `dmPolicy` is `pairing`:
+
+1. An unapproved sender texts you.
+2. The server auto-replies with a 6-character code (e.g. `a4f91c`).
+3. The sender tells you the code.
+4. You run `/imessage:access pair a4f91c` inside Pi.
+5. They're added to the allowlist and can now reach the assistant.
+
+**Caveat**: Every contact who texts this Mac gets the pairing auto-reply. This is why `allowlist` is the default — most people use their personal Messages database and don't want random contacts getting bot replies.
+
+Pairing codes expire after 1 hour. Maximum 3 pending codes at a time. Each sender gets at most 2 reminder replies.
+
+### Group Chats
+
+Group chats are **off by default**. Opt each one in individually.
+
+Groups are identified by their **chat GUID**, which looks like `iMessage;+;chat123456789012345678`. These are not exposed in Messages.app. Get them from:
+
+- The `chat_id` field in `chat_messages` tool output
+- The server's stderr log when it drops a group message
+- The `/imessage:access` status output
+
+Enable a group:
+
+```
+/imessage:access group add "iMessage;+;chat123456789012345678"
+```
+
+Always quote the GUID — the semicolons are shell metacharacters.
+
+Disable a group:
+
+```
+/imessage:access group rm "iMessage;+;chat123456789012345678"
+```
+
+By default, groups use `requireMention: true`, meaning the assistant only responds when a message matches a `mentionPatterns` regex. See [Mention Patterns](#mention-patterns).
+
+Group flags:
+
+| Flag | Effect |
+|---|---|
+| `--no-mention` | Respond to every message in the group (no mention trigger required) |
+| `--allow addr1,addr2` | Only these group members can trigger the assistant |
+
+```
+/imessage:access group add "iMessage;+;chat123456789012345678" --no-mention
+/imessage:access group add "iMessage;+;chat123456789012345678" --allow +14155551234,friend@icloud.com
+```
+
+### Mention Patterns
+
+iMessage has **no structured @mentions**. The `@Name` highlight you see in group chats is purely visual — `chat.db` does not mark it as a mention.
+
+With `requireMention: true` (the group default), the only trigger is a regex match against `mentionPatterns`. If no patterns are set, no group messages will ever reach the assistant.
+
+Set mention patterns:
+
+```
+/imessage:access set mentionPatterns '["^pi\\b", "@assistant", "hey bot"]'
+```
+
+These are **case-insensitive** regexes. A message like "hey @assistant can you help?" would match `@assistant`.
+
+---
+
+## Slash Commands
+
+Two commands are registered:
+
+### /imessage:status
+
+Shows the current state of the iMessage channel.
+
+```
+/imessage:status
+```
+
+Output includes:
+- Whether the server is running
+- DM policy (`allowlist`, `pairing`, or `disabled`)
+- Allowed senders (handles)
+- Number of enabled groups
+- Pending pairings (if any)
+- Your self-chat addresses
+
+### /imessage:access
+
+Manages access control. Supports multiple subcommands:
+
+| Command | Effect |
+|---|---|
+| `/imessage:access` | Show current state: policy, allowlist, pending pairings, groups. |
+| `/imessage:access allow +14155551234` | Add a handle to the allowlist. |
+| `/imessage:access remove +14155551234` | Remove a handle from the allowlist. |
+| `/imessage:access pair a4f91c` | Approve a pending pairing code. |
+| `/imessage:access deny a4f91c` | Discard a pending pairing code. |
+| `/imessage:access policy allowlist` | Set DM policy. Values: `allowlist`, `pairing`, `disabled`. |
+| `/imessage:access group add "iMessage;+;chat…"` | Enable a group. Flags: `--no-mention`, `--allow a,b`. |
+| `/imessage:access group rm "iMessage;+;chat…"` | Disable a group. |
+| `/imessage:access set textChunkLimit 5000` | Set a delivery config key. |
+
+All changes take effect immediately — the server re-reads `access.json` on every inbound message.
+
+---
+
+## Tools Exposed to the Assistant
+
+iMessage registers two tools that the Pi assistant can use:
+
+### imessage_reply
+
+Send a message to an iMessage chat.
+
+**Parameters:**
+
+| Parameter | Required | Description |
+|---|---|---|
+| `chat_id` | Yes | The chat GUID from the inbound message |
+| `text` | Yes | Message text to send |
+| `files` | No | Array of absolute file paths to attach. Sent as separate messages after the text. Max 100MB per file. |
+
+Text is auto-chunked based on `textChunkLimit` and `chunkMode` settings. Files over 100MB are rejected. The assistant cannot send files from the state directory (`~/.pi/agent/imessage/`).
+
+### imessage_messages
+
+Fetch recent iMessage history as conversation threads.
+
+**Parameters:**
+
+| Parameter | Required | Description |
+|---|---|---|
+| `chat_guid` | No | A specific chat GUID to read. Omit to read from every allowlisted chat. |
+| `limit` | No | Max messages per chat. Default 100, max 500. |
+
+Each thread is labelled **DM** or **Group** with its participant list, followed by timestamped messages (oldest-first). Reads `chat.db` directly — full native history, scoped to allowlisted chats only.
+
+---
+
+## Configuration File
+
+All state lives in `~/.pi/agent/imessage/`. This is **outside** the npm package directory — npm packages can be updated or reinstalled, and you don't want to lose your access config. It follows Pi's standard convention:
+
+| Path | What |
+|---|---|
+| `~/.pi/agent/settings.json` | Pi global settings |
+| `~/.pi/agent/models.json` | Pi model config |
+| `~/.pi/agent/sessions/` | Pi session history |
+| `~/.pi/agent/imessage/` | iMessage channel state |
+| `~/.pi/agent/imessage/access.json` | Access control (allowlist, policy, groups) |
+| `~/.pi/agent/imessage/approved/` | Temporary files for pairing confirmations |
+
+Nothing is written during installation (`/plugin install imessage`). The `~/.pi/agent/imessage/` directory is created at runtime — when you launch with `--channels` and either receive a message or run an access command.
+
+Override the state directory with the `IMESSAGE_STATE_DIR` environment variable:
+
+```sh
+IMESSAGE_STATE_DIR=/some/other/path pi --channels plugin:imessage
+```
+
+If `access.json` is missing, defaults are used: `allowlist` policy with empty allowlists. Only self-chat passes.
+
+### Schema
+
+```jsonc
+{
+  // How to handle texts from senders not in allowFrom.
+  // "allowlist" = drop silently (default, safest for personal accounts)
+  // "pairing" = auto-reply with a code
+  // "disabled" = drop everything except self-chat
+  "dmPolicy": "allowlist",
+
+  // Handle addresses allowed to reach the assistant.
+  // Phone numbers: +countrycode + digits, no spaces/dashes.
+  // Emails: full address.
+  "allowFrom": ["+14155551234", "partner@icloud.com"],
+
+  // Group chats the assistant participates in.
+  // Keyed by chat GUID. Empty object = DM-only (default).
+  "groups": {
+    "iMessage;+;chat123456789012345678": {
+      // true = only respond on mentionPatterns match.
+      // iMessage has no structured @mentions; regex is the only trigger.
+      "requireMention": true,
+      // Restrict triggers to these senders. Empty = any member.
+      "allowFrom": []
+    }
+  },
+
+  // Case-insensitive regexes that count as a mention in groups.
+  // Required when requireMention is true.
+  "mentionPatterns": ["^pi\\b", "@assistant"],
+
+  // Max characters per outbound message chunk.
+  // iMessage has no length cap; this is for readability.
+  "textChunkLimit": 10000,
+
+  // How to split long messages.
+  // "length" = cut exactly at the limit.
+  // "newline" = prefer paragraph/line boundaries near the limit.
+  "chunkMode": "newline"
+}
+```
+
+Changes to this file take effect on the next inbound message — no restart needed (unless `IMESSAGE_ACCESS_MODE=static`).
+
+---
+
+## Delivery Settings
+
+Configure via `/imessage:access set <key> <value>`:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `textChunkLimit` | number | 10000 | Split outbound messages longer than this. Max 10000. |
+| `chunkMode` | `"length"` or `"newline"` | `"length"` | `length` cuts at exactly the limit. `newline` prefers paragraph boundaries. |
+| `mentionPatterns` | JSON array of regex strings | `[]` | Case-insensitive patterns that trigger the assistant in group chats. |
+
+Examples:
+
+```
+/imessage:access set textChunkLimit 5000
+/imessage:access set chunkMode newline
+/imessage:access set mentionPatterns '["^pi\\b", "@assistant"]'
+```
+
+There is no tapback, edit, or thread-reply support — those require Apple's private API.
+
+---
+
+## Limitations
+
+- **macOS only** — requires `chat.db` and AppleScript.
+- **No tapback, edit, or thread replies** — AppleScript can send messages but cannot interact with these features. They require Apple's private API. If you need them, look at [BlueBubbles](https://bluebubbles.app) (requires disabling SIP).
+- **No structured @mentions** — iMessage's `@Name` is visual only. Group mention triggers are regex-based.
+- **SMS off by default** — SMS sender IDs can be spoofed. Enable with `IMESSAGE_ALLOW_SMS=true` only if you understand the risk.
+- **Polling, not push** — checks `chat.db` once per second. There is a theoretical sub-second delay.
+- **No message delete** — AppleScript cannot delete messages.
+
+---
+
+## Troubleshooting
+
+### "authorization denied" on startup
+
+Full Disk Access is not granted. Go to **System Settings → Privacy & Security → Full Disk Access** and add your terminal app.
+
+### Messages are sent but the assistant doesn't see replies
+
+The Automation permission was denied. Go to **System Settings → Privacy & Security → Automation** and re-enable Messages control for your terminal.
+
+### Self-chat isn't working
+
+Make sure you're texting from a device signed into the **same Apple ID**. The server detects your addresses from `message.account` and `chat.last_addressed_handle` in `chat.db`. Check `/imessage:status` — it lists detected self-chat addresses.
+
+### Someone texted me but the assistant didn't respond
+
+They're not on the allowlist. Under the default `allowlist` policy, messages from unknown senders are silently dropped. Add them:
+
+```
+/imessage:access allow +14155551234
+```
+
+Check who's currently allowed:
+
+```
+/imessage:access
+```
+
+### Group messages aren't reaching the assistant
+
+Groups must be explicitly enabled. You also need mention patterns set (unless using `--no-mention`). Check:
+
+```
+/imessage:access
+```
+
+If the group is listed and `requireMention` is true, make sure `mentionPatterns` includes a pattern that matches how people address the assistant.
+
+### The assistant is processing its own replies
+
+The echo suppression window is 15 seconds. If the assistant sends a message and the same text appears back within that window, it's suppressed. This should be rare. If it happens, the duplicate is harmless — it just creates an extra processing cycle.
+
+### Pairing codes aren't being sent
+
+Make sure the DM policy is actually set to `pairing`:
+
+```
+/imessage:access
+```
+
+Also check that you haven't hit the limit of 3 pending codes. Expired codes (1 hour) are cleaned up automatically.

package/dist/README.md

@@ -0,0 +1,84 @@
+# iMessage
+
+Connect iMessage to your Pi assistant. Reads `~/Library/Messages/chat.db` directly for history, search, and new-message detection; sends via AppleScript to Messages.app. No external server, no background process to keep alive.
+
+macOS only.
+
+## Quick setup
+> Default: text yourself. Other senders are dropped silently (no auto-reply) until you allowlist them. See [ACCESS.md](./ACCESS.md) for groups and multi-user setups.
+
+**1. Grant Full Disk Access.**
+
+`chat.db` is protected by macOS TCC. The first time the server reads it, macOS pops a prompt asking if your terminal can access Messages — click **Allow**. The prompt names whatever app launched bun (Terminal.app, iTerm, Ghostty, your IDE).
+
+If you click Don't Allow, or the prompt never appears, grant it manually: **System Settings → Privacy & Security → Full Disk Access** → add your terminal. Without this the server exits immediately with `authorization denied`.
+
+**2. Install the plugin.**
+
+These are Pi commands — run `pi` to start a session first.
+
+Install the plugin. No env vars required.
+```
+/plugin install imessage
+```
+
+**3. Relaunch with the channel flag.**
+
+The server won't connect without this — exit your session and start a new one:
+
+```sh
+pi --channels plugin:imessage
+```
+
+Check that `/imessage:status` tab-completes.
+
+**4. Text yourself.**
+
+iMessage yourself from any device. It reaches the assistant immediately — self-chat bypasses access control.
+
+> The first outbound reply triggers an **Automation** permission prompt ("Terminal wants to control Messages"). Click OK.
+
+**5. Decide who else gets in.**
+
+Nobody else's texts reach the assistant until you add their handle:
+
+```
+/imessage:access allow +15551234567
+```
+
+Handles are phone numbers (`+15551234567`) or Apple ID emails (`them@icloud.com`). If you're not sure what you want, ask iMessage to review your setup.
+
+## How it works
+
+| | |
+| --- | --- |
+| **Inbound** | Polls `chat.db` once a second for `ROWID > watermark`. Watermark initializes to `MAX(ROWID)` at boot — old messages aren't replayed on restart. |
+| **Outbound** | `osascript` with `tell application "Messages" to send …`. Text and chat GUID pass through argv so there's no escaping footgun. |
+| **History & search** | Direct SQLite queries against `chat.db`. Full history — not just messages since the server started. |
+| **Attachments** | `chat.db` stores absolute filesystem paths. The first inbound image per message is surfaced to the assistant as a local path it can `Read`. Outbound attachments send as separate messages after the text. |
+
+## Environment variables
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `IMESSAGE_APPEND_SIGNATURE` | `true` | Appends `\nSent by iMessage` to outbound messages. Set to `false` to disable. |
+| `IMESSAGE_ALLOW_SMS` | `false` | Accept inbound SMS/RCS in addition to iMessage. **Off by default because SMS sender IDs are spoofable** — a forged SMS from your own number would otherwise bypass access control. Only enable if you understand the risk. |
+| `IMESSAGE_ACCESS_MODE` | — | Set to `static` to disable runtime pairing and read `access.json` only. |
+| `IMESSAGE_STATE_DIR` | `~/.pi/agent/imessage` | Override where `access.json` and pairing state live. |
+
+## Access control
+
+See **[ACCESS.md](./ACCESS.md)** for DM policies, groups, self-chat, delivery config, skill commands, and the `access.json` schema.
+
+Quick reference: IDs are **handle addresses** (`+15551234567` or `someone@icloud.com`). Default policy is `allowlist` — this reads your personal `chat.db`. Self-chat always bypasses the gate.
+
+## Tools exposed to the assistant
+
+| Tool | Purpose |
+| --- | --- |
+| `reply` | Send to a chat. `chat_id` + `text`, optional `files` (absolute paths). Auto-chunks text; files send as separate messages. |
+| `chat_messages` | Fetch recent history as conversation threads. Each thread is labelled **DM** or **Group** with its participant list, then timestamped messages (oldest-first). Omit `chat_guid` to see every allowlisted chat at once, or pass one to drill in. Default 100 messages per chat. Reads `chat.db` directly — full native history. |
+
+## What you don't get
+
+AppleScript can send messages but not tapback, edit, or thread — those require Apple's private API. If you need them, look at [BlueBubbles](https://bluebubbles.app) (requires disabling SIP).