If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ReagentX/imessage-exporter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit today
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ReagentX/imessage-exporter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ReagentX/imessage-exporter.

What it runs against: a local clone of ReagentX/imessage-exporter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ReagentX/imessage-exporter | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ReagentX/imessage-exporter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ReagentX/imessage-exporter.git
#   cd imessage-exporter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ReagentX/imessage-exporter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ReagentX/imessage-exporter(\\.git)?\\b" \\
  && ok "origin remote is ReagentX/imessage-exporter" \\
  || miss "origin remote is not ReagentX/imessage-exporter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "imessage-database/src/lib.rs" \\
  && ok "imessage-database/src/lib.rs" \\
  || miss "missing critical file: imessage-database/src/lib.rs"
test -f "imessage-database/src/tables/messages/message.rs" \\
  && ok "imessage-database/src/tables/messages/message.rs" \\
  || miss "missing critical file: imessage-database/src/tables/messages/message.rs"
test -f "imessage-database/src/util/typedstream.rs" \\
  && ok "imessage-database/src/util/typedstream.rs" \\
  || miss "missing critical file: imessage-database/src/util/typedstream.rs"
test -f "imessage-database/src/message_types/mod.rs" \\
  && ok "imessage-database/src/message_types/mod.rs" \\
  || miss "missing critical file: imessage-database/src/message_types/mod.rs"
test -f "imessage-database/build.rs" \\
  && ok "imessage-database/build.rs" \\
  || miss "missing critical file: imessage-database/build.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ReagentX/imessage-exporter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

imessage-exporter is a Rust library and CLI tool that reads Apple's SQLite iMessage database (chat.db) and exports conversations to portable formats (HTML, TXT) while preserving media, metadata, and advanced message features like tapbacks, replies, handwriting, and digital touch. It also runs diagnostics to identify corruption or inconsistencies in the iMessage database. Workspace monorepo with two crates: imessage-database (library) and imessage-exporter (CLI binary). The library lives in imessage-database/src/ with modular error handling (src/error/), message type parsers for each feature (src/message_types/{app,digital_touch,handwriting,polls,etc}.rs), and protobuf definitions (digital_touch.proto, handwriting.proto). The exporter wraps this library. Build script at imessage-database/build.rs handles code generation.

macOS/Linux/Windows users who want to backup, migrate, or archive their iMessage history; developers building tools that need programmatic access to iMessage data; compliance officers managing data retention; users switching platforms who need message portability.

Active and mature: the codebase is 1.3M lines of Rust with comprehensive feature support through macOS Tahoe 26.4.1, includes CI/CD via GitHub Actions (.github/workflows/test.yml), and handles every iMessage feature class (RCS, SMS, MMS, handwriting, digital touch, app integrations). No visible abandoned markers—documentation is extensive (docs/ folder with feature tables) and build tooling is professional (lto optimization, single codegen unit). This is production-ready.

Low structural risk but single-maintainer visibility (ReagentX is the primary org). The project has minimal external dependencies (Cargo.lock maintained, workspace resolver 2), but depends critically on reverse-engineered binary formats (plist payload_data, typedstream, protobuf-based handwriting/digital_touch in src/message_types/) which may break with iOS/macOS updates. No visible issue backlog metadata, so community support maturity is unclear.

No PR or commit timestamp visible in provided data, but the codebase claims support through macOS Tahoe 26.4.1 and iOS 26.4.2 (dated 25E253, 23E261), suggesting recent maintenance. The presence of edited messages (edited.rs) and handwriting support (with proto definitions) indicates active feature parity with current iMessage capabilities.

git clone https://github.com/ReagentX/imessage-exporter.git
cd imessage-exporter
cargo build --release
cargo run --release -- --help

See imessage-exporter/README.md for full installation and usage details.

Daily commands:

cargo build --release
cargo run --release -- --database-path <path-to-chat.db> --output-path <export-dir> --export-format html

Exact options in imessage-exporter/README.md. Requires read access to macOS iMessage database (usually ~/Library/Messages/chat.db).

• imessage-database/src/lib.rs — Library entry point exposing all public APIs for accessing iMessage data structures and tables; required reading to understand the public interface.
• imessage-database/src/tables/messages/message.rs — Core message data model that powers all message extraction; contains the primary abstraction for iMessage message records.
• imessage-database/src/util/typedstream.rs — TypedStream deserialization logic for Apple's proprietary binary format used in message metadata; essential for parsing complex message payloads.
• imessage-database/src/message_types/mod.rs — Message type routing and variant system that dispatches different iMessage types (apps, effects, handwriting, etc.) to their handlers.
• imessage-database/build.rs — Build script that compiles protobuf definitions for Digital Touch and Handwriting message types; must run before compilation succeeds.
• Cargo.toml — Workspace configuration defining the imessage-database library and imessage-exporter binary as member crates.
• imessage-database/src/tables/table.rs — Generic table query abstraction providing the base interface for all database table access patterns.

Add Support for a New iMessage App Message Type

1. Create a new handler file in imessage-database/src/message_types/ following the pattern of existing types like app.rs (imessage-database/src/message_types/new_type.rs)
2. Add a variant to the MessageTypeData enum in imessage-database/src/message_types/mod.rs and wire the handler in the routing logic (imessage-database/src/message_types/mod.rs)
3. If the message uses binary plist payloads, use plist::from_bytes in imessage-database/src/util/plist.rs to deserialize (imessage-database/src/util/plist.rs)
4. Add test fixtures (plist files) to imessage-database/test_data/app_message/ and write parsing tests in imessage-database/src/tables/messages/tests/ (imessage-database/test_data/app_message/)

Add a New Database Table Query

1. Create a new struct in imessage-database/src/tables/ implementing the Table trait from table.rs (imessage-database/src/tables/new_table.rs)
2. Implement the Table trait methods: get_query_string() for SQL, get_models() to parse rows, and get_pagination_query() if needed (imessage-database/src/tables/new_table.rs)
3. Export the new table struct in imessage-database/src/tables/mod.rs (imessage-database/src/tables/mod.rs)
4. Define error types in imessage-database/src/error/ if table-specific errors are needed (imessage-database/src/error/table.rs)

Add Binary Format Parsing (TypedStream/StreamTyped)

1. If parsing Apple's proprietary TypedStream format, extend imessage-database/src/util/typedstream.rs with new deserialization logic (imessage-database/src/util/typedstream.rs)
2. Define error handling in imessage-database/src/error/typedstream.rs (imessage-database/src/error/typedstream.rs)
3. For protobuf-based messages, add a .proto file and reference it in imessage-database/build.rs to auto-generate Rust code (imessage-database/build.rs)
4. Integrate the new format into message type handlers in imessage-database/src/message_types/ (imessage-database/src/message_types/mod.rs)

Fix Cross-Platform Path Issues

1. Update imessage-database/src/util/dirs.rs to add detection logic for new OS or database locations (imessage-database/src/util/dirs.rs)
2. Check imessage-database/src/util/platform.rs to ensure platform detection covers the new scenario (imessage-database/src/util/platform.rs)
3. Add conditional compilation blocks or feature flags in imessage-database/Cargo.toml if OS-specific dependencies are needed (imessage-database/Cargo.toml)

• Rust — Memory-safe, no GC pauses, and fast binary execution for reading large SQLite databases without crashes; essential for reliable data export.
• SQLite — iMessage data is

Database access: The tool requires read access to ~/Library/Messages/chat.db on macOS, which may be protected by System Integrity Protection (SIP)—users may need to add the binary to Full Disk Access in Security & Privacy settings. Reverse-engineered formats: The typedstream and plist payload_data parsers (src/message_types/) are based on reverse engineering; iOS/macOS updates can break these without warning. Protobuf compilation: Handwriting and digital_touch features depend on .proto files being compiled at build time (build.rs); missing protobuf compiler will fail the build. Database mutations: Tool is explicitly read-only, but any concurrent iMessage access during export may cause lock contention.

• plist (Property List) format — iMessage stores structured message data (reactions, tapbacks, mentions) in binary plist embedded in the SQLite payload_data column; parsing this is central to feature extraction
• typedstream binary format — Apple's proprietary serialization format used in early iMessage payloads; reverse-engineered in this repo to extract legacy message types
• Protocol Buffers (protobuf) — Handwriting and digital touch messages are encoded as protobuf; understanding .proto compilation and message deserialization is essential for extending feature support
• SQLite full-text search (FTS) — iMessage database uses FTS for search indexing; relevant for understanding query optimization and backup integrity checks
• Rust error propagation with Result/Option — The codebase extensively uses custom error types (src/error/) and the ? operator; mastering this pattern is critical for contributing to message parsers
• Link-Time Optimization (LTO) — The release profile enables LTO and single codegen-unit for maximum performance on database operations; affects compilation time and binary size trade-offs
• macOS Sandbox and System Integrity Protection (SIP) — Users deploying this tool must grant Full Disk Access to read ~/Library/Messages/chat.db; affects deployment and error messaging strategy

• kylebshr/d3-imessage — Visualizes iMessage conversation patterns; complementary use case for the exported data
• PicoNvim/ichatlytics — Another iMessage analytics tool; shows alternative approach to reading/analyzing the chat.db database
• apple/swift-protobuf — Official Swift protobuf library; relevant since handwriting.proto and digital_touch.proto are reverse-engineered Apple message formats
• mattn/go-sqlite3 — SQLite bindings in Go; reference for how other languages handle iMessage database access patterns
• restic/restic — Backup tool that also handles encrypted system databases; architectural reference for database backup reliability

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for message type parsers

The codebase has extensive message type parsing logic (app.rs, polls.rs, sticker.rs, music.rs, etc.) but the only visible tests are in imessage-database/src/tables/messages/tests/. Each message type variant deserves dedicated unit tests to ensure correct parsing of different iMessage feature payloads. This improves reliability for a core feature.

• [ ] Create imessage-database/src/message_types/tests/ module directory
• [ ] Add unit tests in imessage-database/src/message_types/app.rs for app message parsing
• [ ] Add unit tests in imessage-database/src/message_types/polls.rs for poll parsing with sample plist data
• [ ] Add unit tests in imessage-database/src/message_types/sticker.rs and music.rs
• [ ] Update imessage-database/src/message_types/mod.rs to include test module
• [ ] Run cargo test to verify coverage

Add CI workflow for cross-platform binary builds and release artifacts

The repo has test.yml but no automated build workflow that produces release binaries for macOS, Linux, and Windows. Given the README claims support for all three platforms, a release workflow would validate multi-platform compatibility and provide pre-built binaries for users.

• [ ] Create .github/workflows/release.yml workflow file
• [ ] Add job for building on macos-latest, ubuntu-latest, and windows-latest
• [ ] Use cargo build --release with profile.release settings from Cargo.toml
• [ ] Create GitHub release artifacts (zip/tar.gz) for each platform in target/release/
• [ ] Trigger workflow on git tags matching 'v*'
• [ ] Test locally with cargo build --release before PR submission

Add protobuf message deserialization tests with example data

The codebase includes two protobuf definitions (digital_touch.proto and handwriting.proto) with corresponding generated Rust code and models, but no visible tests validating the deserialization logic. Adding integration tests with real/sample protobuf binary data would catch serialization bugs early.

• [ ] Create imessage-database/src/message_types/digital_touch/tests.rs
• [ ] Add test cases for parsing digital_touch protobuf payloads with sample binary data
• [ ] Create imessage-database/src/message_types/handwriting/tests.rs
• [ ] Add test cases for handwriting model deserialization
• [ ] Reference the existing models.rs in each module to validate field extraction
• [ ] Include error cases (malformed protobuf data) in tests

• Add unit tests for src/message_types/polls.rs—the polls feature has a parser but no visible test coverage; add test cases for poll creation, voting, and results payloads
• Expand docs/tables/messages.md to document the payload_data plist structure for each message type (currently lists columns but not the binary format details); add examples for tapback, reaction, and edited message payloads
• Write integration tests in imessage-database/tests/ that exercise the full export pipeline (load sample database → parse all message types → verify output format); currently only src/error tests visible

• Medium · Potential SQL Injection in Database Queries — imessage-database/src/tables/messages/query_parts.rs, imessage-database/src/util/query_context.rs. The codebase contains SQL query building logic in imessage-database/src/tables/messages/query_parts.rs and related query context utilities. Without reviewing the actual implementation, there's a risk that user input or external data could be improperly sanitized before being used in SQL queries, potentially leading to SQL injection vulnerabilities. Fix: Ensure all database queries use parameterized queries/prepared statements exclusively. Avoid string concatenation for SQL query building. Review query_context.rs and query_parts.rs for any dynamic SQL construction without proper escaping.
• Medium · Protobuf-Generated Code Security — imessage-database/src/message_types/digital_touch/digital_touch.proto, imessage-database/src/message_types/handwriting/handwriting.proto. The codebase includes protocol buffer files (digital_touch.proto and handwriting.proto) that generate Rust code. Generated protobuf code can have vulnerabilities if not kept up-to-date, and there's risk of deserialization attacks when parsing untrusted proto messages from the iMessage database. Fix: Keep the protobuf compiler and runtime library updated to the latest version. Implement strict validation of deserialized protobuf messages. Add size limits and resource consumption checks when parsing untrusted protobuf data.
• Medium · Potential Path Traversal in File Operations — imessage-database/src/util/dirs.rs, imessage-database/src/tables/attachment.rs. The utility module imessage-database/src/util/dirs.rs handles directory operations. If user input or database values are used to construct file paths without proper validation, this could lead to directory traversal attacks, especially when exporting multimedia content. Fix: Implement strict path validation to ensure all file operations remain within intended directories. Use canonicalization and verify resolved paths are within allowed boundaries. Sanitize all components used in path construction.
• Medium · Insufficient Input Validation for Plist Parsing — imessage-database/src/util/plist.rs, imessage-database/src/error/plist.rs. The codebase processes plist files (imessage-database/src/util/plist.rs) from the iMessage database. Malformed or malicious plist files could cause denial of service or unexpected behavior if not properly validated. Fix: Implement comprehensive error handling and resource limits when parsing plist files. Validate structure and data types before processing. Consider implementing size limits for plist files and maximum nesting depth.
• Low · Hardcoded Configuration Values — imessage-database/src/util/bundle_id.rs. While no explicit secrets were identified, the code contains various utility functions (bundle_id.rs, dates.rs) that may have hardcoded values specific to iMessage internals. These should be reviewed for any hardcoded sensitive identifiers. Fix: Review all utility modules for hardcoded values. Consider externalizing any configuration that may change across macOS versions. Document any hardcoded identifiers and their purpose.
• Low · Missing Build-Time Security Checks — imessage-database/build.rs. The build.rs file exists but its content is not provided. Build scripts can pose security risks if they execute untrusted commands or download dependencies without verification. Fix: Review build.rs to ensure it doesn't execute arbitrary commands, download dependencies without checksum verification, or expose sensitive information during compilation. Consider using locked dependency versions in Cargo.lock (which appears to be present).
• Low · Potential XSS in HTML Export — imessage-exporter crate (HTML export functionality). The project exports iMessage data to HTML format. If message content (text, attachment names, or other user data) is not properly escaped when generating HTML output, this could lead to stored XSS vulnerabilities when the HTML is opened in a browser. Fix: Ensure all user-controlled data from the iMessage database is properly HTML-escaped before being inserted into HTML exports. Use a templating engine with automatic escaping or implement strict output encoding. Validate and sanitize all message content.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.