iMessage Data Foundry
Generate realistic iMessage and Address Book sqlite databases for mock testing and demo applications.
Overview
iMessage Data Foundry creates synthetic chat.db SQLite databases that exactly mirror the macOS iMessage schema. You have the option to use Ai to generate the personas and conversations. You can either use local models through mlx (note, really only for apple silicon though given the dependency on mlx-lm.), or OpenAI / Anthropic endpoints.
Good use cases for this synthetic data are:
- Testing iMessage analysis tools and exporters
- Development of applications that interface with iMessage data
- Demos and documentation requiring realistic message data
Demo
Features
- Full Schema Replication — Exact match of macOS iMessage
chat.dbstructure - Multi-Version Support — Sonoma (14.x), Sequoia (15.x), and Tahoe (26.x)
- AI-Powered Personas — Generate realistic personas with distinct personalities
- Natural Conversations — LLM-generated messages that feel authentic
- Persona Library — Save and reuse personas across database generations
- Group Chats — Support for both 1:1 and group conversations
- Realistic Timestamps — Natural message timing with conversation batching
- Attachment Stubs — Placeholder attachments with proper database records
Installation
From PyPI (recommended)
pip install imessage-data-foundry
With uvx (no install required)
uvx imessage-data-foundry
With pipx
pipx install imessage-data-foundry
From source
git clone https://github.com/johnlarkin1/imessage-data-foundry.git
cd imessage-data-foundry
pip install -e .
Quick Start
# Launch the TUI
uvx imessage-data-foundry
# Or run directly
uv run python -m imessage_data_foundry
CLI Options
imessage-data-foundry --help
imessage-data-foundry --version
imessage-data-foundry --output ~/Desktop/chat.db
imessage-data-foundry # interactive mode (this is the default)
Configuration
LLM Provider
Select your preferred LLM provider from the Settings menu in the app. Available providers depend on which API keys you have configured.
API Keys
Set API keys as environment variables before running the app:
export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."
Local Models
For local inference on Apple Silicon, install mlx-lm:
pip install mlx-lm
Settings are stored in ~/.config/imessage-data-foundry/foundry.db.
Usage
Creating Personas
Personas can be created manually or generated by AI:
┌─ Create Persona ─────────────────────────────────┐
│ │
│ Name: Sarah Chen │
│ Phone: +1 (555) 123-4567 │
│ Relationship: Close friend from college │
│ │
│ Personality: │
│ Outgoing, tech-savvy software engineer who │
│ loves hiking and craft coffee. Quick to │
│ respond with enthusiasm and emoji. │
│ │
│ [Generate with AI] [Save] [Cancel] │
│ │
└──────────────────────────────────────────────────┘
Generating Conversations
- Select personas to include
- Choose chat type (1:1 or group)
- Set message count target
- Optionally provide a conversation seed
- Generate!
Output
The generated chat.db file can be used with any tool that reads iMessage databases:
# Example: Use with imessage-exporter
imessage-exporter -p ./output/chat.db -f html -o ./export/
API Keys
You'll need an API key from one of the supported providers:
| Provider | Get API Key |
|---|---|
| OpenAI | https://platform.openai.com/api-keys |
| Anthropic | https://console.anthropic.com/settings/keys |
Project Structure
imessage-data-foundry/
├── imessage_data_foundry/
│ ├── cli/ # CLI application and flows
│ ├── db/ # Database schema and building
│ ├── personas/ # Persona management
│ ├── conversations/ # Conversation generation
│ ├── llm/ # LLM provider integrations
│ ├── settings/ # Settings storage
│ └── utils/ # Utility functions
├── tests/ # Test suite
└── docs/ # Documentation
Schema Compatibility
Generated databases are tested for compatibility with:
Limitations
- Text-only focus — Reactions, read receipts, and message effects are not simulated
- Placeholder attachments — Attachments are stubs, not real media files
- macOS-centric — Schema targets macOS; iOS backup databases may differ slightly
Development
# Install dev dependencies
uv sync --dev
# Run tests
uv run pytest
# Run type checking
uv run mypy src/
# Format code
uv run ruff format src/
License
MIT License — See LICENSE for details.
Acknowledgments
- Schema research informed by imessage-exporter
- Built with Textual for the beautiful TUI
Metadata
Release files for imessage-data-foundry 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| imessage_data_foundry-1.0.0.tar.gz | 164.2 kB | With provenance | Details for imessage_data_foundry-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| imessage_data_foundry-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for imessage_data_foundry-1.0.0-py3-none-any.whl |
Total release size: 236.3 kB
Release files / imessage_data_foundry-1.0.0.tar.gz
| Download URL | imessage_data_foundry-1.0.0.tar.gz |
|---|---|
| Size | 164.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1a47a569a35b5c592a8103affba7afdef8cf14462c2a4bddb9cd2f3d8240efbe
|
|
BLAKE2b-256 checksum How to use checksums |
112341daf3ba2904d871f0bda8d2a9fe9b12c454eb7738adfbcd381d02531cbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.
Transparency logRelease files / imessage_data_foundry-1.0.0-py3-none-any.whl
| Download URL | imessage_data_foundry-1.0.0-py3-none-any.whl |
|---|---|
| Size | 72.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7916d75905c877cfa2b0676f067fa28e7ba4a8cf794621eabc21588ec78ff619
|
|
BLAKE2b-256 checksum How to use checksums |
4376695296e09f1e89853721971ddecdd446957a61573391dba28cdf53b278e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.
Transparency logSecurity for imessage-data-foundry 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for imessage_data_foundry-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.