clawless 0.2.0 → 0.2.1

package/README.md

@@ -1,12 +1,42 @@
-# Telegram-Gemini ACP Bridge
+# Clawless — Bring Your Own Agent (Interface + ACP)
 
-A bridge that connects a Telegram bot to the Gemini CLI using the Agent Communication Protocol (ACP). This turns Telegram into a "remote terminal" for your local Gemini agent, enabling rich tool use and persistent context.
+Clawless is an interface bridge built around one core idea: **Bring Your Own Agent**.
+
+Instead of forcing a built-in runtime, Clawless lets you keep your preferred local ACP-capable CLI (Gemini CLI by default) and adds a reliable interface layer, callbacks, and scheduling on top.
+
+Today, Telegram is the first interface adapter; more interfaces are planned.
+
+## Bring Your Own Agent (Main Value)
+
+Clawless is designed so your messaging layer and automation layer stay stable while your agent runtime can change.
+
+- Keep your preferred local agent CLI workflow
+- Keep your existing MCP tools and local files
+- Swap runtimes without rebuilding your bot integration
+- Avoid lock-in to a single all-in-one framework
+
+## Why Clawless
+
+If you have tried heavier all-in-one agent frameworks, Clawless is the minimal alternative:
+
+- **BYO-agent first**: use your preferred local ACP-capable CLI runtime
+- **Lightweight setup**: minimal glue instead of a full platform migration
+- **Local-first control**: your machine, your tools, your data flow
+- **Transport only**: interface layer is separate from the agent runtime
+
+## Interface Adapters
+
+- **Current adapter**: Telegram
+- **Planned direction**: add more interfaces without changing core agent orchestration
+- **Design goal**: keep one message context contract so new interfaces reuse queueing, callbacks, scheduler, and ACP flow
 
 ## Features
 
-- 🤖 **Telegram Bot Interface**: Interact with Gemini CLI through Telegram
-- ⌨️ **Typing Status UX**: Shows Telegram typing indicator while Gemini is processing
-- 🛠️ **Rich Tool Support**: Leverages MCP (Model Context Protocol) servers connected to Gemini CLI
+- 🔀 **Bring Your Own Agent Runtime**: Keep Telegram/callback/scheduler UX while choosing your preferred local ACP-capable CLI
+- 🔌 **Adapter-Friendly Interface Layer**: Telegram today, additional interfaces planned
+- 🤖 **Telegram (Current Adapter)**: Interact with your local agent runtime through Telegram
+- ⌨️ **Typing Status UX**: Shows Telegram typing indicator while the agent is processing
+- 🛠️ **Rich Tool Support**: Leverages MCP (Model Context Protocol) servers connected to your local CLI runtime
 - 🔒 **Privacy**: Runs on your hardware, you control data flow
 - 💾 **Persistent Context**: Maintains local session unlike standard API calls
 - 📬 **Sequential Queueing**: Processes one message at a time to avoid overlap and races
@@ -16,22 +46,22 @@ A bridge that connects a Telegram bot to the Gemini CLI using the Agent Communic
 ## Architecture
 
 ```
-┌──────────┐         ┌───────────┐         ┌─────────────┐
-│ Telegram │ ◄─────► │  Bridge   │ ◄─────► │ Gemini CLI  │
-│   User   │         │ (Node.js) │   ACP   │   (Local)   │
-└──────────┘         └───────────┘         └─────────────┘
+┌──────────────────────┐     ┌────────────────┐     ┌──────────────────────────┐
+│ Interface Adapter    │◄───►│   Clawless     │◄───►│ Local Agent.             │
+│ (Telegram now)       │     │   (Node.js)    │ ACP │ e.g. Gemini CLI (default)│
+└──────────────────────┘     └────────────────┘     └──────────────────────────┘
 ```
 
 The bridge:
-1. Receives messages from Telegram users
-2. Forwards them to the Gemini CLI via ACP (Agent Communication Protocol)
-3. Shows typing status, then sends a single final response
+1. Receives messages from the active interface adapter (Telegram today)
+2. Forwards them to **your configured local agent CLI** via ACP (Agent Communication Protocol)
+3. Sends interface-appropriate progress/status updates, then returns a single final response
 
 ## Prerequisites
 
 - **Node.js** 18.0.0 or higher
-- **Gemini CLI** installed and configured with ACP support
-- **Telegram Bot Token** from [@BotFather](https://t.me/BotFather)
+- **A local ACP-capable agent CLI** installed and configured (Gemini CLI is the default setup)
+- **Telegram Bot Token** from [@BotFather](https://t.me/BotFather) for the current Telegram adapter
 
 ## Installation
 
@@ -73,6 +103,8 @@ After install, the package exposes a CLI command:
 clawless
 ```
 
+> Note: the binary name is currently `clawless` for compatibility, while the project name is Clawless.
+
 Local development alternatives:
 
 ```bash
@@ -193,7 +225,7 @@ pm2 save
 | `CALLBACK_PORT` | No | 8788 | Bind port for callback server |
 | `CALLBACK_AUTH_TOKEN` | No | - | Optional bearer/token guard for callback endpoint |
 | `CALLBACK_MAX_BODY_BYTES` | No | 65536 | Maximum accepted callback request body size |
-| `AGENT_BRIDGE_HOME` | No | ~/.clawless | Home directory for Gemini Bridge runtime files |
+| `AGENT_BRIDGE_HOME` | No | ~/.clawless | Home directory for Clawless runtime files |
 | `MEMORY_FILE_PATH` | No | ~/.clawless/MEMORY.md | Persistent memory file path injected into Gemini prompt context |
 | `MEMORY_MAX_CHARS` | No | 12000 | Max memory-file characters injected into prompt context |
 | `SCHEDULES_FILE_PATH` | No | ~/.clawless/schedules.json | Persistent scheduler storage file |
@@ -229,7 +261,7 @@ curl -sS -X POST "http://127.0.0.1:8788/callback/telegram" \
 
 ### Scheduler API
 
-The bridge includes a built-in cron scheduler that allows you to schedule tasks to be executed through Gemini CLI:
+The bridge includes a built-in cron scheduler that allows you to schedule tasks to be executed through your configured local agent CLI:
 
 - Schedules are persisted to disk and automatically reloaded on restart.
 - Default storage path: `~/.clawless/schedules.json` (override with `SCHEDULES_FILE_PATH`).
@@ -256,7 +288,7 @@ curl -X POST http://127.0.0.1:8788/api/schedule \
   }'
 ```
 
-When a scheduled job runs, it executes the message through Gemini CLI and sends the response to your Telegram chat.
+When a scheduled job runs, it executes the message through your configured local agent runtime and sends the response to your Telegram chat.
 
 **Ask Gemini to create schedules naturally:**
 - "Remind me to take a break in 30 minutes"
@@ -268,10 +300,10 @@ See [SCHEDULER.md](SCHEDULER.md) for complete API documentation.
 ### Persistent Memory File
 
 - The bridge ensures a memory file exists at `~/.clawless/MEMORY.md` on startup.
-- Gemini is started with include access to both `~/.clawless` and your full home directory (`~/`).
+- The configured local agent CLI is started with include access to both `~/.clawless` and your full home directory (`~/`).
 - ACP session setup uses the required `mcpServers` field with an empty array and relies on Gemini CLI runtime defaults for MCP/skills loading.
 - Each prompt includes memory instructions and current `MEMORY.md` content.
-- When asked to memorize/remember something, Gemini is instructed to append new notes under `## Notes`.
+- When asked to memorize/remember something, the agent is instructed to append new notes under `## Notes`.
 
 ### Timeout Tuning
 
@@ -296,28 +328,31 @@ The `MAX_RESPONSE_LENGTH` prevents memory issues with very long responses:
 1. **User sends a message** via Telegram
 2. **Bridge queues** the message if another request is in progress
 3. **Worker dequeues** the next message when prior processing completes
-4. **Gemini run starts** and typing status is shown in Telegram
-5. **Single final reply** is sent when Gemini finishes
+4. **Agent run starts** and typing status is shown in Telegram
+5. **Single final reply** is sent when the run finishes
 
 ### Queueing Behavior
 
 The bridge uses a single-worker in-memory queue:
-- Prevents overlapping Gemini runs
+- Prevents overlapping agent runs
 - Preserves message order
 - Avoids duplicate-edit/fallback races from message updates
 
 ## Advantages Over Standard API Bots
 
-1. **Persistent Context**: The Gemini CLI maintains a local session, unlike stateless API calls
-2. **Local File Access**: Can access files on your server if configured
-3. **MCP Tool Integration**: Automatically uses tools from connected MCP servers (Calendar, Database, etc.)
-4. **Privacy Control**: Runs on your hardware, you control data processing
-5. **Custom Configuration**: Use your specific Gemini CLI setup and preferences
+1. **BYO-Agent Flexibility**: Keep the same bridge while choosing or changing your local CLI runtime
+2. **Persistent Context**: The local agent CLI maintains a local session, unlike stateless API calls
+3. **Local File Access**: Can access files on your server if configured
+4. **MCP Tool Integration**: Uses tools from connected MCP servers (Calendar, Database, etc.)
+5. **Privacy Control**: Runs on your hardware, you control data processing
+6. **Custom Configuration**: Use your specific local CLI setup and preferences
 
 ## Troubleshooting
 
 ### Bot doesn't respond
 
+For the default Gemini CLI setup:
+
 1. Check if Gemini CLI is installed:
 ```bash
 which gemini
@@ -347,22 +382,29 @@ If you see "429 Too Many Requests" errors:
 ### Project Structure
 
 ```
-RemoteAgent/
-├── index.ts              # Main bridge application
+Clawless/
+├── index.ts                        # Main bridge application
+├── bin/
+│   └── cli.ts                      # CLI entrypoint
 ├── messaging/
-│   └── telegramClient.ts # Telegram adapter implementing neutral message context
-├── package.json          # Node.js dependencies
-├── ecosystem.config.json # PM2 configuration
-├── .env.example          # Environment variables template
-├── .env                  # Your local configuration (not in git)
-└── README.md            # This file
+│   └── telegramClient.ts           # Telegram adapter
+├── scheduler/
+│   ├── cronScheduler.ts            # Schedule persistence + cron orchestration
+│   └── scheduledJobHandler.ts      # Scheduled run execution logic
+├── acp/
+│   ├── tempAcpRunner.ts            # Isolated ACP run helper
+│   └── clientHelpers.ts            # ACP helper utilities
+├── package.json                    # Node.js dependencies
+├── ecosystem.config.json           # PM2 configuration
+├── clawless.config.example.json # CLI config template
+└── README.md                       # This file
 ```
 
 ### Adding Features
 
 The codebase is designed to be simple and extensible:
 - Core queue + ACP logic is in `index.ts`
-- Messaging-platform specifics live in `messaging/telegramClient.ts`
+- Interface-specific messaging logic lives in `messaging/telegramClient.ts`
 - New bot platforms can implement the same message context shape (`text`, `startTyping()`, `sendText()`)
 - Error handling is centralized
 - Rate limiting logic is configurable
@@ -401,4 +443,4 @@ For issues and questions:
 
 ---
 
-**Note**: This bridge requires a working Gemini CLI installation with ACP support. Ensure your CLI is properly configured before running the bridge.
+**Note**: This bridge requires a working local ACP-capable CLI (Gemini CLI is the default setup). Ensure your CLI is properly configured before running the bridge.

package/SCHEDULER.md

@@ -1,14 +1,14 @@
 # Scheduler API Documentation
 
-The Clawless now includes a cron scheduler API that allows you to schedule tasks to be executed through Gemini CLI at specific times or on a recurring basis.
+Clawless includes a cron scheduler API that allows you to schedule tasks to be executed through your local agent CLI at specific times or on a recurring basis (Gemini CLI by default).
 
 ## Overview
 
 When a scheduled job runs:
-1. The scheduled message is sent to a standalone Gemini CLI session
-2. Gemini processes the message and generates a response
-3. The response is sent back to your Telegram bot
-4. The result appears in your Telegram chat
+1. The scheduled message is sent to a standalone local agent CLI session
+2. The agent processes the message and generates a response
+3. The response is sent back through the active interface adapter
+4. With the current Telegram adapter, the result appears in your Telegram chat
 
 Schedules are persisted to disk and reloaded on startup. By default the file is `~/.clawless/schedules.json` and can be overridden via `SCHEDULES_FILE_PATH`.
 
@@ -43,7 +43,7 @@ curl -X POST http://127.0.0.1:8788/api/schedule \
 **Request Body:**
 ```json
 {
-  "message": "The prompt to send to Gemini CLI",
+  "message": "The prompt to send to your local agent CLI",
   "description": "Optional description of the schedule",
   "cronExpression": "0 9 * * *"
 }
@@ -83,7 +83,7 @@ curl -X POST http://127.0.0.1:8788/api/schedule \
 **Request Body:**
 ```json
 {
-  "message": "The prompt to send to Gemini CLI",
+  "message": "The prompt to send to your local agent CLI",
   "description": "Optional description",
   "oneTime": true,
   "runAt": "2026-02-13T15:30:00Z"
@@ -180,39 +180,39 @@ curl -X DELETE http://127.0.0.1:8788/api/schedule/schedule_1707835800000_abc123
 }
 ```
 
-## Using with Gemini CLI
+## Using with Your Local CLI (Default: Gemini)
 
-The Gemini CLI is aware of the scheduler API through the system prompt. You can ask Gemini to create schedules naturally:
+The configured local CLI is aware of the scheduler API through the system prompt. With the default setup, you can ask Gemini to create schedules naturally:
 
 **Examples:**
 
 1. **"Remind me to take a break in 30 minutes"**
-   - Gemini will create a one-time schedule
+  - The agent will create a one-time schedule
 
 2. **"Check my calendar every morning at 9am and send me a summary"**
-   - Gemini will create a recurring schedule with cron expression `0 9 * * *`
+  - The agent will create a recurring schedule with cron expression `0 9 * * *`
 
 3. **"Every Friday at 5pm, remind me to review my weekly goals"**
-   - Gemini will create a recurring schedule with cron expression `0 17 * * 5`
+  - The agent will create a recurring schedule with cron expression `0 17 * * 5`
 
 4. **"List my scheduled tasks"**
-   - Gemini will query the schedule API and show you all active schedules
+  - The agent will query the schedule API and show you all active schedules
 
 5. **"Cancel the calendar summary schedule"**
-   - Gemini will find and delete the matching schedule
+  - The agent will find and delete the matching schedule
 
 ## How It Works
 
-1. When you ask Gemini to create a schedule, it will:
+1. When you ask the agent to create a schedule, it will:
    - Parse your request to determine timing (cron expression or specific date/time)
    - Call the scheduler API with appropriate parameters
    - Confirm the schedule was created
 
 2. When the scheduled time arrives:
    - The scheduler executes the job
-   - The message is sent to a new Gemini CLI session
-   - Gemini processes the message (can use tools, access files, etc.)
-   - The response is sent to your Telegram chat
+  - The message is sent to a new local CLI session
+  - The agent processes the message (can use tools, access files, etc.)
+  - The response is sent to the active interface destination (Telegram with current adapter)
 
 3. For recurring schedules:
    - The job runs according to the cron expression
@@ -226,9 +226,9 @@ The Gemini CLI is aware of the scheduler API through the system prompt. You can
 ## Notes
 
 - Schedules are stored in memory and will be lost if the bridge restarts
-- Make sure your Telegram bot has received at least one message so it knows where to send results
+- For the current Telegram adapter, make sure your bot has received at least one message so it knows where to send results
 - The timezone used for cron schedules is determined by the `TZ` environment variable (defaults to UTC)
-- Scheduled jobs run in separate Gemini CLI sessions, so they have access to all configured tools and MCP servers
+- Scheduled jobs run in separate local CLI sessions, so they have access to all configured tools and MCP servers
 
 ## Troubleshooting
 
@@ -237,7 +237,7 @@ The Gemini CLI is aware of the scheduler API through the system prompt. You can
 - Verify the cron expression is valid using a cron expression tester
 - Ensure the bridge is running continuously
 
-### Results not appearing in Telegram
+### Results not appearing in Telegram (current adapter)
 - Send at least one message to your bot first to establish the chat binding
 - Check if `lastIncomingChatId` is set in the logs
 

package/bin/cli.ts

@@ -23,7 +23,7 @@ const ENV_KEY_MAP: Record<string, string> = {
 	callbackPort: 'CALLBACK_PORT',
 	callbackAuthToken: 'CALLBACK_AUTH_TOKEN',
 	callbackMaxBodyBytes: 'CALLBACK_MAX_BODY_BYTES',
-	agentBridgeHome: 'AGENT_BRIDGE_HOME',
+	ClawlessHome: 'AGENT_BRIDGE_HOME',
 	memoryFilePath: 'MEMORY_FILE_PATH',
 	memoryMaxChars: 'MEMORY_MAX_CHARS',
 	schedulesFilePath: 'SCHEDULES_FILE_PATH',
@@ -50,7 +50,7 @@ const DEFAULT_CONFIG_TEMPLATE = {
 	callbackPort: 8788,
 	callbackAuthToken: '',
 	callbackMaxBodyBytes: 65536,
-	agentBridgeHome: '~/.clawless',
+	ClawlessHome: '~/.clawless',
 	memoryFilePath: '~/.clawless/MEMORY.md',
 	memoryMaxChars: 12000,
 	schedulesFilePath: '~/.clawless/schedules.json',

package/index.ts

@@ -576,9 +576,9 @@ function ensureMemoryFile() {
 
   if (!fs.existsSync(MEMORY_FILE_PATH)) {
     const template = [
-      '# Gemini Bridge Memory',
+      '# Clawless Memory',
       '',
-      'This file stores durable memory notes for Gemini Bridge.',
+      'This file stores durable memory notes for Clawless.',
       '',
       '## Notes',
       '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawless",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A bridge connecting Telegram to Agent Gemini CLI using Agent Communication Protocol (ACP)",
   "main": "dist/index.js",
   "type": "module",

package/QUICKSTART-SCHEDULER.md

@@ -1,226 +0,0 @@
-# Quick Start Guide: Scheduler Feature
-
-This guide will help you start using the scheduler feature in under 5 minutes.
-
-## Prerequisites
-
-1. Clawless is installed and configured
-2. You have sent at least one message to your bot (to establish chat binding)
-3. The bridge is running (`npm run dev` or `npm start`)
-
-## Basic Usage
-
-### Talk to Gemini Naturally
-
-The easiest way to use the scheduler is to just ask Gemini:
-
-**Examples:**
-
-```
-You: "Remind me to take a break in 30 minutes"
-
-You: "Check my calendar every morning at 9am and send me a summary"
-
-You: "Every Friday at 5pm, remind me to review my weekly goals"
-
-You: "What schedules do I have?"
-
-You: "Cancel the daily calendar check"
-```
-
-Gemini will handle all the API calls automatically!
-
-## Direct API Usage
-
-### 1. Create a Recurring Schedule
-
-```bash
-curl -X POST http://127.0.0.1:8788/api/schedule \
-  -H "Content-Type: application/json" \
-  -d '{
-    "message": "What time is it?",
-    "description": "Time check",
-    "cronExpression": "0 9 * * *"
-  }'
-```
-
-**Response:**
-```json
-{
-  "ok": true,
-  "schedule": {
-    "id": "schedule_1707835800000_abc123",
-    "message": "What time is it?",
-    "description": "Time check",
-    "cronExpression": "0 9 * * *",
-    "oneTime": false,
-    "active": true,
-    "createdAt": "2026-02-13T10:00:00.000Z"
-  }
-}
-```
-
-### 2. Create a One-Time Schedule
-
-```bash
-# Schedule for 30 seconds from now
-if ! RUN_AT=$(date -u -d "+30 seconds" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null); then
-  # Fallback for macOS/BSD date
-  RUN_AT=$(date -u -v+30S +"%Y-%m-%dT%H:%M:%SZ")
-fi
-
-curl -X POST http://127.0.0.1:8788/api/schedule \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"message\": \"Test reminder\",
-    \"oneTime\": true,
-    \"runAt\": \"${RUN_AT}\"
-  }"
-```
-
-### 3. List All Schedules
-
-```bash
-curl http://127.0.0.1:8788/api/schedule | jq .
-```
-
-### 4. Delete a Schedule
-
-```bash
-curl -X DELETE http://127.0.0.1:8788/api/schedule/SCHEDULE_ID
-```
-
-## Common Cron Expressions
-
-| Expression | Meaning |
-|------------|---------|
-| `0 9 * * *` | Every day at 9:00 AM |
-| `0 */6 * * *` | Every 6 hours |
-| `*/30 * * * *` | Every 30 minutes |
-| `0 9 * * 1-5` | Weekdays at 9:00 AM |
-| `0 17 * * 5` | Every Friday at 5:00 PM |
-| `0 0 1 * *` | First day of month at midnight |
-
-**Cron format:** `minute hour day month weekday`
-
-## What Happens When a Job Runs?
-
-1. **Scheduler triggers** at the scheduled time
-2. **Message is sent** to a new Gemini CLI session
-3. **Gemini processes** the message (can use tools, files, etc.)
-4. **Response is sent** to your Telegram chat automatically
-
-Example Telegram message you'll receive:
-```
-🔔 Scheduled task completed:
-
-Daily calendar summary
-
-Today's events:
-- 9:00 AM: Team standup
-- 2:00 PM: Project review
-- 4:30 PM: 1-on-1 with manager
-```
-
-## Testing Your First Schedule
-
-1. **Start the bridge:**
-   ```bash
-   npm run dev
-   ```
-
-2. **Create a test schedule (runs in 30 seconds):**
-   ```bash
-   if ! RUN_AT=$(date -u -d "+30 seconds" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null); then
-     # Fallback for macOS/BSD date
-     RUN_AT=$(date -u -v+30S +"%Y-%m-%dT%H:%M:%SZ")
-   fi
-   
-   curl -X POST http://127.0.0.1:8788/api/schedule \
-     -H "Content-Type: application/json" \
-     -d "{
-       \"message\": \"Hello! This is a test scheduled message.\",
-       \"description\": \"Test\",
-       \"oneTime\": true,
-       \"runAt\": \"${RUN_AT}\"
-     }"
-   ```
-
-3. **Wait 30 seconds** - You should receive a message in Telegram!
-
-4. **Or ask Gemini directly:**
-   ```
-   Send me a test message in 30 seconds
-   ```
-
-## With Authentication
-
-If you have `CALLBACK_AUTH_TOKEN` set in your config:
-
-```bash
-curl -X POST http://127.0.0.1:8788/api/schedule \
-  -H "Content-Type: application/json" \
-  -H "x-callback-token: YOUR_TOKEN_HERE" \
-  -d '{
-    "message": "Test",
-    "cronExpression": "0 9 * * *"
-  }'
-```
-
-## Troubleshooting
-
-### "No target chat available"
-**Solution:** Send at least one message to your bot first.
-
-### Schedule not executing
-**Solution:** 
-- Check bridge logs for errors
-- Verify cron expression is valid
-- Ensure bridge is still running
-
-### Can't reach API
-**Solution:**
-- Verify bridge is running: `curl http://127.0.0.1:8788/healthz`
-- Check if port 8788 is available
-- Look for errors in bridge logs
-
-## Next Steps
-
-- Read [SCHEDULER.md](SCHEDULER.md) for complete API documentation
-- Read [TESTING.md](TESTING.md) for comprehensive testing guide
-- Run `./scripts/test-scheduler.sh` for automated tests
-- View `./scripts/gemini-scheduler-examples.sh` for more examples
-
-## Pro Tips
-
-1. **Descriptions matter**: Add clear descriptions to help you remember what each schedule does
-2. **Test with one-time first**: Before setting up recurring jobs, test with a one-time schedule
-3. **Use natural language**: Just ask Gemini - it's easier than curl commands!
-4. **Check regularly**: Use "What schedules do I have?" to review active schedules
-5. **Timezone aware**: Set `TZ` environment variable if needed (default is UTC)
-
-## Example Workflows
-
-### Daily Morning Routine
-```
-You: "Every morning at 7am, check my calendar and the weather, then send me a summary"
-```
-
-### Work Break Reminders
-```
-You: "Remind me to take a break every 2 hours during work days"
-```
-
-### Weekly Review
-```
-You: "Every Sunday at 6pm, remind me to plan my goals for next week"
-```
-
-### Custom Notifications
-```
-You: "Check if there are any urgent emails every 30 minutes and notify me if found"
-```
-
----
-
-That's it! You're ready to start scheduling with Clawless. 🎉

package/QUICKSTART.md

@@ -1,98 +0,0 @@
-# Quick Start Guide
-
-Get your Telegram-Gemini bridge running in 5 minutes!
-
-## Prerequisites Checklist
-
-- [ ] Node.js 18+ installed (`node --version`)
-- [ ] Gemini CLI installed (`gemini --version`)
-- [ ] Telegram bot token from [@BotFather](https://t.me/BotFather)
-
-## Setup Steps
-
-### 1. Install Dependencies
-```bash
-npm install
-```
-
-### 2. Configure Environment
-```bash
-cp .env.example .env
-```
-
-Edit `.env` and add your bot token:
-```env
-TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
-```
-
-### 3. Test Gemini CLI
-Verify Gemini CLI supports ACP:
-```bash
-gemini --protocol acp
-```
-
-### 4. Run the Bridge
-
-**Quick test:**
-```bash
-npm start
-```
-
-**Development (auto-restart):**
-```bash
-npm run dev
-```
-
-**Production (with PM2):**
-```bash
-npm install -g pm2
-pm2 start ecosystem.config.json
-pm2 logs
-```
-
-## Verify It's Working
-
-1. Open Telegram
-2. Find your bot (search for the username you gave it)
-3. Send a message: "Hello!"
-4. You should see "🤔 Thinking..." followed by Gemini's response
-
-## Common Issues
-
-### "TELEGRAM_TOKEN is required"
-- Check your `.env` file exists
-- Verify the token is on the line `TELEGRAM_TOKEN=...`
-- No quotes needed around the token
-
-### "command not found: gemini"
-- Install Gemini CLI first
-- Verify with: `which gemini`
-
-### Bot doesn't respond
-- Check logs: `pm2 logs` (if using PM2)
-- Or check console output
-- Verify your bot token is correct
-
-### Rate limit errors (429)
-- Increase `UPDATE_INTERVAL_MS` in `.env` to 2000 or higher
-- Restart the bot
-
-## Next Steps
-
-- Read the full [README.md](README.md) for detailed configuration
-- Configure MCP servers for tool use
-- Set up auto-start with PM2
-
-## Getting Help
-
-- Check [README.md](README.md) troubleshooting section
-- Review Gemini CLI documentation
-- Open an issue on GitHub
-
----
-
-**Pro tip:** Keep the bridge running with PM2 and set it to auto-start on boot:
-```bash
-pm2 startup
-pm2 save
-```