Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Building a Local SMS Sync Tool for Samsung Devices: Bridging Android Messages to macOS

Over the past development session, I built a local SMS synchronization tool that extracts message data from Samsung Android devices and makes it available on macOS without relying on cloud services or third-party APIs. This post covers the technical architecture, the challenges encountered, and the rationale behind key design decisions.

What Was Done

The primary deliverable is a Python-based SMS sync daemon that runs on macOS and periodically pulls SMS data from a connected Samsung device. Rather than routing through Twilio or another SaaS platform, the solution leverages Android Debug Bridge (ADB) to communicate directly with the device's SMS database, extract message threads, and make them queryable locally.

Three main artifacts were created:

  • /Users/cb/Documents/repos/tools/samsung_sms_sync.py — The core sync engine
  • /Users/cb/Library/LaunchAgents/com.cb.samsung-sms-sync.plist — macOS LaunchAgent configuration for daemon operation
  • Integration with existing voice agent infrastructure to query synced SMS data

Technical Details

Architecture Overview

The solution operates in three layers:

  • Data Source: Samsung device's native SMS database (typically stored at /data/data/com.android.providers.telephony/databases/telephony.db)
  • Transport: ADB over USB connection, pulling the SQLite database and querying it locally
  • Local Cache: Exported SMS file stored in the repos directory for consumption by existing tooling (voice agents, digest generation, etc.)

This design avoids the need for Twilio credentials while maintaining a clean separation between device communication and message processing.

ADB Integration

The first obstacle was getting Android Platform Tools installed on an Apple Silicon Mac. The standard Homebrew installation path was failing:

brew install android-platform-tools

The issue: the formula was attempting to install to an x86-64 path while running on ARM64. Resolution involved checking the Homebrew prefix and forcing a clean reinstall with the correct architecture flags.

Once installed, the sync script uses ADB to pull the telephony database:

adb pull /data/data/com.android.providers.telephony/databases/telephony.db ./local_cache/

Then parses it locally using Python's sqlite3 module to extract conversation threads, timestamps, and message bodies.

Database Schema Parsing

Android's telephony database uses a standard schema where:

  • The sms table stores individual messages with columns: _id, address (phone number), body, date, type (1=received, 2=sent), read
  • Conversations are aggregated by phone number (address)
  • Timestamps are in milliseconds since epoch

The script filters for recent activity (configurable window, e.g., last 7 days) and groups messages by thread, which allows the existing digest generation code to reuse the output format without modification.

macOS LaunchAgent Configuration

The .plist file at /Users/cb/Library/LaunchAgents/com.cb.samsung-sms-sync.plist configures the daemon to run periodically:

<key>StartInterval</key>
<integer>300</integer>

This runs the sync script every 300 seconds (5 minutes). The daemon requires:

  • The Android device to be connected via USB with ADB enabled (Developer Mode + USB Debugging)
  • No authentication prompt on the device (or prior approval of the Mac's fingerprint)
  • Sufficient permissions to read telephony data (requires either rooted device or delegated read access)

Infrastructure & Integration Points

The exported SMS data integrates with existing tooling:

  • Voice Agent SMS Handlers: The phone_agent.py scripts that previously relied on Twilio can now be adapted to read from the local export file, eliminating API call overhead and latency.
  • Digest Generation: The SES-based email digest job (triggered via send-sms-digest commands) consumes the exported data to generate summaries. The output format remains compatible with existing parsing logic.
  • Handoff Tracking: Active handoff records in the voice agent's database reference phone numbers; the sync tool ensures those numbers are resolved to recent conversation context without requiring external lookups.

Key Design Decisions

Why Not Use Twilio?

Twilio is a powerful SaaS for sending SMS and managing inbound routing. However, for reading existing message threads from a personal device, it adds unnecessary cost and dependency. The local approach:

  • Eliminates monthly API costs
  • Reduces latency (no network round-trip)
  • Maintains privacy (data never leaves the device except for local processing)
  • Simplifies credential management (no Twilio SID/token to secure)

ADB Over Cloud Sync Services

Alternatives like Samsung Cloud or Google Drive SMS backups would require polling cloud APIs and managing authentication. ADB provides direct, synchronous access and is already ubiquitous in Android development.

SQLite Parsing on macOS Rather Than Device

We pull the entire database file rather than querying it on the device because:

  • The device may not have Python or appropriate CLI tools installed
  • Processing on the host machine allows for flexible filtering and format conversion
  • Easier to version control and modify query logic without modifying device software

What's Next

Future enhancements include:

  • Bidirectional Sync: Extend the tool to support sending SMS from macOS, either via ADB message dispatch or delegating back to the voice agent infrastructure.
  • Conflict Resolution: If the device receives new messages during a sync cycle, implement a merge strategy to avoid dropping data.
  • Multi-Device Support: Allow the daemon to manage multiple connected Android devices, tagging exports with device identifiers.
  • Encrypted Local Storage: Wrap the exported SMS file with encryption at rest to prevent accidental exposure of message content.
  • Webhook Integration: Trigger downstream jobs (like digest generation or CRM updates) when new messages are detected, rather than relying on polling.

The current implementation provides a stable foundation for local SMS access without external dependencies, and its design allows for incremental enhancement without breaking existing integrations.