clawpulse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelhak Akermi
+
+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.md

@@ -0,0 +1,413 @@
+# ClawPulse - Quick Start Guide
+
+Get ClawPulse running in 5 minutes! 🚀
+
+## Prerequisites
+
+- Node.js 22+ installed
+- OpenClaw Gateway running on your system
+- OpenClaw CLI installed (`openclaw` command available)
+
+## Installation
+
+### Option 1: From npm (when published)
+```bash
+npm install -g clawpulse
+```
+
+### Option 2: From source
+```bash
+git clone https://github.com/abakermi/clawpulse.git
+cd clawpulse
+npm install
+npm run build
+npm link  # Makes 'clawpulse' command available globally
+```
+
+## Quick Start
+
+### Step 1: Initialize
+
+```bash
+clawpulse init
+```
+
+This creates `~/.clawpulse/` with your database.
+
+### Step 2: Add Your First Job
+
+```bash
+# Simple job (logs only)
+clawpulse add \
+  --cron "*/5 * * * *" \
+  --message "What's the time?" \
+  --name "time-check" \
+  --agent main
+```
+
+### Step 3: Start the Scheduler
+
+```bash
+clawpulse daemon
+```
+
+You should see:
+```
+🦞 Starting ClawPulse Scheduler...
+✅ OpenClaw CLI found
+📋 Loaded 1 enabled jobs
+⏰ Scheduled job: time-check (*/5 * * * *)
+✅ ClawPulse Scheduler started
+```
+
+Every 5 minutes, the job will execute and you'll see responses in the OpenClaw Gateway logs.
+
+### Step 4: View Your Jobs
+
+```bash
+clawpulse list
+```
+
+---
+
+## Common Examples
+
+### 1. Daily Morning Briefing to WhatsApp
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Good morning! What's on my agenda today?" \
+  --name "morning-briefing" \
+  --agent main \
+  --channel whatsapp \
+  --deliver
+```
+
+**Result**: Every day at 9 AM, you'll receive a WhatsApp message with your agenda!
+
+### 2. Hourly Status Update to Telegram
+
+```bash
+# First, get your Telegram chat ID from @userinfobot
+clawpulse add \
+  --cron "0 * * * *" \
+  --message "Hourly system status check" \
+  --name "status-telegram" \
+  --agent main \
+  --channel telegram \
+  --deliver \
+  --reply-to YOUR_CHAT_ID
+```
+
+**Result**: Every hour, you'll receive a Telegram message with the status!
+
+### 3. Weekly Report every Monday
+
+```bash
+clawpulse add \
+  --cron "0 10 * * 1" \
+  --message "Generate weekly activity report from last 7 days" \
+  --name "weekly-report" \
+  --agent main \
+  --channel whatsapp \
+  --deliver
+```
+
+**Result**: Every Monday at 10 AM, get your weekly report!
+
+### 4. Every 15 Minutes Health Check (Logs Only)
+
+```bash
+clawpulse add \
+  --cron "*/15 * * * *" \
+  --message "System health check" \
+  --name "health-check" \
+  --agent main
+  # Note: No --channel or --deliver = responses only in logs
+```
+
+**Result**: Agent responds every 15 minutes, visible in gateway logs.
+
+---
+
+## Understanding Cron Expressions
+
+Cron format: `minute hour day month weekday`
+
+### Common Patterns
+
+```bash
+# Every minute
+*/1 * * * *
+
+# Every 5 minutes
+*/5 * * * *
+
+# Every hour
+0 * * * *
+
+# Every day at 9 AM
+0 9 * * *
+
+# Every day at 9 AM and 5 PM
+0 9,17 * * *
+
+# Every weekday at 9 AM
+0 9 * * 1-5
+
+# Every Monday at 10 AM
+0 10 * * 1
+
+# Every Sunday at midnight
+0 0 * * 0
+
+# First day of every month at 9 AM
+0 9 1 * *
+```
+
+**Need help?** Use [crontab.guru](https://crontab.guru) to build and test expressions!
+
+---
+
+## Channel Delivery
+
+### WhatsApp (Easiest)
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Morning update" \
+  --agent main \
+  --channel whatsapp \
+  --deliver
+  # No --reply-to needed - uses your personal WhatsApp chat
+```
+
+### Telegram (Requires Chat ID)
+
+```bash
+# 1. Get chat ID from @userinfobot on Telegram
+# 2. Use it with --reply-to
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Morning update" \
+  --agent main \
+  --channel telegram \
+  --deliver \
+  --reply-to 123456789
+```
+
+### Slack (Requires Channel)
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Morning update" \
+  --agent main \
+  --channel slack \
+  --deliver \
+  --reply-to "#general"
+```
+
+### Logs Only (No Delivery)
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Morning update" \
+  --agent main
+  # Omit --channel and --deliver flags
+  # Response only appears in OpenClaw Gateway logs
+```
+
+---
+
+## CLI Commands
+
+### Add a Job
+```bash
+clawpulse add --cron "0 9 * * *" --message "Morning briefing" --agent main
+```
+
+### List All Jobs
+```bash
+clawpulse list
+```
+
+Output:
+```
+📋 Found 2 jobs:
+
+morning-briefing (1770547841976-d382qjv)
+  Status: ✓ enabled
+  Cron: */1 * * * *
+  Message: Good morning! What's on the agenda today?
+  Channel: whatsapp
+  Agent: main
+  Deliver: yes
+  Runs: 5 success, 0 failed
+  Last run: 2/8/2026, 10:48:35 AM
+  Next run: 2/8/2026, 10:49:00 AM
+```
+
+### Show Status
+```bash
+clawpulse status
+```
+
+Output:
+```
+📊 ClawPulse Status
+
+Total jobs: 2
+Enabled jobs: 2
+Running jobs: 2
+Total runs: 10
+Successful runs: 10
+Failed runs: 0
+Last run: 2/8/2026, 10:48:35 AM
+Next run: 2/8/2026, 10:49:00 AM
+```
+
+### Remove a Job
+```bash
+clawpulse remove 1770547841976-d382qjv
+```
+
+### Manually Trigger a Job
+```bash
+clawpulse trigger 1770547841976-d382qjv
+```
+
+---
+
+## Troubleshooting
+
+### 1. Jobs not firing?
+
+Make sure the daemon is running:
+```bash
+# In one terminal
+clawpulse daemon
+
+# In another terminal
+clawpulse status
+```
+
+### 2. "OpenClaw CLI not found"?
+
+Check OpenClaw is installed:
+```bash
+which openclaw
+openclaw --version
+```
+
+If not installed, install OpenClaw first.
+
+### 3. Telegram delivery fails?
+
+Error: `Delivering to Telegram requires target <chatId>`
+
+**Solution**: Add `--reply-to` with your Telegram chat ID:
+```bash
+# Get chat ID from @userinfobot
+clawpulse add ... --channel telegram --deliver --reply-to 123456789
+```
+
+### 4. Database errors?
+
+Reset the database:
+```bash
+rm ~/.clawpulse/data.db*
+clawpulse init
+```
+
+### 5. "Command hangs after adding job"?
+
+This was a bug in earlier versions. Make sure you have the latest build:
+```bash
+cd clawpulse
+npm run build
+```
+
+---
+
+## Advanced Usage
+
+### Custom Agent
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Analyze yesterday's metrics" \
+  --agent analytics  # Use 'analytics' agent instead of 'main'
+  --channel slack \
+  --deliver \
+  --reply-to "#metrics"
+```
+
+### Target Specific Session
+
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Continue our discussion about project X" \
+  --session-id abc123  # Resume specific conversation
+  --channel whatsapp \
+  --deliver
+```
+
+### Custom Timezone
+
+```bash
+export TZ=America/New_York
+clawpulse daemon
+```
+
+---
+
+## Real-World Use Cases
+
+### Personal Assistant
+```bash
+# Morning briefing
+clawpulse add --cron "0 8 * * 1-5" --message "Good morning! Summarize my calendar and top 3 priorities" --agent main --channel whatsapp --deliver
+
+# Evening wrap-up
+clawpulse add --cron "0 18 * * 1-5" --message "Summarize what I accomplished today" --agent main --channel whatsapp --deliver
+
+# Weekend planning
+clawpulse add --cron "0 9 * * 6" --message "What's on my calendar for next week?" --agent main --channel whatsapp --deliver
+```
+
+### Team Notifications
+```bash
+# Daily standup reminder
+clawpulse add --cron "0 9 * * 1-5" --message "Daily standup in 30 minutes! Prepare your updates" --agent main --channel slack --deliver --reply-to "#team"
+
+# Weekly retrospective
+clawpulse add --cron "0 15 * * 5" --message "Weekly retro in 1 hour! Review the sprint board" --agent main --channel slack --deliver --reply-to "#team"
+```
+
+### Monitoring & Alerts
+```bash
+# Health checks
+clawpulse add --cron "*/15 * * * *" --message "Check system health and alert if issues" --agent monitoring --channel telegram --deliver --reply-to 123456789
+
+# Daily metrics
+clawpulse add --cron "0 10 * * *" --message "Generate yesterday's metrics report" --agent analytics --channel slack --deliver --reply-to "#metrics"
+```
+
+---
+
+## What's Next?
+
+1. **Check the full README** for all options: [README.md](./README.md)
+2. **Join the community**: OpenClaw Discord `#extensions` channel
+3. **Report issues**: GitHub Issues (when repo is public)
+4. **Contribute**: See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+---
+
+**You're all set!** ClawPulse is now scheduling your jobs reliably. 🦞⚡

package/README.md

@@ -0,0 +1,315 @@
+# ClawPulse 🦞⚡
+
+> **Reliable cron scheduler for OpenClaw** - Fix broken scheduling and build truly proactive AI agents
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## The Problem
+
+OpenClaw's built-in cron scheduler has critical issues (10+ bugs in the past month):
+- Jobs never fire despite scheduler reporting 'started'
+- `schedule.kind: 'every'` without anchorMs never triggers
+- Timer re-arms but runDueJobs finds nothing
+- Scheduler lane wedges for hours
+
+**Result**: Users cannot build proactive agents. No reminders, no monitoring, no automation.
+
+## The Solution
+
+ClawPulse is a lightweight, reliable scheduler that integrates seamlessly with OpenClaw:
+
+- ✅ **Rock-solid scheduling** - Uses battle-tested Croner library
+- 📱 **Multi-channel delivery** - WhatsApp, Telegram, Slack, Discord, etc.
+- 🎯 **Agent targeting** - Route to specific agents or sessions
+- 📊 **Execution history** - Track what fired, when, and results
+- 🔧 **Simple CLI** - Add jobs in seconds
+- 💾 **SQLite persistence** - Jobs survive restarts
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g clawpulse
+```
+
+### 2. Initialize
+
+```bash
+clawpulse init
+```
+
+### 3. Add your first job
+
+```bash
+# Send to WhatsApp every day at 9 AM
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Good morning! What's on the agenda today?" \
+  --agent main \
+  --channel whatsapp \
+  --deliver
+
+# Send to Telegram every hour
+clawpulse add \
+  --cron "0 * * * *" \
+  --message "Hourly status update" \
+  --agent main \
+  --channel telegram \
+  --deliver \
+  --reply-to YOUR_CHAT_ID
+```
+
+### 4. Start the scheduler
+
+```bash
+clawpulse daemon
+```
+
+## CLI Commands
+
+```bash
+# Add a scheduled job
+clawpulse add --cron "0 9 * * *" --message "Morning briefing" --agent main
+
+# List all jobs
+clawpulse list
+
+# Show scheduler status
+clawpulse status
+
+# Update a job
+clawpulse update <job-id> --message "Updated message" --cron "0 10 * * *"
+
+# Enable/disable jobs
+clawpulse enable <job-id>
+clawpulse disable <job-id>
+
+# View execution history
+clawpulse logs <job-id> --limit 20
+
+# Remove a job
+clawpulse remove <job-id>
+
+# Manually trigger a job
+clawpulse trigger <job-id>
+```
+
+## Options
+
+### --cron
+Cron expression for scheduling. Examples:
+- `"*/5 * * * *"` - Every 5 minutes
+- `"0 9 * * *"` - Every day at 9 AM
+- `"0 0 * * 0"` - Every Sunday at midnight
+- `"0 9 * * 1-5"` - Every weekday at 9 AM
+
+Use [crontab.guru](https://crontab.guru) to create expressions.
+
+### --channel
+Delivery channel (optional):
+- `whatsapp` - WhatsApp (default personal chat)
+- `telegram` - Telegram (requires --reply-to)
+- `slack` - Slack
+- `discord` - Discord
+- `signal` - Signal
+- And more...
+
+### --agent
+OpenClaw agent ID (default: `main`)
+
+### --deliver
+Send the agent's response back to the channel. Without this flag, responses only appear in gateway logs.
+
+### --reply-to
+Target for delivery (required for Telegram):
+- Telegram: Chat ID (e.g., `123456789`)
+- Slack: Channel name (e.g., `#general`)
+- Discord: Channel ID
+
+### --session-id
+Target specific session instead of agent
+
+### --to
+Target phone number in E.164 format (alternative to --agent)
+
+## Examples
+
+### Daily morning briefing to WhatsApp
+```bash
+clawpulse add \
+  --cron "0 9 * * *" \
+  --message "Good morning! Summarize my calendar and top emails" \
+  --name "morning-briefing" \
+  --agent main \
+  --channel whatsapp \
+  --deliver
+```
+
+### Hourly status check to Telegram
+```bash
+clawpulse add \
+  --cron "0 * * * *" \
+  --message "System status check" \
+  --name "status-check" \
+  --agent main \
+  --channel telegram \
+  --deliver \
+  --reply-to 5661599285
+```
+
+### Weekly report every Monday at 10 AM
+```bash
+clawpulse add \
+  --cron "0 10 * * 1" \
+  --message "Generate weekly activity report" \
+  --name "weekly-report" \
+  --agent main \
+  --channel slack \
+  --deliver \
+  --reply-to "#reports"
+```
+
+### Every 5 minutes health check (logs only)
+```bash
+clawpulse add \
+  --cron "*/5 * * * *" \
+  --message "Health check ping" \
+  --name "health-check" \
+  --agent main
+  # Note: No --deliver flag - responses only in logs
+```
+
+## How It Works
+
+```
+┌──────────────┐       ┌──────────────┐       ┌──────────────┐
+│  ClawPulse   │       │   OpenClaw   │       │   Channels   │
+│   Scheduler  │──────▶│   CLI Agent  │──────▶│   (Output)   │
+└──────────────┘       └──────────────┘       └──────────────┘
+       │                       │                       │
+  Cron Jobs               Process Msg            WhatsApp
+  SQLite DB               Generate Reply         Telegram
+  Job History            Gateway Auth            Slack, etc.
+```
+
+1. **ClawPulse** stores jobs in SQLite and triggers them on schedule
+2. **OpenClaw CLI** receives the message and sends it to your agent
+3. **Channels** (optional) deliver the agent's response to WhatsApp/Telegram/etc.
+
+## Architecture
+
+- **Language**: TypeScript
+- **Runtime**: Node.js 22+
+- **Scheduler**: [Croner](https://github.com/hexagon/croner) (battle-tested, 99.9%+ reliability)
+- **Database**: SQLite with WAL mode
+- **Integration**: OpenClaw CLI (handles authentication automatically)
+
+## Configuration
+
+ClawPulse stores data in `~/.clawpulse/`:
+- `data.db` - SQLite database (jobs and execution history)
+- `data.db-wal` - Write-ahead log
+- `data.db-shm` - Shared memory
+
+### Environment Variables
+
+```bash
+# Gateway URL (default: ws://localhost:18789)
+export OPENCLAW_GATEWAY_URL=ws://localhost:18789
+
+# Database path (default: ~/.clawpulse/data.db)
+export CLAWPULSE_DB=/custom/path/data.db
+
+# Timezone (default: system timezone)
+export TZ=America/New_York
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/abakermi/clawpulse.git
+cd clawpulse
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run in dev mode
+npm run dev -- daemon
+
+# Test specific command
+npm run dev -- add --cron "*/1 * * * *" --message "Test" --agent main
+```
+
+## Troubleshooting
+
+### Jobs not firing?
+
+Check that the daemon is running:
+```bash
+clawpulse status
+```
+
+### Telegram delivery failing?
+
+Make sure you provide a chat ID:
+```bash
+# Get your Telegram chat ID from @userinfobot
+clawpulse add --channel telegram --deliver --reply-to YOUR_CHAT_ID ...
+```
+
+### Database errors?
+
+Reset the database:
+```bash
+rm ~/.clawpulse/data.db*
+clawpulse init
+```
+
+## Roadmap
+
+### ✅ Phase 1: MVP (Complete)
+- [x] Reliable cron scheduling with Croner
+- [x] SQLite persistence
+- [x] OpenClaw CLI integration
+- [x] Multi-channel delivery (WhatsApp, Telegram, etc.)
+- [x] Job management (add/list/remove/update/enable/disable/logs)
+- [x] Execution history
+- [x] Input validation with helpful error messages
+- [x] Unit tests (68.5% coverage, 39/39 passing)
+
+### 📋 Phase 3: Advanced Features (Future)
+- [ ] HTTP webhook receiver
+- [ ] GitHub event integration
+- [ ] Event chains (when A completes, trigger B)
+- [ ] Web dashboard (basic UI)
+- [ ] PostgreSQL support
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](./LICENSE)
+
+Copyright (c) 2026 Abdelhak Akermi
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/abakermi/clawpulse/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/abakermi/clawpulse/discussions)
+- **OpenClaw Discord**: `#extensions` channel
+
+---
+
+**Built with ❤️ for the OpenClaw community** 🦞
+
+**Status**: Alpha - Working and tested with OpenClaw Gateway

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "clawpulse",
+  "version": "0.1.0",
+  "description": "Event-driven orchestrator for OpenClaw - fix broken cron and enable proactive AI agents",
+  "keywords": [
+    "openclaw",
+    "cron",
+    "scheduler",
+    "events",
+    "webhooks",
+    "automation",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "author": "Abdelhak Akermi",
+  "homepage": "https://github.com/abakermi/clawpulse#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abakermi/clawpulse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abakermi/clawpulse/issues"
+  },
+  "bin": {
+    "clawpulse": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc && cp -r src/database/*.sql dist/database/",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.6.0",
+    "commander": "^12.0.0",
+    "croner": "^10.0.0",
+    "dotenv": "^17.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "QUICKSTART.md"
+  ]
+}