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

``bash
npm install -g tg-agent
`

2. Run

`bash
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:

`toml
[telegram]
bot_token = "YOUR_BOT_TOKEN"
`

Usage

Send the following commands in Telegram:

$3

- /new [title] - Create a new session
- /list - List all sessions
- /use - 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

$3

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

$3

- /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

$3

- /login - OAuth login to a provider
- /logout - Logout from a provider

$3

- /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.

$3

- 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.

$3

`toml
[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

[tls]
extra_ca_certs = ""
reject_unauthorized = ""
`

$3

- 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:

`bash
codex login
`

MCP Configuration

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

`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