imsgcrawl reads Apple Messages through a temporary read-only SQLite snapshot and syncs it into a local archive. It gives people, scripts, and agents bounded commands for checking status, listing chats, reading messages, searching text, and exporting phone contacts.
$ imsgcrawl search "older hello"
Search "older hello": showing 1 of 1.
Use --json when you need local chat IDs for follow-up commands.
date from conversation text
2000-12-31 16:01 Older Name Older Name older hello
The example uses synthetic fixture data. imsgcrawl keeps the source database and archive on the local machine.
Download a prebuilt archive for macOS or Linux from the latest release, extract it, and place imsgcrawl on your PATH. macOS release binaries are signed and notarized.
To build from source, install Go 1.27.0 or newer and run:
go install github.com/openclaw/imsgcrawl/cmd/imsgcrawl@latestThe source minimum is Go 1.27.0. Repository builds prefer the patched Go 1.27.3 through the toolchain directive in go.mod; Go selects it automatically when toolchain switching is enabled. CI uses that patched compiler while checking the unchanged source directive. New macOS source builds require macOS 13 or newer; this does not change the requirements of previously released binaries.
The default source is ~/Library/Messages/chat.db, and the default archive is ~/.imsgcrawl/archive.db. The shell or terminal running imsgcrawl may need Full Disk Access on macOS.
imsgcrawl status
imsgcrawl sync
imsgcrawl chats --limit 10
imsgcrawl messages --chat CHAT_ID --limit 20
imsgcrawl search "phrase"
imsgcrawl search -- "--help"Take CHAT_ID from the chats output. List and search commands are bounded by default; use --all only when complete local output is intentional.
| Command | Purpose |
|---|---|
metadata |
Print crawler capabilities and paths |
status |
Check source and archive readability without printing messages |
sync |
Merge the Messages snapshot into the local archive |
chats |
List archived conversations and their local IDs |
messages --chat ID |
Read one archived conversation |
search QUERY |
Search archived message text |
contacts export |
Export display names and normalized phone numbers |
Run imsgcrawl help COMMAND for flags. The command reference includes limits, examples, output shapes, and custom database/archive paths.
sync merges by default, retains rows absent from an ordinary snapshot, and binds an archive to one normalized Messages database path. sync --restore replaces the archive from the current source when changing sources or intentionally rebuilding it.
Explicit Messages deletion feeds become tombstones, and iMessage edits and retractions become append-only revision events. Normal reads and search omit deleted or withdrawn content. See Archive and retention for the data model and restore rules.
Add --json anywhere in the command line for stable fields and local IDs:
imsgcrawl --json chats --limit 20 | jq '.items[0]'Text output is for local reading and renders terminal controls in source text as visible escapes (for example, \x1b), so messages and names cannot execute terminal escape sequences. JSON preserves the original strings for scripts, tests, CrawlBar, and other CrawlKit consumers. The command reference shows the response envelope.
Messages data contains private names, email addresses, phone numbers, conversation text, and local paths. Do not publish output from a real Messages database. Public examples, tests, bug reports, and screenshots should use synthetic data.
The archive and smoke-test artifacts contain the same private material. Keep them local unless every disclosed item and destination have been explicitly approved.
go mod verify
go test ./...
go vet ./...
mkdir -p ./bin
go build -trimpath -o ./bin/imsgcrawl ./cmd/imsgcrawl
python3 scripts/smoke-cli.py ./bin/imsgcrawl
python3 -B scripts/test_smoke_transcript.pyThe synthetic CLI smoke creates and removes its own temporary Messages database; it never reads your Messages data. CI runs it and the race-enabled Go suite on macOS and Linux.
macOS CI uses the Apple Silicon xcode-27 runner, checks both release architectures against the macOS 13 minimum, and runs the Intel binary under Rosetta. Release preflight uses the pinned shared workflow with dry_run=true to build, sign, notarize and verify without creating tags or publishing.
The transcript-script tests use synthetic command output and require Bash and jq.
The optional devenv shell also provides Go, SQLite, and jq. See the agent smoke transcript for an end-to-end local CLI check.
Licensed under the MIT License.
