Multi-agent, Multi-team, Multi-channel, 24/7 AI assistant

Run multiple teams of AI agents that collaborate with each other simultaneously with isolated workspaces.

• ✅ Multi-agent - Run multiple isolated AI agents with specialized roles
• ✅ Multi-team collaboration - Agents hand off work to teammates via chain execution and fan-out
• ✅ Multi-channel - Discord, WhatsApp, and Telegram
• ✅ Team Observation - You can observe agent teams conversations via tinyclaw team visualize
• ✅ Multiple AI providers - Anthropic Claude and OpenAI Codex using existing subscriptions without breaking ToS
• ✅ Parallel processing - Agents process messages concurrently
• ✅ Live TUI dashboard - Real-time team visualizer for monitoring agent chains
• ✅ Persistent sessions - Conversation context maintained across restarts
• ✅ File-based queue - No race conditions, reliable message handling
• ✅ 24/7 operation - Runs in tmux for always-on availability

• macOS or Linux
• Node.js v14+
• tmux
• Bash 4.0+ (macOS: brew install bash)
• Claude Code CLI (for Anthropic provider)
• Codex CLI (for OpenAI provider)

Option 1: One-line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/jlia0/tinyclaw/main/scripts/remote-install.sh | bash

Option 2: From Release

wget https://github.com/jlia0/tinyclaw/releases/latest/download/tinyclaw-bundle.tar.gz
tar -xzf tinyclaw-bundle.tar.gz
cd tinyclaw && ./scripts/install.sh

Option 3: From Source

git clone https://github.com/jlia0/tinyclaw.git
cd tinyclaw && npm install && ./scripts/install.sh

tinyclaw start  # Runs interactive setup wizard

The setup wizard will guide you through:

1. Channel selection - Choose Discord, WhatsApp, and/or Telegram
2. Bot tokens - Enter tokens for enabled channels
3. Workspace setup - Name your workspace directory
4. Default agent - Configure your main AI assistant
5. AI provider - Select Anthropic (Claude) or OpenAI
6. Model selection - Choose model (e.g., Sonnet, Opus, GPT-5.3)
7. Heartbeat interval - Set proactive check-in frequency

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     WhatsApp QR Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[QR CODE HERE]

📱 Settings → Linked Devices → Link a Device

Commands work with tinyclaw (if CLI installed) or ./tinyclaw.sh (direct script).

Use sender pairing to control who can message your agents.

Pairing behavior:

• First message from unknown sender: TinyClaw generates a code and sends approval instructions.
• Additional messages while still pending: TinyClaw blocks silently (no repeated pairing message).
• After approval: messages from that sender are processed normally.

Note: If you are on v0.0.1 or v0.0.2, the update script was broken. Please re-install instead:

curl -fsSL https://raw.githubusercontent.com/jlia0/tinyclaw/main/scripts/remote-install.sh | bash

Your settings and user data will be preserved.

tinyclaw update

export TINYCLAW_SKIP_UPDATE_CHECK=1

These commands work in Discord, Telegram, and WhatsApp:

Note: The @agent_id routing prefix requires a space after it (e.g., @coder fix not @coderfix).

Access control note: before routing, channel clients apply sender pairing allowlist checks.

Use @agent_id prefix to route messages to specific agents (see In-Chat Commands table above):

@coder fix the authentication bug
@writer document the API endpoints
@researcher find papers on transformers
help me with this  ← goes to default agent (no prefix needed)

Agents are configured in .tinyclaw/settings.json:

{
  "workspace": {
    "path": "/Users/me/tinyclaw-workspace",
    "name": "tinyclaw-workspace"
  },
  "agents": {
    "coder": {
      "name": "Code Assistant",
      "provider": "anthropic",
      "model": "sonnet",
      "working_directory": "/Users/me/tinyclaw-workspace/coder"
    },
    "writer": {
      "name": "Technical Writer",
      "provider": "openai",
      "model": "gpt-5.3-codex",
      "working_directory": "/Users/me/tinyclaw-workspace/writer"
    }
  }
}

Each agent operates in isolation:

• Separate workspace directory - ~/tinyclaw-workspace/{agent_id}/
• Own conversation history - Maintained by CLI
• Custom configuration - .claude/, heartbeat.md (root), AGENTS.md
• Independent resets - Reset individual agent conversations

┌─────────────────────────────────────────────────────────────┐
│                     Message Channels                         │
│         (Discord, Telegram, WhatsApp, Heartbeat)            │
└────────────────────┬────────────────────────────────────────┘
                     │ Write message.json
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                   ~/.tinyclaw/queue/                         │
│                                                              │
│  incoming/          processing/         outgoing/           │
│  ├─ msg1.json  →   ├─ msg1.json   →   ├─ msg1.json        │
│  ├─ msg2.json       └─ msg2.json       └─ msg2.json        │
│  └─ msg3.json                                                │
│                                                              │
└────────────────────┬────────────────────────────────────────┘
                     │ Queue Processor
                     ↓
┌─────────────────────────────────────────────────────────────┐
│              Parallel Processing by Agent                    │
│                                                              │
│  Agent: coder        Agent: writer       Agent: assistant   │
│  ┌──────────┐       ┌──────────┐        ┌──────────┐       │
│  │ Message 1│       │ Message 1│        │ Message 1│       │
│  │ Message 2│ ...   │ Message 2│  ...   │ Message 2│ ...   │
│  │ Message 3│       │          │        │          │       │
│  └────┬─────┘       └────┬─────┘        └────┬─────┘       │
│       │                  │                     │            │
└───────┼──────────────────┼─────────────────────┼────────────┘
        ↓                  ↓                     ↓
   claude CLI         claude CLI             claude CLI
  (workspace/coder)  (workspace/writer)  (workspace/assistant)

Key features:

• File-based queue - Atomic operations, no race conditions
• Parallel agents - Different agents process messages concurrently
• Sequential per agent - Preserves conversation order within each agent
• Isolated workspaces - Each agent has its own directory and context

tinyclaw/
├── .tinyclaw/            # TinyClaw data
│   ├── settings.json     # Configuration
│   ├── queue/            # Message queue
│   │   ├── incoming/
│   │   ├── processing/
│   │   └── outgoing/
│   ├── logs/             # All logs
│   ├── channels/         # Channel state
│   ├── files/            # Uploaded files
│   ├── pairing.json      # Sender allowlist state (pending + approved)
│   ├── chats/            # Team chain chat history
│   │   └── {team_id}/    # Per-team chat logs
│   ├── events/           # Real-time event files
│   ├── .claude/          # Template for agents
│   ├── heartbeat.md      # Template for agents
│   └── AGENTS.md         # Template for agents
├── ~/tinyclaw-workspace/ # Agent workspaces
│   ├── coder/
│   │   ├── .claude/
│   │   ├── heartbeat.md
│   │   └── AGENTS.md
│   ├── writer/
│   └── assistant/
├── src/                  # TypeScript sources
├── dist/                 # Compiled output
├── lib/                  # Runtime scripts
├── scripts/              # Installation scripts
└── tinyclaw.sh           # Main script

Located at .tinyclaw/settings.json:

{
  "channels": {
    "enabled": ["discord", "telegram", "whatsapp"],
    "discord": { "bot_token": "..." },
    "telegram": { "bot_token": "..." },
    "whatsapp": {}
  },
  "workspace": {
    "path": "/Users/me/tinyclaw-workspace",
    "name": "tinyclaw-workspace"
  },
  "agents": {
    "assistant": {
      "name": "Assistant",
      "provider": "anthropic",
      "model": "sonnet",
      "working_directory": "/Users/me/tinyclaw-workspace/assistant"
    }
  },
  "teams": {
    "dev": {
      "name": "Development Team",
      "agents": ["coder", "reviewer"],
      "leader_agent": "coder"
    }
  },
  "monitoring": {
    "heartbeat_interval": 3600
  }
}

Edit agent-specific heartbeat prompts:

# Edit heartbeat for specific agent
nano ~/tinyclaw-workspace/coder/heartbeat.md

Default heartbeat prompt:

Check for:

1. Pending tasks
2. Errors
3. Unread messages

Take action if needed.

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

@coder Review and fix bugs in auth.ts
@writer Document the changes
@reviewer Check the documentation quality

@dev fix the auth bug
# → Routes to team leader (@coder)
# → Coder fixes bug, mentions @reviewer in response
# → Reviewer automatically invoked, reviews changes
# → Combined response sent back to user

Teams support sequential chains (single handoff) and parallel fan-out (multiple teammate mentions). See docs/TEAMS.md for details.

• WhatsApp on phone
• Discord on desktop
• Telegram anywhere
• CLI for automation

All channels share agent conversations!

• AGENTS.md - Agent management and routing
• TEAMS.md - Team collaboration, chain execution, and visualizer
• QUEUE.md - Queue system and message flow
• TROUBLESHOOTING.md - Common issues and solutions

See docs/TROUBLESHOOTING.md for detailed solutions.

Quick fixes:

# Reset everything (preserves settings)
tinyclaw stop && rm -rf .tinyclaw/queue/* && tinyclaw start

# Reset WhatsApp
tinyclaw channels reset whatsapp

# Check status
tinyclaw status

# View logs
tinyclaw logs all

Common issues:

• Bash version error → Install bash 4.0+: brew install bash
• WhatsApp not connecting → Reset auth: tinyclaw channels reset whatsapp
• Messages stuck → Clear queue: rm -rf .tinyclaw/queue/processing/*
• Agent not found → Check: tinyclaw agent list

Need help?

• GitHub Issues
• Check logs: tinyclaw logs all

• Inspired by OpenClaw by Peter Steinberger
• Built on Claude Code and Codex CLI
• Uses discord.js, whatsapp-web.js, node-telegram-bot-api

MIT

TinyClaw - Tiny but mighty! 🦞✨