This project provides an AI-powered Telegram agent designed to assist users in crafting witty and engaging messages, particularly for romantic or social conversations. It targets individuals seeking to enhance their communication skills or automate message generation within Telegram, offering benefits like time savings and improved conversational quality through AI-driven suggestions and content retrieval.

How It Works

The system employs a hybrid architecture: a TypeScript CLI agent communicates with a Python-based Telegram API Bridge (built with FastAPI and Telethon), which interfaces directly with Telegram servers. AI capabilities are powered by Claude Sonnet for generating response suggestions and enhancing message tone. Knowledge retrieval and content sourcing, including over 500 pickup lines and dating guides, are handled by Nia's semantic search engine, allowing users to query curated databases or potentially their own indexed content.

Quick Start & Requirements

1. Clone Repository: git clone https://github.com/arlanrakh/talk-to-girlfriend-ai.git
2. Install Dependencies: Use uv sync for Python and bun install for the agent.
3. Configure Environment: Copy .env.example to .env and populate it with required API credentials: TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_SESSION_STRING, AI_GATEWAY_API_KEY, and NIA_API_KEY. A NIA_CODEBASE_SOURCE UUID is also needed. Telegram API credentials can be obtained from my.telegram.org/apps.
4. Start Bridge: Run python telegram_api.py to launch the FastAPI server.
5. Run Agent: Navigate to the agent directory and execute bun run dev.

Highlighted Details

• Provides AI-powered smart reply suggestions based on conversation context.
• Offers semantic search over 500+ pickup lines, dating guides, and conversation tips via Nia.
• Features message enhancement to transform mundane text into witty or flirty exchanges.
• Enables full Telegram interaction via natural language, including reading, sending, reacting, editing, and deleting messages.
• Can function as a standalone Multi-Client Protocol (MCP) server, exposing over 60 Telegram tools for integration with applications like Claude Desktop or Cursor.

Maintenance & Community

The project is primarily maintained by arlanrakh, with contributions noted from chigwell for the telegram-mcp component. No specific community channels (like Discord or Slack) or roadmap details are provided in the README.

Licensing & Compatibility

The project is licensed under the Apache 2.0 license. This license is generally permissive, allowing for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

The Telegram session string grants full access to a user's account and must be protected; committing it or the .env file is a security risk. Setup requires obtaining API keys from multiple external services (Telegram, Vercel AI Gateway, Nia), and managing dependencies across both Python and Node.js/Bun environments. The project's specific focus on "talking to a girlfriend" suggests a niche application, and its reliance on external AI and search services means performance and availability are subject to those providers.