Telegram Concierge

A native macOS AI assistant that lives inside a Telegram bot you control. It reads and sends emails, searches the web, generates images, manages your calendar, transcribes voice messages, runs macOS Shortcuts, delegates coding tasks to Claude Code/Gemini CLI/Codex CLI, and remembers everything — powered by any LLM available through OpenRouter.

<p align="center"> <img src="https://img.shields.io/badge/platform-macOS%2014+-blue" alt="macOS 14+"> <img src="https://img.shields.io/badge/Swift-5.9-orange" alt="Swift 5.9"> <img src="https://img.shields.io/badge/license-MIT-green" alt="License"> </p>

---

✨ Features

🤖 AI Core

• Any LLM via OpenRouter — Gemini, Claude, GPT, Grok, and more
• Configurable reasoning effort — adjust thinking depth per model
• Full tool-use (function calling) — the LLM autonomously decides when and how to use over 30 tools
• Multimodal — understands images, PDFs, audio, and documents you send via Telegram
• Remote privacy mode — send /hide from Telegram to hide conversations and other sensitive UI on the Mac until /show is sent

🧠 Persistent Memory (FractalMind)

• Tiered chunking — conversation history is automatically archived into chunks, summarized by the LLM, and consolidated over time
• Crash-safe archival — pending chunks survive app restarts
• Semantic search — the AI can search its own memory for past conversations
• User context — learns facts about you over time and persists them across sessions
• Mind export/import — full data portability: download or restore your entire assistant state as a .mind file

📧 Email

• Gmail API (recommended) — fast, efficient, thread-aware email with OAuth2
• IMAP/SMTP — alternative for non-Gmail setups
• Full lifecycle — read, search, compose, reply, forward, download attachments, send with attachments
• Background monitoring — the AI is aware of your latest inbox activity

📅 Calendar

• View, add, edit, and delete calendar events
• Calendar context is injected into every system prompt so the AI always knows your schedule
• Export/import calendar data independently

🌐 Web

• Google search via Serper
• Web page reading via Jina
• Page image viewing — the AI can selectively download and analyze images from web pages
• File downloads — download files from any URL

🖼️ Image Generation

• Powered by Gemini (gemini-3-pro-image-preview)
• Iterative improvement — the AI can see and refine its own generated images

🎙️ Voice Transcription

• On-device transcription using WhisperKit (whisper-large-v3-turbo)
• CoreML-optimized for Apple Silicon
• Send voice messages in Telegram and the AI receives the transcript

💻 Code CLI Integration

• Delegate coding tasks to Claude Code, Gemini CLI, or Codex CLI
• Project workspace management — create, browse, read, and add files to projects
• Run the selected CLI provider with prompts and receive structured results
• Send generated files back via Telegram or email

⚡ macOS Shortcuts

• List and run any macOS Shortcut from Telegram
• Pass input and receive output programmatically

📇 Contacts

• Import contacts from .vcf (vCard) files
• Search, add, list, and delete contacts
• Used by the AI when composing emails to find addresses

⏰ Reminders & Self-Orchestration

• Set reminders with natural language
• Recurring reminders (daily, weekly, monthly, yearly)
• Self-orchestration — the AI proactively sets reminders for itself to follow up on tasks

📄 Document Handling

• Read and analyze documents (PDF, DOCX, XLSX, CSV, TXT, and more)
• Generate documents (PDF, spreadsheet, text) and send them via Telegram or email
• Multimodal analysis of images sent as documents

---

🏗️ Architecture

┌──────────────────────────────────────────────────┐
│                  Telegram User                   │
│             (messages, voice, files)             │
└─────────────────────┬────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────┐
│              TelegramBotService                  │
│          (long-polling, message dispatch)         │
└─────────────────────┬────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────┐
│            ConversationManager                   │
│    (message history, agentic loop, archival)     │
├──────────────────────────────────────────────────┤
│  OpenRouterService    │  ConversationArchive     │
│  (LLM API + context   │  Service (FractalMind    │
│   window management)  │  memory & summarization) │
└───────────┬──────────┴───────────────────────────┘
            │
            ▼
┌──────────────────────────────────────────────────┐
│               ToolExecutor                       │
│        (parallel tool dispatch, 30+ tools)       │
├──────────────────────────────────────────────────┤
│ EmailService / GmailService                      │
│ CalendarService      │ ReminderService           │
│ WebOrchestrator      │ GeminiImageService        │
│ DocumentService      │ DocumentGeneratorService  │
│ ContactsService      │ WhisperKitService         │
│ MindExportService    │ Code CLI (subprocess)     │
│ macOS Shortcuts      │ User Context Management   │
└──────────────────────────────────────────────────┘

Key Design Decisions

• Agentic loop — the LLM runs iteratively: it can call tools, observe results, then call more tools until it has a final answer
• Parallel tool execution — multiple independent tool calls are dispatched concurrently
• Dynamic context window — conversation is kept within token limits (~10k–20k) with automatic overflow archival
• Keychain storage — all API keys and secrets are stored in the macOS Keychain, never on disk
• Sandbox-aware — runs in the macOS app sandbox with network, audio input, and Apple Events entitlements

---

🛠️ Available Tools

<details> <summary><strong>📧 Email (8 IMAP tools / 2 Gmail tools)</strong></summary>

| Tool | Description | |------|-------------| | read_emails / gmailreader | Read Gmail: search/list emails, read full messages or threads, and download attachments | | search_emails | Advanced search across all folders | | send_email / gmailcomposer | Compose Gmail: send new emails, reply in-thread, or forward with attachments | | reply_email | Reply to a specific email in-thread | | forward_email | Forward emails with attachments | | get_email_thread | View full email conversation thread | | send_email_with_attachment | Send email with documents from storage | | download_email_attachment | Download email attachments for analysis |

</details> <details> <summary><strong>📅 Calendar (4 tools)</strong></summary>

| Tool | Description | |------|-------------| | view_calendar | View upcoming (and optionally past) events | | add_calendar_event | Create a new event with title, datetime, duration, notes | | edit_calendar_event | Modify an existing event | | delete_calendar_event | Remove an event |

</details> <details> <summary><strong>🌐 Web (4 tools)</strong></summary>

| Tool | Description | |------|-------------| | web_search | Search the web via Google (Serper) | | view_url | Read a web page's content and image metadata | | view_page_image | Download and view a specific image from a web page | | download_from_url | Download any file from a URL |

</details> <details> <summary><strong>📄 Documents (4 tools)</strong></summary>

| Tool | Description | |------|-------------| | read_document | Read/analyze any stored document (PDF, images, etc.) | | list_documents | List stored documents by recent usage with pagination (limit, cursor) | | generate_document | Generate PDF, spreadsheet, or text documents | | send_document_to_chat | Send a document file to the Telegram chat |

</details> <details> <summary><strong>💻 Code CLI Projects (7 tools)</strong></summary>

| Tool | Description | |------|-------------| | manage_projects | Create a new Code CLI project workspace or list existing ones | | browse_project | View project file tree | | read_project_file | Read a file from a project | | add_project_files | Copy local files into a project | | run_claude_code | Execute the selected Code CLI provider with a prompt in a project | | send_project_result | Send project files via Telegram or email |

</details>

[!TIP] To inspect Code CLI workspaces on disk, use the folder button in the main chat header (ContentView). It opens the projects folder directly in Finder, where you can also delete project folders manually.

<details> <summary><strong>🧠 Memory & Context (4 tools)</strong></summary>

| Tool | Description | |------|-------------| | view_conversation_chunk | Browse archived conversation history | | add_to_user_context | Save a learned fact about the user | | remove_from_user_context | Remove outdated information | | rewrite_user_context | Rewrite the full user context |

</details> <details> <summary><strong>⚡ System (5 tools)</strong></summary>

| Tool | Description | |------|-------------| | set_reminder | Schedule a one-time or recurring reminder | | list_reminders | View pending reminders | | delete_reminder | Cancel a reminder | | shortcuts | List available macOS Shortcuts or run one with optional input | | generate_image | Generate an image from a text prompt | | find_contact | Search contacts by name or email | | add_contact | Add a new contact | | list_contacts | List all contacts |

</details>

---

📦 Project Structure

TelegramConcierge/
├── TelegramConciergeApp.swift      # App entry point
├── Models/
│   ├── Message.swift