From c0e82369cd569cf5664d3a292e0ba8512f14fd59 Mon Sep 17 00:00:00 2001 From: alexanxin Date: Wed, 25 Mar 2026 17:05:14 +0100 Subject: [PATCH] Update README with vision, badges, and cover image --- README.md | 157 +++++++++++++----------------------------------------- 1 file changed, 37 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index 974271e..cdcceb5 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -

-

opencode-dispatch

-

+# 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.

- Control opencode from Telegram — like Claude's Dispatch, but for opencode. + opencode-dispatch Cover

@@ -12,15 +12,26 @@ opencode

-

- Setup · How It Works · Use Cases · Security · Troubleshooting -

- --- -> 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