Summary

This project provides a customizable, iMessage-based personal AI agent built on the Claude Agent SDK. It addresses the need for a proactive, intelligent assistant that can interact naturally via text, manage complex tasks through integrations, and maintain robust memory. The target audience includes developers and power users seeking a template to build or extend their own AI agents, offering significant benefits in terms of extensibility, deep integration capabilities, and advanced memory management.

How It Works

The core architecture employs a dispatcher/worker pattern. An "Interaction agent" (dispatcher) handles incoming iMessages, manages memory, and spawns focused "Sub-agents" (workers) for specific tasks. This approach leverages the Claude Agent SDK for agent orchestration, Composio for a unified integration layer providing access to ~1000 third-party tools, Sendblue for iMessage communication, and Convex for real-time data persistence. Memory is tiered (short, long, permanent) and features vector search, post-turn extraction, decay, cleaning, and a daily adversarial consolidation pipeline for noise reduction and contradiction resolution.

Quick Start & Requirements

• Primary install/run: Clone the repository, run npm install, execute npm run setup for interactive configuration (API keys, Convex deployment), and finally npm run dev to launch the server, Convex, debug UI, and ngrok tunnel.
• Prerequisites: Node.js, a Claude Code subscription (required for Anthropic API access), Sendblue account, Convex account, optional Composio account for integrations, and ngrok or a similar tunneling service for local development. API keys for these services are necessary. Free tiers are available for Sendblue, Convex, and Composio.
• Links: YouTube walkthrough, Debug dashboard (localhost:5173), ngrok public URL.

Highlighted Details

• iMessage Native Integration: Seamless inbound/outbound iMessage via Sendblue, including typing indicators and webhook deduplication.
• Unified Integrations Layer: Composio provides access to ~1000 third-party services (Gmail, Slack, GitHub, Notion, etc.) through a single API key, abstracting OAuth and token management.
• Sophisticated Memory System: Tiered memory (short, long, permanent) with optional vector search (Voyage/OpenAI), post-turn extraction, decay, cleaning, and a daily adversarial consolidation pipeline.
• Proactive Automations & Drafts: Schedule recurring tasks via text commands; external actions are staged as drafts for user confirmation before execution.
• Comprehensive Debug Dashboard: A React/Vite UI offering agent status, timeline, memory visualization (force-directed graph), integrations management, automations tracking, and cost monitoring.

Maintenance & Community

The project welcomes contributions via Pull Requests for optimizations, bug fixes, DX improvements, new example integrations, and documentation enhancements. No specific community channels like Discord or Slack are listed.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The permissive MIT license allows for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

This project is presented as a personal template, not a production-ready product; it is not optimized for cost or security and is provided "as-is." The free tier of ngrok provides rotating URLs, necessitating manual webhook configuration on restarts unless a paid plan or alternative static tunnel is used. The agent's core functionality requires a Claude Code subscription.