npm install tg-agentA 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.
- 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
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"
Send the following commands in Telegram:
- /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
- /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
- /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
- /login - OAuth login to a provider/logout
- - Logout from a provider
- /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.
- 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 promptsend_photo
- Images are passed as multimodal input to the model (if the model supports images)
- Agent can use / send_file tools to send local files back to Telegram (paths must be in workspace directory or uploads folder)
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.
`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]
[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 = ""
`
- 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 directoryworkspace_mappings
- : Set independent workspace for specific chat IDs (keys are chat IDs as strings)limits.max_sessions
- : Maximum number of sessions to keep per chatlimits.max_concurrent
- : Maximum number of concurrent requestslimits.max_history_messages
- : Maximum number of history messages per sessiontimeouts
- : Timeout settings for various operations (in milliseconds)fetch.max_bytes
- : Maximum bytes for fetch tool file downloadstls.extra_ca_certs
- : Path to additional CA certificate filetls.reject_unauthorized
- : Whether to reject unauthorized TLS certificates (empty string means use system default)
Prefers local Codex OAuth credentials (written by codex login)./login openai-codex
You can also execute 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
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)url
- HTTP: Communication via HTTP requests (using )
Place Skills in the ~/.tg-agent/skills folder, and the program will automatically discover them.
- 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.~/.tg-agent/uploads
- Network errors: Check proxy configuration and TLS certificate settings.
- File upload failures: Check permissions for directory.
- Do not commit ~/.tg-agent/config.toml to the repositorytelegram.allowed_user_ids` whitelist to restrict access
- It's recommended to enable
- Sensitive information (such as API keys) is stored in the config file, keep it secure