TinyClaw 🦞

Minimal multi-channel AI assistant with WhatsApp integration and queue-based architecture.

🎯 What is TinyClaw?

TinyClaw is a lightweight wrapper around Claude Code that:

• ✅ Connects WhatsApp (via QR code)
• ✅ Processes messages sequentially (no race conditions)
• ✅ Maintains conversation context
• ✅ Runs 24/7 in tmux
• ✅ Ready for multi-channel (Telegram, etc.)

Key innovation: File-based queue system prevents race conditions and enables multi-channel support.

📐 Architecture

┌─────────────────┐
│  WhatsApp       │──┐
│  Client         │  │
└─────────────────┘  │
                     ├──→ Queue (incoming/)
┌─────────────────┐  │        ↓
│  Telegram       │──┤   ┌──────────────┐
│  (future)       │  │   │   Queue      │
└─────────────────┘  │   │  Processor   │
                     │   └──────────────┘
Other Channels ──────┘        ↓
                         claude --dangerously-skip-permissions -c -p
                              ↓
                         Queue (outgoing/)
                              ↓
                    ┌─────────────────┐
                    │ Channels send   │
                    │ responses       │
                    └─────────────────┘

Tmux Layout

┌──────────────┬──────────────┐
│  WhatsApp    │    Queue     │
│  Client      │  Processor   │
├──────────────┼──────────────┤
│  Heartbeat   │    Logs      │
└──────────────┴──────────────┘

🚀 Quick Start

Prerequisites

• macOS or Linux
• Claude Code installed
• Node.js v14+
• tmux

Installation

cd /Users/jliao/workspace/tinyclaw

# Install dependencies
npm install

# Make scripts executable
chmod +x *.sh *.js

# Start TinyClaw
./tinyclaw.sh start

First Run

A QR code will appear in your terminal:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
        WhatsApp QR Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[QR CODE HERE]

📱 Scan with WhatsApp:
   Settings → Linked Devices → Link a Device

Scan it with your phone. Done! 🎉

Test It

Send a WhatsApp message to yourself from a different WhatsApp account:

"Hello Claude!"

You'll get a response! 🤖

📋 Commands

# Start TinyClaw
./tinyclaw.sh start

# Check status
./tinyclaw.sh status

# Send manual message
./tinyclaw.sh send "What's the weather?"

# Reset conversation
./tinyclaw.sh reset

# View logs
./tinyclaw.sh logs whatsapp
./tinyclaw.sh logs queue

# Attach to tmux
./tinyclaw.sh attach

# Stop
./tinyclaw.sh stop

🔧 Components

1. whatsapp-client.js

• Connects to WhatsApp via QR code
• Writes incoming messages to queue
• Reads responses from queue
• Sends replies back

2. queue-processor.js

• Polls incoming queue
• Processes ONE message at a time
• Calls claude -c -p
• Writes responses to outgoing queue

3. heartbeat-cron.sh

• Runs every 5 minutes
• Sends heartbeat via queue
• Keeps conversation active

4. tinyclaw.sh

• Main orchestrator
• Manages tmux session
• CLI interface

💬 Message Flow

WhatsApp message arrives
       ↓
whatsapp-client.js writes to:
  .tinyclaw/queue/incoming/whatsapp_<id>.json
       ↓
queue-processor.js picks it up
       ↓
Runs: claude -c -p "message"
       ↓
Writes to:
  .tinyclaw/queue/outgoing/whatsapp_<id>.json
       ↓
whatsapp-client.js sends response
       ↓
User receives reply

📁 Directory Structure

tinyclaw/
├── .claude/              # Claude Code config
│   ├── settings.json     # Hooks config
│   └── hooks/            # Hook scripts
├── .tinyclaw/            # TinyClaw data
│   ├── queue/
│   │   ├── incoming/     # New messages
│   │   ├── processing/   # Being processed
│   │   └── outgoing/     # Responses
│   ├── logs/
│   ├── whatsapp-session/
│   └── heartbeat.md
├── tinyclaw.sh           # Main script
├── whatsapp-client.js    # WhatsApp I/O
├── queue-processor.js    # Message processing
└── heartbeat-cron.sh     # Health checks

🔄 Reset Conversation

Via CLI

./tinyclaw.sh reset

Via WhatsApp

Send: !reset or /reset

Next message starts fresh (no conversation history).

⚙️ Configuration

Heartbeat Interval

Edit heartbeat-cron.sh:

INTERVAL=300  # seconds (5 minutes)

Heartbeat Prompt

Edit .tinyclaw/heartbeat.md:

Check for:

1. Pending tasks
2. Errors
3. Unread messages

Take action if needed.

📊 Monitoring

View Logs

# WhatsApp activity
tail -f .tinyclaw/logs/whatsapp.log

# Queue processing
tail -f .tinyclaw/logs/queue.log

# Heartbeat checks
tail -f .tinyclaw/logs/heartbeat.log

# All logs
./tinyclaw.sh logs daemon

Watch Queue

# Incoming messages
watch -n 1 'ls -lh .tinyclaw/queue/incoming/'

# Outgoing responses
watch -n 1 'ls -lh .tinyclaw/queue/outgoing/'

🎨 Features

✅ No Race Conditions

Messages processed sequentially, one at a time:

Message 1 → Process → Done
Message 2 → Wait → Process → Done
Message 3 → Wait → Process → Done

✅ Multi-Channel Ready

Add Telegram by creating telegram-client.js:

// Write to queue
fs.writeFileSync(
  '.tinyclaw/queue/incoming/telegram_<id>.json',
  JSON.stringify({ channel: 'telegram', message, ... })
);

// Read responses
// Same format as WhatsApp

Queue processor handles it automatically!

✅ Clean Responses

Uses claude -c -p:

• -c = continue conversation
• -p = print mode (clean output)
• No tmux capture needed

✅ Persistent Sessions

WhatsApp session persists across restarts:

# First time: Scan QR code
./tinyclaw.sh start

# Subsequent starts: Auto-connects
./tinyclaw.sh restart

🔐 Security

• WhatsApp session stored locally in .tinyclaw/whatsapp-session/
• Queue files are local (no network exposure)
• Each channel handles its own authentication
• Claude runs with your user permissions

🐛 Troubleshooting

WhatsApp not connecting

# Check logs
./tinyclaw.sh logs whatsapp

# Re-authenticate
rm -rf .tinyclaw/whatsapp-session/
./tinyclaw.sh restart

Messages not processing

# Check queue processor
./tinyclaw.sh status

# Check queue
ls -la .tinyclaw/queue/incoming/

# View queue logs
./tinyclaw.sh logs queue

QR code not showing

# Use helper script
./show-qr.sh

# Or attach to tmux
tmux attach -t tinyclaw

🚀 Production Deployment

Using systemd

sudo systemctl enable tinyclaw
sudo systemctl start tinyclaw

Using PM2

pm2 start tinyclaw.sh --name tinyclaw
pm2 save

Using supervisor

[program:tinyclaw]
command=/path/to/tinyclaw/tinyclaw.sh start
autostart=true
autorestart=true

🎯 Use Cases

Personal AI Assistant

You: "Remind me to call mom"
Claude: "I'll remind you!"
[5 minutes later via heartbeat]
Claude: "Don't forget to call mom!"

Code Helper

You: "Review my code"
Claude: [reads files, provides feedback]
You: "Fix the bug"
Claude: [fixes and commits]

Multi-Device

• WhatsApp on phone
• Telegram on desktop
• CLI for scripts All share the same Claude conversation!

🙏 Credits

• Inspired by OpenClaw by Peter Steinberger
• Built on Claude Code
• Uses whatsapp-web.js

📄 License

MIT

---

TinyClaw - Small but mighty! 🦞✨