clawless 0.2.0 → 0.2.2

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
 
@@ -63,6 +93,30 @@ ACP_DEBUG_STREAM=false
 4. Copy the token provided by BotFather
 5. Paste it into your `.env` file
 
+## Authorizing Users (Whitelist)
+
+For security, the bot only accepts commands from authorized users. To configure:
+
+1. **Use your Telegram username**:
+  - You can use your Telegram username (e.g., `your_username` or `@your_username`).
+  - If you don't have a username set, you must create one in Telegram settings.
+
+2. **Add usernames to whitelist** in `~/.clawless/config.json`:
+   ```json
+   {
+     "telegramToken": "your_bot_token",
+    "telegramWhitelist": ["your_username", "another_user"]
+   }
+   ```
+
+3. **Alternative: Use environment variable**:
+   ```bash
+  # Must be a valid JSON array string
+  TELEGRAM_WHITELIST='["your_username", "another_user"]'
+   ```
+
+⚠️ **Security Note**: If `telegramWhitelist` is empty or not configured, **all users will be blocked** by default. This is a safety measure to prevent unauthorized access.
+
 ## Usage
 
 ### CLI Mode
@@ -73,6 +127,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
@@ -178,6 +234,7 @@ pm2 save
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `TELEGRAM_TOKEN` | Yes | - | Your Telegram bot token from BotFather |
+| `TELEGRAM_WHITELIST` | No | [] | List of authorized Telegram usernames. **Security:** If empty, all users are blocked by default. Format: JSON array `["username1", "username2"]` |
 | `TYPING_INTERVAL_MS` | No | 4000 | Interval (in milliseconds) for refreshing Telegram typing status |
 | `GEMINI_TIMEOUT_MS` | No | 900000 | Overall timeout for a single Gemini CLI run |
 | `GEMINI_NO_OUTPUT_TIMEOUT_MS` | No | 60000 | Idle timeout; aborts if Gemini emits no output for this duration |
@@ -193,7 +250,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 +286,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 +313,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 +325,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 +353,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 +407,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
@@ -372,7 +439,7 @@ The codebase is designed to be simple and extensible:
 - **Never commit** `.env` file with your token (it's in `.gitignore`)
 - **Rotate tokens** if accidentally exposed
 - **Limit bot access** using Telegram's bot settings
-- **Monitor logs** for unusual activity
+- **Monitor logs** for unusual activity and unauthorized access attempts
 
 ## Contributing
 
@@ -401,4 +468,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

@@ -7,6 +7,7 @@ import process from 'node:process';
 
 const ENV_KEY_MAP: Record<string, string> = {
 	telegramToken: 'TELEGRAM_TOKEN',
+	telegramWhitelist: 'TELEGRAM_WHITELIST',
 	typingIntervalMs: 'TYPING_INTERVAL_MS',
 	geminiCommand: 'GEMINI_COMMAND',
 	geminiApprovalMode: 'GEMINI_APPROVAL_MODE',
@@ -23,7 +24,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',
@@ -34,6 +35,7 @@ const DEFAULT_AGENT_BRIDGE_HOME = path.join(os.homedir(), '.clawless');
 const DEFAULT_MEMORY_FILE_PATH = path.join(DEFAULT_AGENT_BRIDGE_HOME, 'MEMORY.md');
 const DEFAULT_CONFIG_TEMPLATE = {
 	telegramToken: 'your_telegram_bot_token_here',
+	telegramWhitelist: [],
 	typingIntervalMs: 4000,
 	geminiCommand: 'gemini',
 	geminiApprovalMode: 'yolo',
@@ -50,7 +52,7 @@ const DEFAULT_CONFIG_TEMPLATE = {
 	callbackPort: 8788,
 	callbackAuthToken: '',
 	callbackMaxBodyBytes: 65536,
-	agentBridgeHome: '~/.clawless',
+	ClawlessHome: '~/.clawless',
 	memoryFilePath: '~/.clawless/MEMORY.md',
 	memoryMaxChars: 12000,
 	schedulesFilePath: '~/.clawless/schedules.json',
@@ -109,6 +111,9 @@ function toEnvValue(value: unknown) {
 	if (typeof value === 'string') {
 		return value;
 	}
+	if (typeof value === 'object') {
+		return JSON.stringify(value);
+	}
 	return String(value);
 }
 

package/{agent-bridge.config.example.json → clawless.config.example.json}

@@ -1,5 +1,6 @@
 {
   "telegramToken": "your_telegram_bot_token_here",
+  "telegramWhitelist": [],
   "typingIntervalMs": 4000,
   "geminiCommand": "gemini",
   "geminiApprovalMode": "yolo",

package/dist/bin/cli.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 const ENV_KEY_MAP = {
     telegramToken: 'TELEGRAM_TOKEN',
+    telegramWhitelist: 'TELEGRAM_WHITELIST',
     typingIntervalMs: 'TYPING_INTERVAL_MS',
     geminiCommand: 'GEMINI_COMMAND',
     geminiApprovalMode: 'GEMINI_APPROVAL_MODE',
@@ -21,7 +22,7 @@ const ENV_KEY_MAP = {
     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',
@@ -31,6 +32,7 @@ const DEFAULT_AGENT_BRIDGE_HOME = path.join(os.homedir(), '.clawless');
 const DEFAULT_MEMORY_FILE_PATH = path.join(DEFAULT_AGENT_BRIDGE_HOME, 'MEMORY.md');
 const DEFAULT_CONFIG_TEMPLATE = {
     telegramToken: 'your_telegram_bot_token_here',
+    telegramWhitelist: [],
     typingIntervalMs: 4000,
     geminiCommand: 'gemini',
     geminiApprovalMode: 'yolo',
@@ -47,7 +49,7 @@ const DEFAULT_CONFIG_TEMPLATE = {
     callbackPort: 8788,
     callbackAuthToken: '',
     callbackMaxBodyBytes: 65536,
-    agentBridgeHome: '~/.clawless',
+    ClawlessHome: '~/.clawless',
     memoryFilePath: '~/.clawless/MEMORY.md',
     memoryMaxChars: 12000,
     schedulesFilePath: '~/.clawless/schedules.json',
@@ -98,6 +100,9 @@ function toEnvValue(value) {
     if (typeof value === 'string') {
         return value;
     }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
     return String(value);
 }
 function resolveEnvKey(configKey) {

package/dist/index.js

@@ -48,6 +48,35 @@ const TYPING_INTERVAL_MS = parseInt(process.env.TYPING_INTERVAL_MS || '4000', 10
 const TELEGRAM_STREAM_UPDATE_INTERVAL_MS = 1000;
 // Maximum response length to prevent memory issues (Telegram has 4096 char limit anyway)
 const MAX_RESPONSE_LENGTH = parseInt(process.env.MAX_RESPONSE_LENGTH || '4000', 10);
+// Parse Telegram whitelist from environment variable
+// Expected format: JSON array of usernames (e.g., ["user1", "user2"])
+function parseWhitelistFromEnv(envValue) {
+    if (!envValue || envValue.trim() === '') {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(envValue);
+        if (Array.isArray(parsed)) {
+            return parsed.map((name) => String(name).trim().replace(/^@/, '')).filter(Boolean);
+        }
+    }
+    catch {
+        console.warn('Warning: TELEGRAM_WHITELIST must be a valid JSON array of usernames (e.g., ["user1", "user2"])');
+    }
+    return [];
+}
+const TELEGRAM_WHITELIST = parseWhitelistFromEnv(process.env.TELEGRAM_WHITELIST || '');
+function isUserAuthorized(username) {
+    // If whitelist is empty, block all users by default (safe default)
+    if (TELEGRAM_WHITELIST.length === 0) {
+        return false;
+    }
+    if (!username) {
+        return false;
+    }
+    const normalizedUsername = username.toLowerCase();
+    return TELEGRAM_WHITELIST.some(entry => entry.toLowerCase() === normalizedUsername);
+}
 const messagingClient = new TelegramMessagingClient({
     token: process.env.TELEGRAM_TOKEN,
     typingIntervalMs: TYPING_INTERVAL_MS,
@@ -68,7 +97,7 @@ const GEMINI_STDERR_TAIL_MAX = 4000;
 function validateGeminiCommandOrExit() {
     const result = spawnSync(GEMINI_COMMAND, ['--version'], {
         stdio: 'ignore',
-        timeout: 5000,
+        timeout: 10000,
         killSignal: 'SIGKILL',
     });
     if (result.error?.code === 'ENOENT') {
@@ -492,9 +521,9 @@ function ensureMemoryFile() {
     fs.mkdirSync(path.dirname(MEMORY_FILE_PATH), { recursive: true });
     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',
             '',
@@ -1034,6 +1063,12 @@ async function processSingleMessage(messageContext, messageRequestId) {
  * Handles incoming text messages from Telegram
  */
 messagingClient.onTextMessage(async (messageContext) => {
+    // Check if user is authorized
+    if (!isUserAuthorized(messageContext.username)) {
+        console.warn(`Unauthorized access attempt from username: ${messageContext.username ?? 'none'} (ID: ${messageContext.userId ?? 'unknown'})`);
+        await messageContext.sendText('🚫 Unauthorized. This bot is restricted to authorized users only.');
+        return;
+    }
     if (messageContext.chatId !== undefined && messageContext.chatId !== null) {
         lastIncomingChatId = String(messageContext.chatId);
         persistCallbackChatId(lastIncomingChatId);
@@ -1092,7 +1127,15 @@ messagingClient.launch()
         callbackPort: CALLBACK_PORT,
         mcpSkillsSource: 'local Gemini CLI defaults (no MCP override)',
         acpMode: `${GEMINI_COMMAND} --experimental-acp`,
+        telegramWhitelist: TELEGRAM_WHITELIST.length > 0 ? `${TELEGRAM_WHITELIST.length} user(s) authorized` : 'NONE (all users blocked)',
     });
+    if (TELEGRAM_WHITELIST.length === 0) {
+        console.warn('⚠️  WARNING: Telegram whitelist is empty. All users will be blocked.');
+        console.warn('⚠️  Add usernames to TELEGRAM_WHITELIST config (as a JSON array) to authorize users.');
+    }
+    else {
+        console.log(`✅ Telegram authorization enabled. Authorized usernames: ${TELEGRAM_WHITELIST.join(', ')}`);
+    }
     scheduleAcpPrewarm('post-launch');
     if (HEARTBEAT_INTERVAL_MS > 0) {
         setInterval(() => {

package/dist/messaging/telegramClient.js

@@ -22,12 +22,16 @@ class TelegramMessageContext {
     maxMessageLength;
     text;
     chatId;
+    userId;
+    username;
     constructor(ctx, typingIntervalMs, maxMessageLength) {
         this.ctx = ctx;
         this.typingIntervalMs = typingIntervalMs;
         this.maxMessageLength = maxMessageLength;
         this.text = ctx.message?.text || '';
         this.chatId = ctx.chat?.id;
+        this.userId = ctx.from?.id;
+        this.username = ctx.from?.username;
     }
     startTyping() {
         this.ctx.telegram.sendChatAction(this.ctx.chat.id, 'typing').catch(() => { });

package/index.ts

@@ -55,6 +55,42 @@ const TELEGRAM_STREAM_UPDATE_INTERVAL_MS = 1000;
 // Maximum response length to prevent memory issues (Telegram has 4096 char limit anyway)
 const MAX_RESPONSE_LENGTH = parseInt(process.env.MAX_RESPONSE_LENGTH || '4000', 10);
 
+// Parse Telegram whitelist from environment variable
+// Expected format: JSON array of usernames (e.g., ["user1", "user2"])
+function parseWhitelistFromEnv(envValue: string): string[] {
+  if (!envValue || envValue.trim() === '') {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(envValue);
+    if (Array.isArray(parsed)) {
+      return parsed.map((name) => String(name).trim().replace(/^@/, '')).filter(Boolean);
+    }
+  } catch {
+    console.warn('Warning: TELEGRAM_WHITELIST must be a valid JSON array of usernames (e.g., ["user1", "user2"])');
+  }
+
+  return [];
+}
+
+const TELEGRAM_WHITELIST: string[] = parseWhitelistFromEnv(process.env.TELEGRAM_WHITELIST || '');
+
+function isUserAuthorized(username: string | undefined): boolean {
+  // If whitelist is empty, block all users by default (safe default)
+  if (TELEGRAM_WHITELIST.length === 0) {
+    return false;
+  }
+
+  if (!username) {
+    return false;
+  }
+
+  const normalizedUsername = username.toLowerCase();
+
+  return TELEGRAM_WHITELIST.some(entry => entry.toLowerCase() === normalizedUsername);
+}
+
 const messagingClient = new TelegramMessagingClient({
   token: process.env.TELEGRAM_TOKEN,
   typingIntervalMs: TYPING_INTERVAL_MS,
@@ -77,7 +113,7 @@ const GEMINI_STDERR_TAIL_MAX = 4000;
 function validateGeminiCommandOrExit() {
   const result = spawnSync(GEMINI_COMMAND, ['--version'], {
     stdio: 'ignore',
-    timeout: 5000,
+    timeout: 10000,
     killSignal: 'SIGKILL',
   });
 
@@ -576,9 +612,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',
       '',
@@ -1182,6 +1218,13 @@ async function processSingleMessage(messageContext: any, messageRequestId: numbe
  * Handles incoming text messages from Telegram
  */
 messagingClient.onTextMessage(async (messageContext) => {
+  // Check if user is authorized
+  if (!isUserAuthorized(messageContext.username)) {
+    console.warn(`Unauthorized access attempt from username: ${messageContext.username ?? 'none'} (ID: ${messageContext.userId ?? 'unknown'})`);
+    await messageContext.sendText('🚫 Unauthorized. This bot is restricted to authorized users only.');
+    return;
+  }
+
   if (messageContext.chatId !== undefined && messageContext.chatId !== null) {
     lastIncomingChatId = String(messageContext.chatId);
     persistCallbackChatId(lastIncomingChatId);
@@ -1246,8 +1289,16 @@ messagingClient.launch()
       callbackPort: CALLBACK_PORT,
       mcpSkillsSource: 'local Gemini CLI defaults (no MCP override)',
       acpMode: `${GEMINI_COMMAND} --experimental-acp`,
+      telegramWhitelist: TELEGRAM_WHITELIST.length > 0 ? `${TELEGRAM_WHITELIST.length} user(s) authorized` : 'NONE (all users blocked)',
     });
 
+    if (TELEGRAM_WHITELIST.length === 0) {
+      console.warn('⚠️  WARNING: Telegram whitelist is empty. All users will be blocked.');
+      console.warn('⚠️  Add usernames to TELEGRAM_WHITELIST config (as a JSON array) to authorize users.');
+    } else {
+      console.log(`✅ Telegram authorization enabled. Authorized usernames: ${TELEGRAM_WHITELIST.join(', ')}`);
+    }
+
     scheduleAcpPrewarm('post-launch');
 
     if (HEARTBEAT_INTERVAL_MS > 0) {

package/messaging/telegramClient.ts

@@ -28,6 +28,8 @@ class TelegramMessageContext {
   maxMessageLength: number;
   text: string;
   chatId: string | number | undefined;
+  userId: number | undefined;
+  username: string | undefined;
 
   constructor(ctx: any, typingIntervalMs: number, maxMessageLength: number) {
     this.ctx = ctx;
@@ -35,6 +37,8 @@ class TelegramMessageContext {
     this.maxMessageLength = maxMessageLength;
     this.text = ctx.message?.text || '';
     this.chatId = ctx.chat?.id;
+    this.userId = ctx.from?.id;
+    this.username = ctx.from?.username;
   }
 
   startTyping() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawless",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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
-```