clawless 0.1.2

package/.env.example

@@ -0,0 +1,48 @@
+# Telegram Token (required)
+# Get this from @BotFather on Telegram
+TELEGRAM_TOKEN=your_telegram_bot_token_here
+
+# Typing indicator refresh interval in milliseconds (optional, default: 4000)
+TYPING_INTERVAL_MS=4000
+
+# Gemini command and mode options
+GEMINI_COMMAND=gemini
+# GEMINI_APPROVAL_MODE=yolo
+# GEMINI_MODEL=
+
+# How ACP permission options are auto-selected when requested by the agent.
+# Supported: allow_once, reject_once, cancelled
+ACP_PERMISSION_STRATEGY=allow_once
+
+# Gemini overall timeout in milliseconds (optional, default: 900000)
+GEMINI_TIMEOUT_MS=900000
+
+# Gemini no-output timeout in milliseconds (optional, default: 60000)
+# Set to 0 to disable idle-timeout behavior.
+GEMINI_NO_OUTPUT_TIMEOUT_MS=60000
+
+# Grace period before forcing SIGKILL after SIGTERM (optional, default: 5000)
+GEMINI_KILL_GRACE_MS=5000
+
+# Stream diagnostics
+# ACP_STREAM_STDOUT=true writes raw ACP text chunks to stdout as they arrive
+# ACP_DEBUG_STREAM=true writes structured chunk timing/count logs
+ACP_STREAM_STDOUT=false
+ACP_DEBUG_STREAM=false
+
+# Maximum response length in characters (optional, default: 4000)
+# Prevents memory issues with very long responses
+# Telegram has a 4096 character limit per message anyway
+MAX_RESPONSE_LENGTH=4000
+
+# Local callback server: lets cron/jobs POST messages to Telegram directly
+# Endpoint: POST http://localhost:8788/callback/telegram
+CALLBACK_HOST=localhost
+CALLBACK_PORT=8788
+# Optional auth token, sent via x-callback-token or Authorization: Bearer <token>
+CALLBACK_AUTH_TOKEN=
+# Max accepted callback payload size in bytes
+CALLBACK_MAX_BODY_BYTES=65536
+
+# Persistent scheduler storage file (JSON)
+SCHEDULES_FILE_PATH=~/.clawless/schedules.json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hainan Zhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART-SCHEDULER.md

@@ -0,0 +1,226 @@
+# 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

@@ -0,0 +1,98 @@
+# 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
+```