{"_id":"@adrianlzt/opencode-telegram","name":"@adrianlzt/opencode-telegram","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@adrianlzt/opencode-telegram","version":"0.1.0","description":"OpenCode plugin to interact via Telegram","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit"},"dependencies":{"dotenv":"^16.4.7","jsonc-parser":"^3.3.1","telegraf":"^4.16.3"},"devDependencies":{"@opencode-ai/plugin":"0.0.0-beta-202603271537","@types/node":"^25.5.0","tsup":"^8.4.0","tsx":"^4.21.0","typescript":"^5.7.0"},"gitHead":"8b33dc3d3cb8d32471b53b2e3c0ded000ce3a835","_id":"@adrianlzt/opencode-telegram@0.1.0","_nodeVersion":"25.8.2","_npmVersion":"11.12.1","dist":{"integrity":"sha512-db+FeuxOoAq1UEQDZY5EEZTnrTux7CBcbZyP0acKxn4PH/ZPZ69JX1wfuyt5lOviCCyTBjLRe6LCSXaHDjrDEA==","shasum":"88e5567d05825b2a95753f140a6c12be4e8a8f44","tarball":"https://registry.npmjs.org/@adrianlzt/opencode-telegram/-/opencode-telegram-0.1.0.tgz","fileCount":15,"unpackedSize":2154889,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC2O/QtrwYzNerLJalmPq6YTPyBmCYvnDXqpnMtQpo+XQIhAMg4XYl1CRGilxr98ENDMUXth7IW6CZbWWvVlZdHau3G"}]},"_npmUser":{"name":"adrianlzt","email":"adrianlzt@gmail.com"},"directories":{},"maintainers":[{"name":"adrianlzt","email":"adrianlzt@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-telegram_0.1.0_1774961897770_0.3267378288854379"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T12:58:17.703Z","0.1.0":"2026-03-31T12:58:17.961Z","modified":"2026-03-31T12:58:18.109Z"},"maintainers":[{"name":"adrianlzt","email":"adrianlzt@gmail.com"}],"description":"OpenCode plugin to interact via Telegram","readme":"# opencode-telegram\n\nOpenCode plugin to interact with the AI agent via Telegram.\n\n## What it does\n\nThe plugin listens to OpenCode events and forwards them to your Telegram:\n\n| Event | Behavior |\n|---|---|\n| `permission.asked` | Sends the permission details with context (diff, file, tool info) and three inline buttons: Allow once, Allow always, Reject. |\n| `session.idle` | Sends the last assistant message. Reply to continue the session. |\n| `session.error` | Sends the error message. Reply to continue the session. |\n| `question.asked` | Sends the questions. Reply to provide answers. |\n\nOnly messages from the configured `recipientChatId` are processed.\n\n### Long messages\n\nIf a message exceeds Telegram's text limit (4096 characters), the full content is sent as a `.md` file attachment instead. A summary text message is sent alongside it.\n\n### Voice messages\n\nYou can send voice notes to the bot. Telegram does not provide built-in transcription, so the agent receives a fallback message indicating a voice message was sent but could not be transcribed.\n\n## Prerequisites\n\n- [OpenCode](https://opencode.ai/) installed\n- A Telegram bot (create one via [@BotFather](https://t.me/BotFather))\n- Your bot token and the chat ID to send notifications to\n\n## Installation\n\n### Option 1: npm (recommended)\n\n1. Install dependencies and build:\n\n```bash\ncd opencode-telegram\nnpm install\nnpm run build\n```\n\n2. Add to your OpenCode config (`opencode.json` or `~/.config/opencode/opencode.json`):\n\n```json\n{\n  \"plugin\": [\"opencode-telegram\"]\n}\n```\n\n### Option 2: Local file\n\n1. Build the plugin:\n\n```bash\ncd opencode-telegram\nnpm install\nnpm run build\n```\n\n2. Copy the built file to your plugin directory:\n\n```bash\ncp dist/index.js ~/.config/opencode/plugins/telegram.js\n```\n\n3. Create `~/.config/opencode/package.json` with the required dependency:\n\n```json\n{\n  \"dependencies\": {\n    \"telegraf\": \"^4.16.3\"\n  }\n}\n```\n\nOpenCode will load plugins from `~/.config/opencode/plugins/` automatically.\n\n## Configuration\n\nConfiguration can be set via a JSON config file, environment variables, or a `.env` file. Environment variables take precedence over the config file.\n\n### Config file (recommended)\n\nCreate `~/.config/opencode/notification-telegram.jsonc`:\n\n```jsonc\n{\n  \"bot_token\": \"your_bot_token\",\n  \"recipient_chat_id\": \"145264105\",\n  // \"enabled\": true\n}\n```\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `TELEGRAM_BOT_TOKEN` | Yes | - | Telegram bot token from @BotFather |\n| `TELEGRAM_RECIPIENT_CHAT_ID` | Yes | - | Telegram chat ID to send notifications to |\n| `TELEGRAM_ENABLED` | No | `true` | Set to `false` to start with notifications paused |\n\n### .env file\n\nAlternatively, create a `.env` file in your project root:\n\n```bash\nTELEGRAM_BOT_TOKEN=your_bot_token\nTELEGRAM_RECIPIENT_CHAT_ID=145264105\n# TELEGRAM_ENABLED=true\n```\n\n### Finding your chat ID\n\nSend any message to your bot on Telegram, then visit:\n```\nhttps://api.telegram.org/bot<TOKEN>/getUpdates\n```\nYour chat ID is the `chat.id` field in the response.\n\n## Pausing / Resuming\n\nThe plugin can be toggled at runtime without restarting OpenCode.\n\n### Config default\n\nSet `\"enabled\": false` in `notification-telegram.jsonc` (or `TELEGRAM_ENABLED=false` as env var) to start with notifications paused.\n\n### Runtime toggle\n\nType these commands in the OpenCode TUI:\n\n- `/telegram-pause` — suppress all Telegram notifications\n- `/telegram-resume` — re-enable Telegram notifications\n\nThese commands are intercepted by the plugin and never reach the LLM.\n\n## How It Works\n\nThe plugin uses Telegraf's long-polling to receive inbound messages. No public URL or webhook setup needed.\n\n```\nOpenCode Agent\n    |\n    |-- session.idle --> Send last message to Telegram\n    |-- session.error --> Send error to Telegram\n    |-- permission.asked --> Send context + buttons to Telegram\n    |-- question.asked --> Send questions to Telegram\n    |\n    v\nYour Telegram (chat with the bot)\n    |\n    |-- Send text --> Forwarded as new prompt to active session\n    |-- Send voice note --> Fallback message sent to agent\n    |-- Click \"Allow once\" --> Approve permission for this request\n    |-- Click \"Allow always\" --> Approve permission for this session\n    |-- Click \"Reject\" --> Deny the permission\n    |\n    v\nOpenCode Agent continues\n```\n\n## Logs\n\nThe plugin writes logs to `~/.local/share/opencode-telegram/plugin.log`. Check there for debugging.\n\n## Troubleshooting\n\n### Plugin doesn't load\n\n- Check that your config file or env vars are set correctly\n- Check the log file for configuration error messages\n- Ensure `telegraf` is installed\n\n### Messages not received\n\n- Check the log file for error messages\n- Verify your bot token is correct: `https://api.telegram.org/bot<TOKEN>/getMe`\n- Ensure the recipient chat ID matches your chat with the bot\n- Only messages from the configured `recipientChatId` are processed\n\n### Permission buttons don't work\n\n- Check the log file for \"No pending permission found\" warnings\n- This can happen if the permission expired before you clicked the button\n- Permissions have a timeout; if the agent moved on, the button is stale\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f8a6efef7f3744d828a9e0efde71ddd0"}