agent

Autonomous iMessage reply runtime built with Mastra, BlueBubbles, and TypeScript.

What this project is

This repo runs an AI chat agent that:

• Receives inbound iMessage events through BlueBubbles webhooks
• Streams and formats replies with multi-bubble delivery and typing simulation
• Uses Mastra agents with provider fallback support
• Tracks quality with iMessage-focused evals

GitHub About Metadata

Use the following values in the repository About settings.

• Description: Autonomous iMessage AI agent runtime built with Mastra and BlueBubbles.
• About: TypeScript runtime for webhook-driven iMessage replies, delivery timing, and eval-backed quality checks.
• Topics/Tags: mastra, typescript, ai-agent, imessage, bluebubbles, llm, agent-runtime, evals

Quick Start

Prerequisites

• Node.js >=22.13.0
• BlueBubbles server access and webhook credentials
• Model/provider credentials in .env

Commands

npm run login            # Authenticate provider access
npm run doctor           # Validate runtime configuration
npm run start            # Start webhook runtime
npm run dev              # Start Mastra Studio (http://localhost:4111)
npm run build            # Build for production
npm run eval:imessage    # Run deterministic iMessage evals

Project Structure

• src/index.ts: Runtime entrypoint for webhook processing and outbound delivery
• src/lib/: Messaging, provider, policy, and delivery utilities
• src/mastra/agents/: Agent definitions and model bindings
• src/mastra/evals/: iMessage eval harness and fixtures
• src/mastra/: Mastra initialization and framework wiring

References

• Mastra docs: https://mastra.ai/docs/
• Mastra Studio overview: https://mastra.ai/docs/studio/overview
• Mastra LLM docs index: https://mastra.ai/llms.txt
• BlueBubbles SDK (used by this runtime): https://www.npmjs.com/package/@anmho/bluebubbles-sdk
• Project guidance: AGENTS.md