opencode-telegram-plugin

Control OpenCode from your phone via Telegram. Send prompts, manage sessions, run shell commands, approve permissions, and execute any OpenCode slash command -- all from a Telegram chat.

Installation

From npm (recommended)

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-telegram-plugin"]
}

Or install globally in ~/.config/opencode/opencode.json.

OpenCode will automatically install the plugin using Bun.

Manual install

Copy telegram-plugin.ts to your plugins directory:

# Global
cp telegram-plugin.ts ~/.config/opencode/plugins/

# Project-specific
cp telegram-plugin.ts .opencode/plugins/

Then add the dependency to your package.json:

{
  "dependencies": {
    "node-telegram-bot-api": "^0.66.0"
  }
}

Setup

1. Create a Telegram bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to name your bot
3. Copy the bot token BotFather gives you

2. Get your chat ID

1. Send any message to your new bot
2. Open this URL in your browser (replace <TOKEN> with your bot token):

   https://api.telegram.org/bot<TOKEN>/getUpdates

3. Find "chat":{"id":XXXXXXXX} in the response -- that number is your chat ID

3. Set environment variables

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"

4. Restart OpenCode

The plugin loads at startup. You'll receive a "Connected!" message in Telegram when it's ready.

Features

• Chat with OpenCode -- send any message as a prompt and get the full response back
• All OpenCode commands -- every built-in and custom slash command is available as /oc_<name>
• Shell commands -- run shell commands with /shell or the ! prefix
• Session management -- create, list, switch, and abort sessions
• Permission forwarding -- tool permission requests are forwarded to Telegram with yes/always/no options; reply with YES, ALWAYS, or NO to respond. Auto-denies after 5 minutes
• File diff view -- see what files were changed in the current session
• Auto-discovery -- custom commands defined in .opencode/commands/ or opencode.json are automatically registered in the Telegram bot menu at startup
• Long message handling -- responses are split to fit Telegram's 4096 character limit
• Error notifications -- session errors are forwarded to Telegram

Commands

Session management

| Command | Description | |---------|-------------| | /start | Show help and all available commands | | /new [title] | Create a new session | | /sessions | List recent sessions | | /switch <id> | Switch to a session by ID prefix | | /status | Show current session info | | /abort | Abort the running task | | /diff | Show files changed in the session | | /messages | Show the last 5 messages | | /commands | List all available OpenCode commands |

Shell

| Command | Description | |---------|-------------| | /shell <cmd> | Run a shell command | | !<cmd> | Inline shell (e.g. !git status) |

OpenCode built-in commands

All OpenCode slash commands are available with the /oc_ prefix:

| Command | Maps to | |---------|---------| | /oc_undo | /undo -- revert last message and file changes | | /oc_redo | /redo -- restore undone message | | /oc_compact | /compact -- summarize/compact the session | | /oc_share | /share -- share the session | | /oc_unshare | /unshare -- unshare the session | | /oc_init | /init -- create or update AGENTS.md | | /oc_models | /models -- list available models | | /oc_help | /help -- show OpenCode help |

Custom commands

Any custom commands you define in .opencode/commands/ or your opencode.json config are automatically discovered and registered. For example, if you have a /test command, it becomes /oc_test in Telegram.

Custom commands can accept arguments:

/oc_test --coverage

Permissions

When OpenCode needs permission to execute a tool (file edits, bash commands, etc.), the request is forwarded to Telegram with details about the tool. You can respond by:

• Replying to the permission message with:
  • YES or Y - Approve once
  • ALWAYS or A - Always allow this pattern
  • NO or N - Deny
• Sending YES, ALWAYS, or NO without replying (applies to most recent pending request)
• Doing nothing - Requests auto-deny after 5 minutes

Use /pending to see any pending permission requests.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather | | TELEGRAM_CHAT_ID | Yes | Your Telegram chat ID |

If either variable is missing, the plugin logs a warning and disables itself.

Requirements

• OpenCode v0.1+
• Node.js 18+
• node-telegram-bot-api npm package

License

MIT