perso/opencode-dispatch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with vision, badges, and cover image

Browse Source
This commit is contained in:
alexanxin
2026-03-25 17:05:14 +01:00
parent d2b2d219b1
commit c0e82369cd
1 changed files with 37 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -120
View File
@@ -1,9 +1,9 @@
<p align="center">
<h1> opencode-dispatch</h1>
</p>
# Beyond the Terminal: The Road to a Truly Autonomous AI Agent
**opencode-dispatch** is a secure Telegram bridge for the [opencode CLI](https://opencode.ai). It brings the power of a 120K-star, self-hosted AI agent to your pocket—giving you "Dispatch-style" remote access without the corporate subscription or vendor lock-in.
<p align="center">
<strong>Control opencode from Telegram — like Claude's Dispatch, but for opencode.</strong>
<img src="https://pbs.twimg.com/media/HEREOD6WcAAaG7_?format=jpg&name=4096x4096" alt="opencode-dispatch Cover" width="700">
</p>
<p align="center">
@@ -12,15 +12,26 @@
<a href="https://opencode.ai"><img src="https://img.shields.io/badge/opencode-CLI-orange?style=for-the-badge" alt="opencode"></a>
</p>
<p align="center">
<a href="#quick-setup">Setup</a> · <a href="#how-it-works">How It Works</a> · <a href="#use-cases">Use Cases</a> · <a href="#security">Security</a> · <a href="#troubleshooting">Troubleshooting</a>
</p>
---
> I deeply appreciate what the opencode team is building. This is my small contribution to their already awesome work — making opencode accessible from anywhere via Telegram.
## Why opencode-dispatch?
Bridge your Telegram bot to the [opencode CLI](https://opencode.ai). Send messages from your phone, opencode processes them just like it would in a terminal. Perfect for when you're away from your desk but still want AI assistance.
While the industry moves toward closed, subscription-based mobile interfaces, **opencode-dispatch** stays true to the open-source ethos: **Your models, your hardware, your data.**
- **📱 Remote Autonomy:** Manage codebases, run tests, and refactor files from a Telegram chat.
- **🤖 Model Agnostic:** Connect to 75+ providers via Models.dev or run entirely local via Ollama.
- **🔒 Security First:** Built-in Telegram Chat ID locking and context isolation.
- **⚡ Lightweight:** Runs on a $5 VPS or your local machine with minimal overhead.
## The Vision: Building "OpenClaw"
This repository is more than a bridge; it's a foundational layer for a persistent, autonomous agent ecosystem. We are moving beyond stateless terminal commands toward an agent that:
1. **Remembers:** Persistent cross-session context.
2. **Acts:** Scheduled task execution and background monitoring.
3. **Learns:** A plug-and-play skills and personality registry.
---
## What You Need
@@ -34,10 +45,7 @@ Bridge your Telegram bot to the [opencode CLI](https://opencode.ai). Send messag
### Step 1: Create a Telegram Bot
1. Open Telegram and search for **@BotFather**
2. Send `/newbot`
3. Give it a name (e.g., "My opencode Bot")
4. Give it a username ending in `bot` (e.g., `my_opencode_bot`)
5. Copy the token BotFather gives you
2. Send `/newbot` and follow the prompts to get your **token**.
### Step 2: Install Dependencies
@@ -77,104 +85,25 @@ opencode serve --port 5050
### Step 5: Run the Bot
**Python:**
```bash
python bot.py
```
- **Python:** `python bot.py`
- **Node.js:** `npm start`
**Node.js:**
```bash
npm start
```
### Step 6: Chat
Open Telegram, find your bot, and send a message. opencode will receive it and respond through the bot.
## Bot Commands
### Bot Commands
| Command | Description |
|---------|-------------|
| `/start` | Welcome message and server info |
| `/help` | Usage instructions |
| `/status` | Server health, session ID, queue size |
| `/working` | Check what task is currently being processed |
| `/clear` | Clear pending messages from queue |
## How It Works
## Security Recommendations
```
Your Phone → Telegram → bot.py → opencode API (port 5050) → response → Telegram → Your Phone
```
### 1. Limit workspace access
1. You send a message to your Telegram bot
2. The bot forwards it to opencode via the server API
3. opencode processes it in your project context
4. The response comes back through the bot to your phone
Never run from your home directory (`~`) or root (`/`). opencode can access all files in the directory it's started from.
## Use Cases
### 1. Ask About Your Codebase
```
You: "What does the auth middleware in @middleware.ts do?"
opencode: "The auth middleware checks for a valid JWT token
in the Authorization header. It extracts the user ID
and attaches it to the request object."
```
### 2. Start a Task
```
You: "Add input validation to the signup form"
opencode: "I'll add validation to the signup form. I found the form in
src/components/Signup.tsx. I'll add email format validation,
password length requirements, and field presence checks."
```
### 3. Check Project Status
```
You: "Are there any failing tests?"
opencode: "I ran the test suite. 47 passing, 2 failing:
- test_checkout_flow: assertion error in calculateTotal
- test_user_profile: timeout waiting for API response"
```
### 4. Get Commit Summaries
```
You: "What changed in the last 3 commits?"
opencode: "Last 3 commits:
1. Add user profile API endpoints (2 files changed)
2. Fix payment timeout issue (1 file changed)
3. Update test fixtures for new schema (4 files changed)"
```
### 5. Quick Lookups
```
You: "What environment variables does this project need?"
opencode: "Required env vars from .env.example:
- DATABASE_URL: PostgreSQL connection string
- JWT_SECRET: Secret for token signing
- STRIPE_KEY: Stripe API key for payments"
```
## Security
### Limit workspace access
Always start opencode from a specific project folder:
```bash
cd ~/my-project # Only this folder and subfolders
opencode serve --port 5050
```
**Never** run from your home directory (`~`) or root (`/`). opencode can access all files in the directory it's started from.
### Password protect (recommended)
### 2. Password protect (Recommended)
Set a password to prevent unauthorized local access:
@@ -182,27 +111,23 @@ Set a password to prevent unauthorized local access:
OPENCODE_SERVER_PASSWORD=your-secret opencode serve --port 5050
```
Add to `.env`:
Then add to `.env`:
```env
OPENCODE_SERVER_PASSWORD=your-secret
```
### Network safety
### 3. Restrict to your Telegram account (Highly Recommended)
The server only listens on `127.0.0.1` (localhost) by default. It's not accessible from other machines on your network. Never use `--hostname 0.0.0.0` unless you know what you're doing.
To lock the bot so only YOU can use it:
### Restrict to your Telegram account (recommended)
By default the bot responds to anyone who finds it. To lock it to your account:
1. Get your chat ID: message [@userinfobot](https://t.me/userinfobot) on Telegram
1. Get your chat ID from [@userinfobot](https://t.me/userinfobot)
2. Add to `.env`:
```env
TELEGRAM_ALLOWED_CHAT_ID=your_chat_id_here
```
Others will receive: "This bot is not authorized to respond to you."
## Troubleshooting
**"Can't connect to opencode"**
@@ -214,20 +139,12 @@ Others will receive: "This bot is not authorized to respond to you."
- Make sure the bot is running (`python bot.py` or `npm start`)
**"Port already in use"**
- Another process is using port 5050
- Pick a different port: `opencode serve --port 5051`
- Update `OPENCODE_API_URL` in `.env` to match
**"opencode command not found"**
- Install the CLI: `curl -fsSL https://opencode.ai/install | bash`
- Then restart your terminal or run: `source ~/.zshrc`
## Tips for Best Results
- **Be specific**: Instead of "fix my code," say "fix the null pointer error in UserService.java"
- **One task at a time**: For complex requests, break them into smaller steps
- **Keep context**: Mention relevant files or features so opencode understands what you're referring to
- **Use /status**: Check if opencode is healthy before sending important tasks
- Install: `curl -fsSL https://opencode.ai/install | bash`
- Then run: `source ~/.zshrc`
## Contributing