К основному содержанию
скилл CX Codex

imessage-query — скилл для Claude Code: запросы к базе iMessage

Скилл imessage-query читает ~/Library/Messages/chat.db через SQLite: достаёт переписку с контактом, ищет по ключевым словам и вытаскивает текст из бинарного attributedBody.

MIT 159 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill imessage-query -a claude-code
Открыть на GitHub

Что делает imessage-query

Скилл даёт агенту рабочие запросы к базе сообщений macOS. Переписка по конкретному контакту, поиск слова по всем чатам, таймлайн с точными метками времени. Даты в базе лежат в наносекундах от эпохи Apple (2001-01-01), в скилле есть готовая формула пересчёта в локальное время.

Главная заноза: колонка text у многих сообщений пустая, а сам текст хранится в attributedBody бинарным NSAttributedString. В комплекте скрипт scripts/decode_attributed_body.py с тремя уровнями декодирования: pytypedstream, разбор length-prefix под несколько двоичных форматов и запасной вариант по маркеру NSString. Ставить pytypedstream не обязательно — без него скрипт просто переходит на следующий уровень.

Нужен macOS и Full Disk Access для терминала, из которого запускается Claude: без него чтение chat.db не пройдёт. Запись в базу скилл запрещает. Ещё он советует отсеивать тапбеки через m.associated_message_type = 0 и не писать в SQL != — в zsh такая строка ломается.

Какие задачи решает

  • вытащить переписку с одним контактом
  • найти ключевое слово по всем чатам сразу
  • восстановить текст из attributedBody
  • отсеять тапбеки и системный шум из выдачи
  • собрать таймлайн переписки с точными метками

Примеры запросов агенту

  • Покажи последние 50 сообщений из iMessage с этим контактом
  • Найди все упоминания «встреча» в переписке и покажи по три сообщения вокруг каждого
  • В чате пустые сообщения — достань текст из attributedBody

Как установить imessage-query

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill imessage-query -a claude-code

2Вручную: положить файлы

~/.claude/skills/imessage-query/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/imessage-query/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об imessage-query

Как установить imessage-query в Claude Code?

Выполните npx skills add terrylica/cc-skills --skill imessage-query -a claude-code. Файл скилла окажется по пути ~/.claude/skills/imessage-query/SKILL.md.

Что делает imessage-query?

Даёт агенту запросы к базе chat.db на macOS: история переписки, поиск по словам, декодирование сообщений из attributedBody и выгрузка треда с метками времени.

Обязателен ли pytypedstream?

Нет. Он включает первый уровень декодирования, а без него скрипт работает на разборе двоичных форматов и запасном варианте по маркеру NSString.

Исходный текст

SKILL.md · MIT
---
name: imessage-query
description: Query macOS iMessage database (chat.db) via SQLite. Decode NSAttributedString messages, handle tapbacks, search conversations.
allowed-tools: Read, Bash, Grep, Glob, Write
---

# iMessage Database Query

Query the macOS iMessage SQLite database (`~/Library/Messages/chat.db`) to retrieve conversation history, decode messages stored in binary format, and build sourced timelines with precise timestamps.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use

- Retrieving iMessage conversation history for a specific contact
- Building sourced timelines with timestamps from text messages
- Searching for keywords across all conversations
- Debugging messages that appear empty but contain recoverable text
- Extracting message content that iOS stored in binary `attributedBody` format

## Prerequisites

1. **macOS only** — `chat.db` is a macOS-specific database
2. **Full Disk Access** — The terminal running Claude Code must have FDA granted in System Settings > Privacy & Security > Full Disk Access
3. **Read-only** — Never write to `chat.db`. Always use read-only SQLite access.
4. **Optional**: `pip install pytypedstream` — Enables tier 1 decoder (proper typedstream deserialization). Script works without it (falls through to pure-binary tiers 2/3).

## Critical Knowledge - The `text` vs `attributedBody` Problem

**IMPORTANT**: Many iMessage messages have a NULL or empty `text` column but contain valid, recoverable text in the `attributedBody` column. This is NOT because they are voice messages — iOS stores dictated messages, messages with rich formatting, and some regular messages in `attributedBody` as an NSAttributedString binary blob.

### How to detect

```sql
-- Messages with attributedBody but no text (these are NOT necessarily voice messages)
SELECT COUNT(*) as hidden_messages
FROM message m
JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
JOIN chat c ON cmj.chat_id = c.ROWID
WHERE c.chat_identifier = '<CHAT_IDENTIFIER>'
AND (m.text IS NULL OR length(m.text) = 0)
AND m.attributedBody IS NOT NULL
AND length(m.attributedBody) > 100
AND m.associated_message_type = 0
AND m.cache_has_attachments = 0;
```

### How to distinguish message types when `text` is NULL

| `cache_has_attachments` | `attributedBody` length | Likely type                                                                |
| ----------------------- | ----------------------- | -------------------------------------------------------------------------- |
| 0                       | > 100 bytes             | **Dictated/rich text** — recoverable via decode script                     |
| 1                       | any                     | Attachment (image, file, voice memo) — text may be in `attributedBody` too |
| 0                       | < 50 bytes              | Tapback reaction or system message — usually noise                         |

### How to decode

Use the bundled decode script for reliable extraction (v4 — 3-tier decoder + native pitfall protections):

```bash
python3 <skill-path>/scripts/decode_attributed_body.py --chat "<CHAT_IDENTIFIER>" --limit 50
```

The decoder uses a 3-tier strategy:

1. **Tier 1**: `pytypedstream` Unarchiver — proper Apple typedstream deserialization (requires `pip install pytypedstream`)
2. **Tier 2**: Multi-format binary — 0x2B/0x4F/0x49 length-prefix parsing (zero deps, ported from [macos-messages](https://github.com/bettercallsean/macos-messages))
3. **Tier 3**: NSString marker + length-prefix — v2 legacy approach (zero deps, last resort)

Falls through tiers on failure. Works without pytypedstream installed (skips tier 1). See [Cross-Repo Analysis](./references/cross-repo-analysis.md) for decoder comparison.

## Date Formula

iMessage stores dates as **nanoseconds since Apple epoch (2001-01-01 00:00:00 UTC)**.

```sql
datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') as timestamp
```

- `m.date / 1000000000` — Convert nanoseconds to seconds
- `+ 978307200` — Add offset from Unix epoch (1970) to Apple epoch (2001)
- `'unixepoch'` — Tell SQLite this is a Unix timestamp
- `'localtime'` — Convert to local timezone (CRITICAL — omitting this gives UTC)

## Quick Start Queries

### 1. List all conversations

```sql
sqlite3 ~/Library/Messages/chat.db \
  "SELECT c.chat_identifier, c.display_name, COUNT(cmj.message_id) as msg_count
   FROM chat c
   JOIN chat_message_join cmj ON c.ROWID = cmj.chat_id
   GROUP BY c.ROWID
   ORDER BY msg_count DESC
   LIMIT 20"
```

### 2. Get conversation thread (text column only)

```sql
sqlite3 ~/Library/Messages/chat.db \
  "SELECT datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') as ts,
          CASE WHEN m.is_from_me = 1 THEN 'Me' ELSE 'Them' END as sender,
          m.text
   FROM message m
   JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
   JOIN chat c ON cmj.chat_id = c.ROWID
   WHERE c.chat_identifier = '<CHAT_IDENTIFIER>'
   AND length(m.text) > 0
   AND m.associated_message_type = 0
   ORDER BY m.date DESC
   LIMIT 50"
```

### 3. Get ALL messages including attributedBody (use decode script)

```bash
python3 <skill-path>/scripts/decode_attributed_body.py \
  --chat "<CHAT_IDENTIFIER>" \
  --after "2026-01-01" \
  --limit 100
```

## Filtering Noise

### Tapback reactions

Tapback reactions (likes, loves, emphasis, etc.) are stored as separate message rows with `associated_message_type != 0`. Always filter:

```sql
AND m.associated_message_type = 0
```

### Shell escaping in zsh

The `!=` operator can cause issues in zsh. Use positive assertions instead:

```sql
-- BAD (breaks in zsh)
AND m.text != ''

-- GOOD (works everywhere)
AND length(m.text) > 0
```

## Using the Decode Script

The bundled `decode_attributed_body.py` handles all edge cases:

```bash
# Basic usage - get last 50 messages from a contact
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --limit 50

# Search for keyword
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --search "meeting"

# Search with surrounding context (3 messages before and after each match)
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --search "meeting" --context 3

# Date range
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --after "2026-01-01" --before "2026-02-01"

# Only messages from the other party
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --sender them

# Only messages from me
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --sender me

# Export conversation to NDJSON for offline analysis
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" --after "2026-02-01" --export thread.jsonl
```

Output format: `timestamp|sender|text` (pipe-delimited, one message per line)

### Context Search (`--context N`)

When `--search` is combined with `--context N`, the script shows N messages before and after each match:

- Matches are prefixed with `[match]`
- Non-contiguous context groups are separated by `--- context ---`
- Overlapping context windows are deduplicated

### NDJSON Export (`--export`)

Exports messages to a NDJSON (.jsonl) file for offline analysis:

```json
{
  "ts": "2026-02-13 18:30:17",
  "sender": "them",
  "is_from_me": false,
  "text": "Message text here",
  "decoded": true,
  "type": "text",
  "edited": true,
  "service": "SMS",
  "effect": "slam",
  "reply_to": {
    "ts": "2026-02-13 18:00:00",
    "sender": "me",
    "text": "Original message..."
  }
}
```

Fields `edited`, `service`, `effect`, `reply_to` are optional — only present when applicable. The `type` field is always present (`"text"`, `"audio"`, or `"attachment"`).

**Retracted messages are NEVER exported** — they are deterministically excluded (see Native Protections below).

**Export-first workflow** (recommended for multi-query analysis):

```bash
# Step 1: Export once
python3 <skill-path>/scripts/decode_attributed_body.py --chat "+1234567890" \
  --after "2026-02-01" --export thread.jsonl

# Step 2: Analyze many times without re-querying SQLite
grep -i "keyword" thread.jsonl
jq 'select(.text | test("reference"; "i"))' thread.jsonl
jq 'select(.sender == "them")' thread.jsonl
```

## Native Protections (v4)

The decode script natively handles these pitfalls — no manual SQL workarounds needed:

| Protection                     | Column Used                               | Behavior                                                                |
| ------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------- |
| Retracted messages (Undo Send) | `date_retracted`, `date_edited`           | **Excluded** from output — content wiped by iOS, not admissible         |
| Edited messages                | `date_edited`                             | **Flagged** with `[edited]` / `"edited": true`                          |
| Audio/voice messages           | `is_audio_message`                        | **Identified** as `[audio message]` — not misclassified as empty        |
| Inline quotes (swipe-to-reply) | `thread_originator_guid`                  | **Resolved** to quoted message text via GUID index                      |
| Attachments without text       | `cache_has_attachments`, attachment table | **Surfaced** as `[attachment: filename]` instead of silently dropped    |
| Message effects                | `expressive_send_style_id`                | **Decoded** to human-readable names (slam, loud, gentle, invisible_ink) |
| Service type                   | `service`                                 | **Flagged** when SMS instead of iMessage                                |
| Tapback reactions              | `associated_message_type`                 | **Filtered** (only `= 0` included)                                      |

## Anti-Patterns to Avoid

1. **Searching multiple chat identifiers blindly** — Always run `--stats` first to confirm the right chat identifier has messages in the expected date range
2. **Keyword search without context** — Always use `--context 5` (or more) with `--search` to understand conversational meaning around matches
3. **Repeated narrow-window SQLite queries** — Export the full date range to NDJSON first, then grep/jq the file for all subsequent analysis

**Note**: Replace `<skill-path>` with the actual installed skill path. To find it:

```bash
find ~/.claude -path "*/imessage-query/scripts/decode_attributed_body.py" 2>/dev/null
```

## Reference Documentation

- [Schema Reference](./references/schema-reference.md) — Tables, columns, relationships
- [Query Patterns](./references/query-patterns.md) — Reusable SQL templates for common operations
- [Known Pitfalls](./references/known-pitfalls.md) — Every gotcha discovered and how to handle it
- [Cross-Repo Analysis](./references/cross-repo-analysis.md) — Comparison of 5 OSS decoder implementations and what we adopted

---

## TodoWrite Task Templates

### Template A - Retrieve Conversation Thread

```
1. Identify chat_identifier for the contact (phone number or email)
2. Run decode script with --chat and appropriate date range
3. Review output for attributedBody-decoded messages (marked with [decoded])
4. If searching for specific topic, add --search flag
5. Format results as needed for the task
```

### Template B - Debug Empty Messages

```
1. Query messages where text IS NULL but attributedBody IS NOT NULL
2. Check cache_has_attachments to distinguish voice/file from dictated text
3. Run decode script to extract hidden text content
4. Verify decoded content makes sense in conversation context
5. Document any new decode patterns in known-pitfalls.md
```

### Template C - Build Sourced Timeline

```
1. Identify all relevant chat_identifiers
2. Run decode script for each contact with date range
3. Merge and sort by timestamp
4. Format as sourced quotes with timestamps for documentation
5. Verify no messages were missed (compare total count vs decoded count)
```

### Template D - Export-First Deep Analysis

```
1. Run --stats to confirm chat_identifier and date range
2. Export full date range to NDJSON: --export thread.jsonl
3. Use grep/jq on the NDJSON file for all keyword searches
4. Use --search with --context 5 for contextual understanding of specific matches
5. All subsequent analysis reads from the NDJSON file (no more SQLite queries)
```

---

## Post-Change Checklist

After modifying this skill:

1. [ ] YAML frontmatter valid (name, description with triggers)
2. [ ] No private data (phone numbers, names, emails) in any file
3. [ ] All SQL uses parameterized placeholders
4. [ ] Decode script works with `python3` (pytypedstream optional, tiers 2/3 are stdlib-only)
5. [ ] All reference links are relative paths
6. [ ] Append changes to [evolution-log.md](./references/evolution-log.md)

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
imessage официальный anthropics Подключает iMessage к Claude: читает историю из chat.db, отправляет через AppleScript. Только macOS. ★ 47 914звёзд репо iMessage History anipottsbuilds MCP-сервер iMessage History ищет и читает историю сообщений Apple на macOS. Он пригодится, когда агенту нужен контекст переписки без отправки данных в облако. CX Codex +1 ★ 34звёзд репо imessage-max cyberpapiii MCP-сервер imessage-max на Swift, который даёт агенту читать, искать и отправлять сообщения iMessage на macOS. Номера превращает в имена из Контактов. CX Codex +1 ★ 7звёзд репо chat-adapter-imessage photon-hq Скилл chat-adapter-imessage помогает подключить Vercel AI SDK к iMessage через адаптер Photon. Он пригодится при разработке ИИ-ассистента, который принимает и отправляет сообщения в iMessage. CX Codex +1 126установок beeper steipete Скилл beeper для Claude Code ищет сообщения и комнаты в локальной истории Beeper. Он связывает расплывчатые подсказки о контакте с iMessage и WhatsApp. CX Codex +1 104установок spectrum photon-hq Скилл для разработки и разбора мессенджер-агентов на Photon Spectrum: один поток сообщений, доставка через iMessage, WhatsApp Business или терминал. CX Codex +1 3 300установок

Из того же набора79

Весь набор →
calendar-event-manager Скилл calendar-event-manager заводит события в macOS Calendar со звуковыми будильниками и парными напоминаниями в Reminders, чтобы встреча не прошла мимо. CX Codex +1 214установок agent-reach Скилл agent-reach даёт агенту возможность искать и читать информацию с интернета: социальные сети (Twitter, Reddit, Weibo, Xiaohongshu, Douyin, Bilibili, V2EX), карьерные сайты (LinkedIn), GitHub, YouTube, подкасты, статьи и RSS-ленты. CX Codex +1 195установок code-hardcode-audit Скилл code-hardcode-audit находит захардкоженные пароли, токены API, магические числа и дубликаты кода. Запускает оркестрацию девяти статических анализаторов через uv. CX Codex +1 166установок documentation-standards Скилл documentation-standards задаёт правила оформления Markdown для чтения моделями и экспорта в PDF через Pandoc. Спасает от поломанной нумерации глав и хаоса в структуре. CX Codex +1 161установок clickhouse-architect Скилл clickhouse-architect проектирует схемы ClickHouse v24.4+, подбирает кодеки сжатия и настраивает ключи сортировки под облачные и серверные развёртывания. CX Codex +1 157установок dead-code-detector Скилл dead-code-detector ищет неиспользуемые функции, импорты и файлы в проектах на Python, TypeScript и Rust. Помогает подготовить кодовую базу к релизу и почистить зависимости. CX Codex +1 150установок plotext-financial-chart Скилл plotext-financial-chart строит текстовые финансовые графики в ASCII для Markdown-файлов через plotext. Помогает наглядно показать ценовые уровни прямо в документации на GitHub. CX Codex +1 146установок latex-setup Скилл latex-setup помогает установить и проверить LaTeX на macOS, настроить Skim и SyncTeX. Пригодится при подготовке новой машины или поиске проблем с пакетами. CX Codex +1 146установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой