tg-agent

A locally running Telegram bot that supports multiple LLM providers (Codex, Claude Code, Antigravity, etc.) with both account login (OAuth) and API key authentication. Handles conversations, tool calls, and session management. Supports multiple sessions, session persistence, /stop cancellation, and tool status updates. Suitable for long-term running on macOS.

Features

• Telegram private chat and group interactions (supports forum topics)
• Multi-session management: /new /list /use /close /reset
• Session persistence: saved to ~/.tg-agent/tg-sessions by default
• Cancellable during execution: /stop
• Automatic Markdown rendering: prefers MarkdownV2, falls back to Markdown, then plain text
• Multiple Provider / Model selection (supports Codex / antigravity / Gemini CLI, etc.)
• OAuth login and logout (/login, /logout)
• Tool calls: built-in fetch, optional MCP (HTTP/stdio)
• Multimedia file support: images, documents, audio, video, voice, video notes
• Proxy support: model and tool requests can be configured separately
• Workspace management: set independent working directories for different chats

Quick Start

1. Install globally

npm install -g tg-agent

2. Run

tg-agent

On first run, you'll be prompted to enter telegram.bot_token which will be written to ~/.tg-agent/config.toml.

3. Configuration (optional)

You can manually create or edit ~/.tg-agent/config.toml with a minimal example:

[telegram]
bot_token = "YOUR_BOT_TOKEN"

Usage

Send the following commands in Telegram:

Session Management

• /new [title] - Create a new session
• /list - List all sessions
• /use <id> - Switch to a specific session
• /close [id] - Close a session (defaults to current session)
• /reset - Clear current session history
• /stop - Cancel the currently processing request

Models and Providers

• /providers - List all available providers
• /models [provider] - List models for a provider (shows current session's provider if not specified)
• /provider <name> - Set the provider for current session
• /model <provider>/<model> - Set the model for current session

Workspace and Tools

• /workspace [path] - View or set the workspace directory for current session
• /mcp - View MCP servers and connection status
• /mcp refresh - Refresh MCP catalog
• /status - View current session's model and workspace settings

Authentication

• /login <provider> - OAuth login to a provider
• /logout <provider> - Logout from a provider

Help

• /start or /help - Show command help

Note: By default, only private chats (DM) are supported. To use in groups, configure telegram.allowed_user_ids whitelist.

Images and Files

• Send images, documents, audio, video, voice, or video notes directly to the bot. Files are saved to ~/.tg-agent/uploads and automatically attached to the prompt
• Images are passed as multimodal input to the model (if the model supports images)
• Agent can use send_photo / send_file tools to send local files back to Telegram (paths must be in workspace directory or uploads folder)

Configuration

All configuration is stored in ~/.tg-agent/config.toml. On first startup, you'll be prompted to enter telegram.bot_token, other fields use default values.

Complete Configuration Example

[telegram]
bot_token = "YOUR_BOT_TOKEN"
allowed_user_ids = ["123456789"]
parse_mode = ""

[model]
provider = "openai-codex"
model = "gpt-5.2"
openai_api_key = ""

[paths]
workspace_dir = ""
session_dir = "~/.tg-agent/tg-sessions"

[workspace_mappings]
# Set independent workspace for specific chat IDs
# "-123456789" = "~/projects/project-a"

[limits]
max_sessions = 5
max_concurrent = 5
max_history_messages = 40
max_output_tokens = 0

[timeouts]
model_timeout_ms = 60000
model_timeout_stream_ms = 300000
fetch_timeout_ms = 60000

[fetch]
max_bytes = 200000
proxy_url = ""

[proxy]
url = ""

[auth]
codex_home = "~/.codex"

[logging]
agent_events = true
agent_stream = true

[system]
prompt = "You are running in user's personal computer or VPS, using telegram bot to interact with user. Be concise and practical."

[tls]
extra_ca_certs = ""
reject_unauthorized = ""

Configuration Options

• telegram.allowed_user_ids: List of user IDs allowed to use the bot (empty list means all users are allowed)
• paths.workspace_dir: Default workspace directory
• workspace_mappings: Set independent workspace for specific chat IDs (keys are chat IDs as strings)
• limits.max_sessions: Maximum number of sessions to keep per chat
• limits.max_concurrent: Maximum number of concurrent requests
• limits.max_history_messages: Maximum number of history messages per session
• timeouts: Timeout settings for various operations (in milliseconds)
• fetch.max_bytes: Maximum bytes for fetch tool file downloads
• tls.extra_ca_certs: Path to additional CA certificate file
• tls.reject_unauthorized: Whether to reject unauthorized TLS certificates (empty string means use system default)

Codex Authentication

Prefers local Codex OAuth credentials (written by codex login). You can also execute /login openai-codex in Telegram to save credentials to ~/.tg-agent/auth.json. If you see missing permissions or cannot find credentials at runtime, re-run:

codex login

MCP Configuration

Add MCP servers in the same ~/.tg-agent/config.toml:

[mcp_servers.context7]
type = "stdio"
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

[mcp_servers.Notion]
url = "https://mcp.notion.com/mcp"

Two types of MCP servers are supported:

• stdio: Communication via standard input/output (using command and args)
• HTTP: Communication via HTTP requests (using url)

Skills Configuration

Place Skills in the ~/.tg-agent/skills folder, and the program will automatically discover them.

Troubleshooting

• Bad Request: can't parse entities: Text doesn't conform to MarkdownV2 rules. The implementation automatically falls back to Markdown or plain text.
• No Codex OAuth credentials found: Run codex login or use /login openai-codex.
• insufficient permissions: Check organization/project permissions or OAuth scope.
• Network errors: Check proxy configuration and TLS certificate settings.
• File upload failures: Check permissions for ~/.tg-agent/uploads directory.

Security

• Do not commit ~/.tg-agent/config.toml to the repository
• It's recommended to enable telegram.allowed_user_ids whitelist to restrict access
• Sensitive information (such as API keys) is stored in the config file, keep it secure