imsgctl

# imsgctl Use `imsgctl` to read Apple Messages data available on the current machine. ## Use This Skill When - The user wants to inspect iMessage or SMS data from Apple Messages. - The user wants to list recent chats. - The user wants message history for a specific chat. - The user wants to filter message history by time. - The user wants attachment metadata. - The user wants to watch for new messages or reactions. ## Do Not Use This Skill When - The user wants to send or reply to a message. - The user wants to delete, edit, react to, or otherwise modify Messages data. - The request is about Slack, Discord, Telegram, Signal, WhatsApp, or another messaging system. ## Operating Rules - Prefer `--json` when results may be parsed or reused. - `imsgctl health --json` emits one JSON object. - `imsgctl chats --json`, `history --json`, and `watch --json` emit JSONL. - Use `--db PATH` when the user gives a specific database path or when the backend must be explicit. - Use `watch` only for live monitoring. It streams until interrupted. ## Defaults And Access - On macOS, running without `--db` prefers `~/Library/Application Support/imsgkit/replica.db` when a valid replica exists. Otherwise it falls back to `~/Library/Messages/chat.db`. - On Linux, running without `--db` reads `~/.local/share/imsgkit/replica.db`, or `$XDG_DATA_HOME/imsgkit/replica.db` when `XDG_DATA_HOME` is set to an absolute path. - Direct access to `~/Library/Messages/chat.db` requires macOS and Full Disk Access for the process doing the reading. - If contact resolution is unavailable, chat and sender labels may fall back to raw identifiers. ## Common Commands ### Check Access ```bash imsgctl health --json ``` ### List Recent Chats ```bash imsgctl chats --limit 20 --json ``` ### Read Recent History For A Chat ```bash imsgctl history --chat-id 42 --limit 50 --json ``` ### Read History With Attachment Metadata ```bash imsgctl history --chat-id 42 --limit 50 --attachments --json ``` ### Read History In A Time Window ```bash imsgctl history \ --chat-id 42 \ --limit 50 \ --start 2026-03-01T00:00:00Z \ --end 2026-03-02T00:00:00Z \ --json ``` ### Watch New Activity ```bash imsgctl watch --chat-id 42 --json ``` ### Watch New Messages, Attachments, and Reactions ```bash imsgctl watch --chat-id 42 --attachments --reactions --json ``` ### Use An Explicit Database Path ```bash imsgctl chats --db ~/Library/Application\ Support/imsgkit/replica.db --limit 20 --json imsgctl history --db ~/.local/share/imsgkit/replica.db --chat-id 42 --limit 50 --json ``` ## Recommended Workflow 1. Run `imsgctl health --json` to confirm access. 2. Run `imsgctl chats --limit 20 --json` to identify the target chat. 3. Use the returned chat ID with `imsgctl history --chat-id ... --json`. 4. Add `--start`, `--end`, `--limit`, or `--attachments` only as needed. 5. Use `imsgctl watch` only if the user asked for live monitoring. ## Viewing Image Attachments When `--attachments` reveals an image, the file is often too large to read directly. Convert it to a smaller JPEG preview, then read the result: - **macOS:** `sips -s format jpeg -Z 800 "/path/to/image.heic" --out /tmp/preview.jpg` - **Linux:** `magick "/path/to/image.heic" -resize 800x800 /tmp/preview.jpg` ## Failure Modes - If direct macOS reads fail, check Full Disk Access first. - If the expected local database path is missing, access will fail until the correct database is available on the current machine. - If chat labels are ambiguous or missing, rely on chat IDs and raw identifiers.