OpenCode Chat Assistant is a secure Discord bot client for OpenCode CLI that runs on your local machine.
Run AI coding tasks, monitor progress, switch models, and manage sessions from Discord.
No open ports, no exposed APIs. The bot connects outward to the Discord Gateway and your local OpenCode server only.
Platforms: macOS, Windows, Linux
Languages: English (en), Deutsch (de), Español (es), Русский (ru), 简体中文 (zh)
When you (or another agent) replies to a session from the OpenCode TUI/GUI while the bot is running, the bot detects and forwards those replies to Discord automatically. No messages are missed, even if they happen outside the bot.
- Message Poller — REST polling detects assistant replies created outside the bot
- Question Poller — catches pending questions that SSE events may miss
- Deduplication — prevents duplicate delivery between SSE and polling
- Auto SSE Subscription — automatically subscribes to server events at startup
The model picker paginates the model list with configurable page size (bot.modelsListLimit) to handle users with many models.
Assistant replies, question prompts, permission requests, and status messages use Discord markdown formatting for better readability.
Users who git clone this repo get the same interactive setup wizard on first launch that npx users get. No need to manually create config.yaml.
Core features:
- Remote coding — send prompts to OpenCode from anywhere, receive complete results with code sent as files
- Session management — create new sessions or continue existing ones, just like in the TUI
- Live status — pinned embed with current project, model, context usage, and changed files list, updated in real time
- Model switching — pick models from OpenCode favorites and recent history directly in the chat
- Agent modes — switch between Plan and Build modes on the fly
- Model variants — select reasoning mode variants per model
- Custom Commands — run OpenCode custom commands (and built-ins like
init/review) from a menu - Skills — browse and run agent skills from Discord
- Interactive Q&A — answer agent questions and approve permissions via buttons
- File attachments — send images, PDF documents, and text-based files to OpenCode
- Context control — compact context when it gets too large, right from the chat
- Input flow control — only one interactive flow active at a time, with contextual hints
- Security — role-based access for channels; DM whitelist for direct messages
- Localization — UI in 5 languages (
bot.locale)
Planned features are listed in PRODUCT.md.
- Node.js 20+ — download
- OpenCode — install from opencode.ai or GitHub
opencode serveThe bot connects to the OpenCode API at
http://localhost:4096by default.
git clone https://github.com/IH-Chung/opencode-chat-assistant.git
cd opencode-chat-assistant
npm install
npm run devOn first launch, an interactive wizard will guide you through the configuration:
- Language — select your preferred UI language
- Bot Token — paste the token from Discord Developer Portal
- Server ID — your Discord server ID (for slash command registration)
- Role IDs — roles that can use the bot in channels
- User IDs — (optional) users who can DM the bot
- API URL — OpenCode server URL (default:
http://localhost:4096) - Server credentials — username and password (optional)
The config.yaml file is saved to the project root. Subsequent launches skip the wizard.
For detailed Discord setup instructions, see docs/DISCORD_SETUP.md.
| Platform | Status |
|---|---|
| macOS | Fully supported |
| Windows | Fully supported |
| Linux | Fully supported (tested on Ubuntu 24.04 LTS) |
| Command | Description |
|---|---|
/status |
Server health, current project, session, and model info |
/new |
Create a new session |
/abort |
Abort the current task |
/sessions |
Browse and switch between recent sessions |
/projects |
Switch between OpenCode projects |
/rename |
Rename the current session |
/commands |
Browse and run custom commands |
/skills |
Browse and run agent skills |
/opencode_start |
Start the OpenCode server remotely |
/opencode_stop |
Stop the OpenCode server remotely |
/help |
Show available commands |
Any regular text message is sent as a prompt to the coding agent. Model, agent, variant, and context controls are available via slash commands and buttons.
/opencode_startand/opencode_stopare emergency commands for restarting a stuck server while away from your computer. Under normal usage, startopencode serveyourself.
- Supported locales:
en,de,es,ru,zh - The setup wizard asks for language first
- Change locale later with
bot.locale
The config.yaml file location depends on how you run the bot:
- From source (git clone):
config.yamlin project root directory (created by setup wizard on first launch) - macOS (installed):
~/Library/Application Support/opencode-chat-assistant/config.yaml - Windows (installed):
%APPDATA%\opencode-chat-assistant\config.yaml - Linux (installed):
~/.config/opencode-chat-assistant/config.yaml
| Key | Description | Required | Default |
|---|---|---|---|
discord.token |
Bot token from Discord Developer Portal | Yes | — |
discord.serverId |
Discord server ID for slash command registration | Yes | — |
discord.allowedRoleIds |
Role IDs for channel access (YAML list or comma-separated) | No | — |
discord.allowedUserIds |
User IDs for DM access (YAML list or comma-separated) | No | — |
opencode.apiUrl |
OpenCode server URL | No | http://localhost:4096 |
opencode.username |
Server auth username | No | opencode |
opencode.password |
Server auth password | No | — |
bot.locale |
Bot UI language (supported locale code, e.g. en, de) |
No | en |
bot.sessionsListLimit |
Sessions per page in /sessions |
No | 10 |
bot.projectsListLimit |
Projects per page in /projects |
No | 10 |
bot.modelsListLimit |
Models per page in model picker | No | 10 |
bot.serviceMessagesIntervalSec |
Service messages interval (thinking + tool calls), 0 = immediate |
No | 5 |
bot.hideThinkingMessages |
Hide 💭 Thinking... service messages |
No | false |
bot.hideToolCallMessages |
Hide tool-call service messages (💻 bash ..., 📖 read ...) |
No | false |
bot.messageFormatMode |
Assistant reply formatting: markdown or raw |
No | markdown |
files.maxFileSizeKb |
Max file size (KB) to send as document | No | 100 |
server.logLevel |
Log level (debug, info, warn, error) |
No | info |
Keep your
config.yamlfile private. It contains your bot token. Never commit it to version control.
The model picker uses OpenCode local model state (favorite + recent):
- Favorites are shown first, then recent
- Models already in favorites are not duplicated in recent
- Current model is marked with
✅ - If no model is selected, OpenCode uses the agent's default model
To add a model to favorites, open OpenCode TUI (opencode), go to model selection, and press Cmd+F/Ctrl+F on the model.
The bot uses a two-tier authorization system:
- Channel access — users with a configured role (
discord.allowedRoleIds) can send prompts in server channels - DM access — specific user IDs (
discord.allowedUserIds) can interact via direct messages - Session owner lock — only one operator at a time; others see a "session busy" message
Since the bot runs locally and connects outward only (Discord Gateway + local OpenCode server), there is no external attack surface.
| Script | Description |
|---|---|
npm run dev |
Build and start |
npm run dev:watch |
Run with auto-restart on file change |
npm run build |
Compile TypeScript |
npm start |
Run compiled code |
npm run lint |
ESLint check (zero warnings policy) |
npm run format |
Format code with Prettier |
npm test |
Run tests (Vitest) |
npm run test:coverage |
Tests with coverage report |
dev:watchauto-restarts on file save — recommended during development. For production or long-running sessions, usenpm run devto avoid mid-task connection interruptions.
Bot doesn't respond to commands
- Verify
discord.tokenis valid and the bot is in your server - Verify
discord.serverIdmatches your server ID (enable Developer Mode in Discord, right-click server, Copy ID) - Check the bot has
applications.commandsscope
"OpenCode server is not available"
- Make sure
opencode serveis running - Check
opencode.apiUrl(default:http://localhost:4096)
No models in model picker
- Add models to favorites in OpenCode TUI (Ctrl+F on a model)
Commands not appearing in Discord
- Ensure slash commands are registered (bot registers on startup)
- Try restarting the bot
- Check Discord Developer Portal for command registration errors
Please follow commit and release note conventions in CONTRIBUTING.md.
This project is a fork of grinev/opencode-telegram-bot, originally created by Ruslan Grinev.
The original project provides the core architecture, bot framework, session management, and overall design. This fork evolved into a Discord-only client with enhancements (external reply sync, model pagination, markdown formatting, source-mode setup wizard, skill support).
All code in this fork was developed with AI assistance using OpenCode and Claude.
For the original upstream project, visit: https://github.com/grinev/opencode-telegram-bot
Original work by Ruslan Grinev | Fork modifications by IH-Chung