ClawPulse 🦞⚡

Reliable cron scheduler for OpenClaw - Fix broken scheduling and build truly proactive AI agents

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

npm install -g clawpulse

2. Initialize

clawpulse init

3. Add your first job

# 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

clawpulse daemon

CLI Commands

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

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

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

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)

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

# 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

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

clawpulse status

Telegram delivery failing?

Make sure you provide a chat ID:

# Get your Telegram chat ID from @userinfobot
clawpulse add --channel telegram --deliver --reply-to YOUR_CHAT_ID ...

Database errors?

Reset the database:

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 for guidelines.

License

MIT License - see LICENSE

Copyright (c) 2026 Abdelhak Akermi

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• OpenClaw Discord: #extensions channel

Built with ❤️ for the OpenClaw community 🦞

Status: Alpha - Working and tested with OpenClaw Gateway