TinyClaw 🦞

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.

tinyclaw.mp4

✨ Features

✅ 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
✅ Web portal (TinyOffice) - Browser-based dashboard for chat, agents, teams, tasks, logs, and settings
✅ Team Observation - You can observe agent teams conversations via tinyclaw team visualize
✅ Multiple AI providers - Anthropic Claude, OpenAI Codex, and custom providers (any OpenAI/Anthropic-compatible endpoint)
✅ Parallel processing - Agents process messages concurrently
✅ Live TUI dashboard - Real-time team visualizer for monitoring agent chains
✅ Persistent sessions - Conversation context maintained across restarts
✅ SQLite queue - Atomic transactions, retry logic, dead-letter management
✅ Plugin system - Extend TinyClaw with custom plugins for message hooks and event listeners
✅ 24/7 operation - Runs in tmux for always-on availability

Community

Discord

We are actively looking for contributors. Please reach out.

🚀 Quick Start

Prerequisites

macOS, Linux and Windows (WSL2)
Node.js v18+
tmux, jq
Bash 3.2+
Claude Code CLI (for Anthropic provider)
Codex CLI (for OpenAI provider)

Installation

Option 1: One-line Install (Recommended)

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

Option 2: From Release

wget https://github.com/TinyAGI/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/TinyAGI/tinyclaw.git
cd tinyclaw && npm install && ./scripts/install.sh

First Run

tinyclaw start  # Runs interactive setup wizard

The setup wizard will guide you through:

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

📱 Channel Setup Guides

Discord Setup

Go to Discord Developer Portal
Create application → Bot section → Create bot
Copy bot token
Enable "Message Content Intent"
Invite bot using OAuth2 URL Generator

Telegram Setup

Open Telegram → Search @BotFather
Send /newbot → Follow prompts
Copy bot token
Start chat with your bot

WhatsApp Setup

After starting TinyClaw, scan the QR code:

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

📱 Settings → Linked Devices → Link a Device

🌐 TinyOffice Web Portal

TinyClaw includes tinyoffice/, a Next.js web portal for operating TinyClaw from the browser.

TinyOffice Features

Dashboard - Real-time queue/system overview and live event feed
Chat Console - Send messages to default agent, @agent, or @team
Agents & Teams - Create, edit, and remove agents/teams
Tasks (Kanban) - Create tasks, drag across stages, assign to agent/team
Logs & Events - Inspect queue logs and streaming events
Settings - Edit TinyClaw configuration (settings.json) via UI
Office View - Visual simulation of agent interactions

Run TinyOffice

Start TinyClaw first (API default: http://localhost:3777), then:

cd tinyoffice
npm install
npm run dev

Open http://localhost:3000.

If TinyClaw API is on a different host/port, set:

cd tinyoffice
echo 'NEXT_PUBLIC_API_URL=http://localhost:3777' > .env.local

📋 Commands

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

Core Commands

Command	Description	Example
`start`	Start TinyClaw daemon	`tinyclaw start`
`stop`	Stop all processes	`tinyclaw stop`
`restart`	Restart TinyClaw	`tinyclaw restart`
`status`	Show current status and activity	`tinyclaw status`
`setup`	Run setup wizard (reconfigure)	`tinyclaw setup`
`logs [type]`	View logs (discord/telegram/whatsapp/queue/heartbeat/all)	`tinyclaw logs queue`
`attach`	Attach to tmux session	`tinyclaw attach`

Agent Commands

Command	Description	Example
`agent list`	List all configured agents	`tinyclaw agent list`
`agent add`	Add new agent (interactive)	`tinyclaw agent add`
`agent show <id>`	Show agent configuration	`tinyclaw agent show coder`
`agent remove <id>`	Remove an agent	`tinyclaw agent remove coder`
`agent reset <id>`	Reset agent conversation	`tinyclaw agent reset coder`
`agent provider <id> [provider]`	Show or set agent's AI provider	`tinyclaw agent provider coder anthropic`
`agent provider <id> <p> --model <m>`	Set agent's provider and model	`tinyclaw agent provider coder openai --model gpt-5.3-codex`

Team Commands

Command	Description	Example
`team list`	List all configured teams	`tinyclaw team list`
`team add`	Add new team (interactive)	`tinyclaw team add`
`team show <id>`	Show team configuration	`tinyclaw team show dev`
`team remove <id>`	Remove a team	`tinyclaw team remove dev`
`team add-agent <t> <a>`	Add an existing agent to a team	`tinyclaw team add-agent dev reviewer`
`team remove-agent <t> <a>`	Remove an agent from a team	`tinyclaw team remove-agent dev reviewer`
`team visualize [id]`	Live TUI dashboard for team chains	`tinyclaw team visualize dev`

Configuration Commands

Command	Description	Example
`provider [name]`	Show or switch AI provider (global default only)	`tinyclaw provider anthropic`
`provider <name> --model <model>`	Switch provider and model; propagates to matching agents	`tinyclaw provider openai --model gpt-5.3-codex`
`model [name]`	Show or switch AI model; propagates to matching agents	`tinyclaw model opus`
`reset`	Reset all conversations	`tinyclaw reset`
`channels reset <channel>`	Reset channel authentication	`tinyclaw channels reset whatsapp`

Custom Provider Commands

Command	Description	Example
`provider list`	List all custom providers	`tinyclaw provider list`
`provider add`	Add a new custom provider	`tinyclaw provider add`
`provider remove <id>`	Remove a custom provider	`tinyclaw provider remove proxy`

Custom providers let you use any OpenAI or Anthropic-compatible API endpoint with the existing CLI harnesses. See docs/AGENTS.md for details.

Pairing Commands

Use sender pairing to control who can message your agents.

Command	Description	Example
`pairing pending`	Show pending sender approvals (with pairing codes)	`tinyclaw pairing pending`
`pairing approved`	Show approved senders	`tinyclaw pairing approved`
`pairing list`	Show both pending and approved senders	`tinyclaw pairing list`
`pairing approve <code>`	Move a sender from pending to approved by code	`tinyclaw pairing approve ABCD1234`
`pairing unpair <channel> <sender_id>`	Remove an approved sender from the allowlist	`tinyclaw pairing unpair telegram 1234567`

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.

Update Commands

Command	Description	Example
`update`	Update TinyClaw to latest version	`tinyclaw update`

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/TinyAGI/tinyclaw/main/scripts/remote-install.sh | bash
Your settings and user data will be preserved.

Update Details

Auto-detection: TinyClaw checks for updates on startup (once per hour).

Manual update:

tinyclaw update

This will:

Check for latest release
Show changelog URL
Download bundle
Create backup of current installation
Install new version

Disable update checks:

export TINYCLAW_SKIP_UPDATE_CHECK=1

Messaging Commands

Command	Description	Example
`send <message>`	Send message to AI manually	`tinyclaw send "Hello!"`
`send <message>`	Route to specific agent	`tinyclaw send "@coder fix bug"`

In-Chat Commands

These commands work in Discord, Telegram, and WhatsApp:

Command	Description	Example
`@agent_id message`	Route message to specific agent	`@coder fix the bug`
`@team_id message`	Route message to team leader	`@dev fix the auth bug`
`/agent`	List all available agents	`/agent`
`/team`	List all available teams	`/team`
`@agent_id /reset`	Reset specific agent conversation	`@coder /reset`
`/reset`	Reset conversation (WhatsApp/global)	`/reset` or `!reset`
`/restart`	Restart TinyClaw process	`/restart`
`message`	Send to default agent (no prefix)	`help me with this`

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.

🤖 Using Agents

Routing Messages

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)

Agent Configuration

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

📖 Learn more about agents

See docs/AGENTS.md for:

Architecture details
Agent configuration
Use cases and examples
Advanced features
Troubleshooting

📐 Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Message Channels                         │
│         (Discord, Telegram, WhatsApp, Web, API)             │
└────────────────────┬────────────────────────────────────────┘
                     │ enqueueMessage()
                     ↓
┌─────────────────────────────────────────────────────────────┐
│               ~/.tinyclaw/tinyclaw.db (SQLite)               │
│                                                              │
│  messages: pending → processing → completed / dead          │
│  responses: pending → acked                                  │
│                                                              │
└────────────────────┬────────────────────────────────────────┘
                     │ 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:

SQLite queue - Atomic transactions via WAL mode, no race conditions
Parallel agents - Different agents process messages concurrently
Sequential per agent - Preserves conversation order within each agent
Retry & dead-letter - Failed messages retry up to 5 times, then enter dead-letter queue
Isolated workspaces - Each agent has its own directory and context

📖 Learn more about the queue system

See docs/QUEUE.md for:

Detailed message flow
Parallel processing explanation
Performance characteristics
Debugging tips

📁 Directory Structure

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
├── tinyoffice/           # TinyOffice web portal (Next.js)
└── tinyclaw.sh           # Main script

⚙️ Configuration

Settings File

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

Heartbeat Configuration

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.

🎯 Use Cases

Personal AI Assistant

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

Multi-Agent Workflow

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

Team Collaboration

@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.

Cross-Device Access

WhatsApp on phone
Discord on desktop
Telegram anywhere
CLI for automation

All channels share agent conversations!

🐳 Docker

For containerized deployment with API authentication, health checks, and process isolation, see tinyclaw-infra. No changes to TinyClaw required.

📚 Documentation

AGENTS.md - Agent management and routing
TEAMS.md - Team collaboration, chain execution, and visualizer
QUEUE.md - Queue system and message flow
tinyoffice/README.md - TinyOffice web portal
PLUGINS.md - Plugin development guide
TROUBLESHOOTING.md - Common issues and solutions
tinyclaw-infra - Docker deployment and auth proxy

🐛 Troubleshooting

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:

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
Corrupted settings.json → TinyClaw auto-repairs invalid JSON (trailing commas, comments, BOM) and creates a .bak backup

Need help?

GitHub Issues
Check logs: tinyclaw logs all

🙏 Credits

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

📄 License

MIT

TinyClaw - Tiny but mighty! 🦞✨

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
.agents/skills		.agents/skills
.github		.github
bin		bin
docs		docs
lib		lib
scripts		scripts
src		src
tinyoffice		tinyoffice
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SOUL.md		SOUL.md
heartbeat.md		heartbeat.md
package-lock.json		package-lock.json
package.json		package.json
tinyclaw.sh		tinyclaw.sh
tsconfig.json		tsconfig.json
tsconfig.visualizer.json		tsconfig.visualizer.json

Folders and files

Latest commit

History

Repository files navigation