Your AI Executive Assistant, Available via iMessage
Talk to an AI assistant over iMessage without opening a browser or installing a new app.
Weldon Makori — Founder & Developer
TEXTMYAGENT is a passion project built to bring AI assistance to where conversations already happen: your Messages app.
TEXTMYAGENT transforms everyday texting into an interface for a Claude-powered executive assistant named Grace. The service listens for inbound iMessage/SMS traffic through BlueBubbles, enriches conversations with long-term memory, and replies in real time while managing usage, rate limits, and context budgets.
Think of it as having a smart, always-available assistant in your pocket—accessible through the Messages app you already use every day.
| Advantage | Description |
|---|---|
| 💬 Native iMessage | Users stay inside Messages with zero installs. No SMS short codes or clunky web chats. |
| 🧠 Deep Integration | Access to delivery receipts, read states, attachments, reactions, and typing indicators. |
| 🛡️ Self-Hosted | Everything runs on your hardware—no vendor lock-in, full credential control. |
| 🔒 Privacy First | Your conversations never leave your infrastructure. |
- Anthropic Claude Integration — Powered by Claude 3.5 Sonnet/Haiku for intelligent, context-aware responses
- Conversation Memory — Multi-layer memory system (working/session/long-term) with automatic summarization
- Natural Language Understanding — Understands casual text, handles typos, interprets intent
- Web Search — Real-time web search for current events, weather, news, and facts
- Adaptive Personality — Mirrors your communication style—casual, professional, or anywhere in between
- Natural Language Reminders — "Remind me to call mom tomorrow at 3pm" → Done
- Reliable Delivery — Bull queue-backed scheduling ensures reminders fire on time
- Multiple Channels — Deliver via iMessage, email, or both
- Send Emails — "Send an email to john@example.com about the meeting"
- Read Inbox — "Check my emails" or "Any new messages?"
- Reply to Emails — "Reply to that email saying I'll be there"
- Dedicated Agent Email — Each user gets a unique agent email address
- Scheduled Tasks — Create recurring or one-time automated actions
- Execution Agents — Spawn specialized agents for specific tasks
- Flexible Scheduling — "Every morning at 9am", "Every 2 hours", "Next Monday at 3pm"
Built-in tools that the AI can use autonomously:
| Tool | Description |
|---|---|
create_reminder |
Set reminders for specific times |
list_reminders |
View pending reminders |
cancel_reminder |
Remove a reminder |
create_trigger |
Schedule recurring automated tasks |
list_triggers |
View scheduled triggers |
update_trigger |
Modify or pause a trigger |
delete_trigger |
Remove a trigger |
send_email |
Send emails on behalf of the user |
list_emails |
View recent emails in inbox |
read_email |
Read full content of an email |
reply_email |
Reply to an existing email |
get_agent_email |
Get the agent's email address |
Here are actual examples of what Grace can do, based on real usage:
You: Remind me to call mom tomorrow at 3pm
Grace: done, i'll ping you at 3pm tmrw
You: weather?
Grace: 72° sunny in austin rn
You: Send an email to weldonmakori@outlook.com saying hi
Grace: sent! emailed weldonmakori@outlook.com with your message
You: Every morning at 9am, send me a summary of my day
Grace: done, trigger set for 9am daily
You: thanks
Grace: 👍
You: hey
Grace: hey
You: what's up
Grace: not much, what do you need?
You: What's on my calendar today?
Grace: 10am design sync
2pm investor call
nothing else scheduled
You: What's the latest news about AI?
Grace: [searches web and provides current information]
TEXTMYAGENT/
├── agent-service/ # Node/TypeScript core application
│ ├── src/
│ │ ├── agents/ # Dual-agent system (Interaction + Execution)
│ │ │ ├── prompts/ # Grace system prompt & personality
│ │ │ ├── InteractionAgent # Handles user conversations
│ │ │ └── ExecutionAgent # Handles tool execution
│ │ ├── config/ # Runtime configuration
│ │ ├── database/ # TypeORM entities & migrations
│ │ │ ├── entities/ # User, Reminder, Trigger, Message
│ │ │ └── connection.ts # Database connection management
│ │ ├── handlers/ # Message preprocessing pipeline
│ │ ├── integrations/ # BlueBubbles client, AgentMail
│ │ ├── services/ # Core business logic
│ │ │ ├── MessageRouter # Message orchestration
│ │ │ ├── ClaudeServiceEnhanced # Claude API with tools
│ │ │ ├── ReminderService # Reminder scheduling
│ │ │ ├── TriggerService # Automation triggers
│ │ │ └── ContextService # User context & memory
│ │ ├── tools/ # Tool registry & implementations
│ │ └── utils/ # Logging, metrics, helpers
│ └── docker-compose.yml # Local dev dependencies
├── bluebubbles-server/ # BlueBubbles server (reference)
├── docs/ # Documentation
│ ├── guides/ # Setup & migration guides
│ ├── operations/ # Runbooks & deployment
│ └── notes/ # Research & planning
└── README.md # You are here
| Service | Responsibility |
|---|---|
| MessageRouter | Cleans inbound messages, assembles context, coordinates Claude calls, dispatches replies |
| ClaudeServiceEnhanced | Wraps Anthropic Claude with streaming, tool loops, and request management |
| AnthropicRequestManager | Enforces rate limits, retry/backoff, notifies admins on quota exhaustion |
| ConversationSummarizer | Compresses history when token usage approaches thresholds |
| ReminderService | Natural language parsing + Bull queue for reliable reminder delivery |
| TriggerService | Manages scheduled automation triggers |
| ContextService | Loads user profiles, preferences, and memory highlights |
- macOS host with iMessage signed in (required by BlueBubbles)
- Node.js 18+
- Docker Desktop (for Postgres & Redis)
- Anthropic API key with Claude access
- BlueBubbles Server running and configured
# Clone the repository
git clone https://github.com/ever-just/bluebubbles-ai-agent.git
cd bluebubbles-ai-agent/agent-service
# Install dependencies
npm install
# Copy environment template
cp .env.example .envEdit .env with your credentials:
# Required
ANTHROPIC_API_KEY=sk-ant-...
BLUEBUBBLES_URL=http://localhost:1234
BLUEBUBBLES_PASSWORD=your-password
DATABASE_URL=postgres://postgres:password@localhost:5432/agent_db
REDIS_URL=redis://localhost:6379
ENCRYPTION_KEY=your-32-char-key
SESSION_SECRET=your-session-secret
# Optional - Email Integration
AGENTMAIL_API_KEY=am_...
AGENTMAIL_ENABLED=true
# Optional - Model Configuration
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_RESPONSE_MAX_TOKENS=600
ANTHROPIC_ENABLE_WEB_SEARCH=true# Start database and Redis
docker-compose up -d
# Development mode (with hot reload)
npm run dev
# Production mode
npm run build && npm start# Check health endpoint
curl http://localhost:3000/health
# Expected response:
{
"status": "healthy",
"services": {
"database": "connected",
"redis": "connected",
"bluebubbles": "connected"
}
}| Variable | Description | Default |
|---|---|---|
PORT |
Server port | 3000 |
NODE_ENV |
Environment | development |
LOG_LEVEL |
Logging verbosity | info |
| Variable | Description | Default |
|---|---|---|
ANTHROPIC_API_KEY |
Claude API key | Required |
ANTHROPIC_MODEL |
Model to use | claude-3-5-haiku-latest |
ANTHROPIC_RESPONSE_MAX_TOKENS |
Max response tokens | 350 |
ANTHROPIC_TEMPERATURE |
Response creativity | 0.7 |
ANTHROPIC_ENABLE_WEB_SEARCH |
Enable web search | true |
ANTHROPIC_ENABLE_WEB_FETCH |
Enable web fetch (beta) | false |
ANTHROPIC_SUMMARY_TRIGGER_TOKENS |
When to summarize | 5500 |
ANTHROPIC_CONTEXT_WINDOW_TOKENS |
Context budget | 7000 |
| Variable | Description | Default |
|---|---|---|
BLUEBUBBLES_URL |
Server URL | Required |
BLUEBUBBLES_PASSWORD |
Server password | Required |
BLUEBUBBLES_SEND_ENABLED |
Allow sending messages | true |
BLUEBUBBLES_MARK_CHATS_READ |
Auto-mark as read | true |
| Variable | Description | Default |
|---|---|---|
AGENTMAIL_API_KEY |
AgentMail API key | — |
AGENTMAIL_ENABLED |
Enable email features | false |
AGENTMAIL_DEFAULT_DOMAIN |
Email domain | agentmail.to |
| Variable | Description | Default |
|---|---|---|
ENABLE_DUAL_AGENT |
Enable dual-agent mode | false |
AGENT_EXECUTION_TIMEOUT_SECONDS |
Tool execution timeout | 90 |
AGENT_MAX_TOOL_ITERATIONS |
Max tool calls per turn | 8 |
- Never commit
.env— It's gitignored by default - Rotate credentials regularly — Claude API keys, BlueBubbles password
- Restrict database access — Use managed services or firewall rules in production
- Enable rate limiting — Protect public endpoints from abuse
- Use HTTPS — Encrypt traffic in production deployments
All logs include metadata for debugging and cost tracking:
{
"level": "info",
"message": "Claude response received",
"timestamp": "2026-04-03T20:15:00.000Z",
"tokensUsed": 245,
"model": "claude-sonnet-4-5-20250929",
"toolsUsed": ["create_reminder"]
}GET /health— Service health with dependency status- Database, Redis, and BlueBubbles connectivity monitored
- Graceful degradation when services are unavailable
- Rate limit exhaustion notifications via iMessage
- Critical error escalation to admin phones
- Retry-after handling respects Anthropic headers
- WhatsApp/Telegram/Slack — Additional messaging channels
- RAG/Vector Search — Knowledge retrieval for richer answers
- Multi-Tenant — Per-user memories, billing, access controls
- Analytics Dashboard — Usage visualization, latency tracking
- Voice Messages — Transcription and voice response support
- Calendar Integration — Google/Apple Calendar sync
- Image Understanding — Vision capabilities for photo analysis
| Directory | Contents |
|---|---|
docs/guides/ |
Setup guides, migrations, checklists |
docs/operations/ |
Runbooks, deployment notes |
docs/templates/ |
Status/report templates |
docs/notes/ |
Research plans, findings |
- Weldon Makori — Project creator and lead developer
- BlueBubbles — macOS-to-messaging bridge
- Anthropic Claude — Conversational AI intelligence
- AgentMail — Email infrastructure for AI agents
- TypeORM — Database ORM
- Bull — Redis-based job queue
- chrono-node — Natural language date parsing
Built for founders and operators who want a dependable AI teammate that fits existing communication workflows—no new apps, no context switching, just text.
MIT License — see LICENSE for details.
- Electron desktop app packaging research and documentation
- Added API usage tracking with daily/monthly statistics
- Added macOS permissions handler (Contacts, Automation, Accessibility, Full Disk Access)
- Enhanced dashboard API with usage analytics endpoints
- Added usage history import script for historical data
- Improved logging with structured metadata
- Fixed Apple Cocoa timestamp conversion for test message injection
- Improved backlog protection for message processing
- Added Electron deep dive documentation for future desktop app
- Added dual-agent system (Interaction + Execution agents)
- Implemented AgentMail email integration
- Added trigger/automation system for scheduled tasks
- Enhanced web search capabilities
- Event-driven typing indicators
- Duplicate message prevention cache
- Improved conversation summarization
- Private API read receipt support
- Tool registry system with extensible tools
- Reminder service with natural language parsing
- Context service for user memory/preferences
- Rate limiting and request management
- BlueBubbles webhook integration
- Claude 3.5 Sonnet/Haiku support
- Basic conversation history
- Health monitoring endpoints
- Initial release
- Basic iMessage ↔ Claude integration
- PostgreSQL + Redis infrastructure
- Express server with WebSocket support
TEXTMYAGENT
Your AI assistant, one text away.