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 chat rooms - Persistent async chat rooms per team with real-time CLI viewer
✅ Multiple AI providers - Anthropic Claude, OpenAI Codex, and custom providers (any OpenAI/Anthropic-compatible endpoint)
✅ Auth token management - Store API keys per provider, no separate CLI auth needed
✅ Parallel processing - Agents process messages concurrently
✅ Live TUI dashboard - Real-time team visualizer and chatroom viewer
✅ 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

Other installation methods

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

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, bot tokens, workspace setup, default agent, AI provider, model selection, and heartbeat interval.

📱 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 & Setup

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:

tinyclaw office

This auto-installs dependencies, builds, and starts the production server on http://localhost:3000.

For development with hot-reload:

cd tinyoffice
npm install
npm run dev

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`

Chatroom Commands

Command	Description	Example
`chatroom <team>`	Real-time TUI viewer with type-to-send	`tinyclaw chatroom dev`
`office`	Start TinyOffice web portal on port 3000	`tinyclaw office`

Every team has a persistent chat room. Agents post to it using [#team_id: message] tags, and messages are broadcast to all teammates. The chatroom viewer polls for new messages in real time — type a message and press Enter to post, or press q/Esc to quit.

API endpoints:

GET  /api/chatroom/:teamId          # Get messages (?limit=100&since=0)
POST /api/chatroom/:teamId          # Post a message (body: { "message": "..." })

Provider & Custom Provider Commands

Command	Description	Example
`provider [name]`	Show or switch global AI provider	`tinyclaw provider anthropic`
`provider <name> --model <model>`	Switch provider and model; propagates to matching agents	`tinyclaw provider openai --model gpt-5.3-codex`
`provider <name> --auth-token <key>`	Store API key for a built-in provider	`tinyclaw provider anthropic --auth-token sk-...`
`provider list`	List all custom providers	`tinyclaw provider list`
`provider add`	Add a new custom provider (interactive)	`tinyclaw provider add`
`provider remove <id>`	Remove a custom provider	`tinyclaw provider remove proxy`
`model [name]`	Show or switch AI model	`tinyclaw model opus`

Custom provider details

Custom providers let you use any OpenAI or Anthropic-compatible API endpoint (e.g., OpenRouter, proxy servers, self-hosted models).

Define a custom provider in settings.json:

{
  "custom_providers": {
    "my-proxy": {
      "name": "My Proxy",
      "harness": "claude",
      "base_url": "https://proxy.example.com/v1",
      "api_key": "sk-...",
      "model": "claude-sonnet-4-5"
    }
  }
}

Field	Required	Description
`name`	Yes	Human-readable display name
`harness`	Yes	CLI to use: `claude` or `codex`
`base_url`	Yes	API endpoint URL
`api_key`	Yes	API key for authentication
`model`	No	Default model name for CLI

Assign a custom provider to an agent:

tinyclaw agent provider coder custom:my-proxy
tinyclaw agent provider coder custom:my-proxy --model gpt-4o

Auth token storage — store API keys for built-in providers so you don't need separate CLI auth:

tinyclaw provider anthropic --auth-token sk-ant-...
tinyclaw provider openai --auth-token sk-...

Tokens are saved in settings.json under models.<provider>.auth_token and automatically exported as ANTHROPIC_API_KEY / OPENAI_API_KEY when invoking CLIs.

API endpoints:

GET    /api/custom-providers              # List custom providers
PUT    /api/custom-providers/:id          # Create or update
DELETE /api/custom-providers/:id          # Delete

See docs/AGENTS.md for more 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.

Messaging & in-chat 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"`

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.

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.

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

Disable update checks:

export TINYCLAW_SKIP_UPDATE_CHECK=1

Configuration commands

Command	Description	Example
`reset`	Reset all conversations	`tinyclaw reset`
`channels reset <chan>`	Reset channel authentication	`tinyclaw channels reset whatsapp`

🤖 Using Agents

Use @agent_id prefix to route messages to specific agents:

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

Agent configuration

Agents are configured in .tinyclaw/settings.json:

{
  "agents": {
    "coder": {
      "name": "Code Assistant",
      "provider": "anthropic",
      "model": "sonnet",
      "working_directory": "/Users/me/tinyclaw-workspace/coder"
    },
    "writer": {
      "name": "Technical Writer",
      "provider": "custom:my-proxy",
      "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

See docs/AGENTS.md for full details on architecture, use cases, and advanced features.

📐 Architecture

Message flow diagram

┌─────────────────────────────────────────────────────────────┐
│                     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

See docs/QUEUE.md for detailed queue system documentation.

⚙️ Configuration

Settings file reference

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"
    }
  },
  "custom_providers": {
    "my-proxy": {
      "name": "My Proxy",
      "harness": "claude",
      "base_url": "https://proxy.example.com/v1",
      "api_key": "sk-...",
      "model": "claude-sonnet-4-5"
    }
  },
  "models": {
    "anthropic": { "auth_token": "sk-ant-..." },
    "openai": { "auth_token": "sk-..." }
  },
  "monitoring": {
    "heartbeat_interval": 3600
  }
}

Heartbeat configuration

Edit agent-specific heartbeat prompts:

nano ~/tinyclaw-workspace/coder/heartbeat.md

Default heartbeat prompt:

Check for:

1. Pending tasks
2. Errors
3. Unread messages

Take action if needed.

Directory structure

tinyclaw/
├── packages/                # Monorepo packages
│   ├── core/                #   Shared types, config, queue, agent invocation
│   ├── main/                #   Queue processor entry point
│   ├── teams/               #   Team conversation orchestration
│   ├── server/              #   API server (REST + SSE)
│   ├── channels/            #   Channel clients (Discord, Telegram, WhatsApp)
│   ├── cli/                 #   CLI commands (tinyclaw.sh helpers)
│   └── visualizer/          #   TUI dashboard and chatroom viewer
├── tinyoffice/              # TinyOffice web portal (Next.js)
├── .tinyclaw/               # TinyClaw data (created at runtime)
│   ├── settings.json        #   Configuration
│   ├── tinyclaw.db          #   SQLite queue database
│   ├── logs/                #   All logs
│   ├── channels/            #   Channel state
│   ├── files/               #   Uploaded files
│   ├── pairing.json         #   Sender allowlist state
│   ├── chats/               #   Team conversation history
│   │   └── {team_id}/       #     Per-team chat logs
│   ├── .claude/             #   Template for agents
│   ├── heartbeat.md         #   Template for agents
│   └── AGENTS.md            #   Template for agents
├── ~/tinyclaw-workspace/    # Agent workspaces
│   ├── coder/
│   ├── writer/
│   └── assistant/
├── lib/                     # Runtime scripts
├── scripts/                 # Installation scripts
└── tinyclaw.sh              # Main script

🎯 Use Cases

Examples

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!

📚 Documentation

AGENTS.md - Agent management, routing, and custom providers
TEAMS.md - Team collaboration, chain execution, chat rooms, 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

🐛 Troubleshooting

Quick fixes & common issues

# 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 · 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! 🦞✨

Navigation Menu

Repository navigation

README.md

README.md

TinyClaw 🦞

✨ Features

Community

🚀 Quick Start

Prerequisites

Installation

First Run

Discord Setup

Telegram Setup

WhatsApp Setup

🌐 TinyOffice Web Portal

Run TinyOffice

📋 Commands

Core Commands

Agent Commands

Team Commands

Chatroom Commands

Provider & Custom Provider Commands

🤖 Using Agents

📐 Architecture

⚙️ Configuration

🎯 Use Cases

Personal AI Assistant

Multi-Agent Workflow

Team Collaboration

Cross-Device Access

📚 Documentation

🐛 Troubleshooting

🙏 Credits

📄 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

TinyClaw 🦞

✨ Features

Community

🚀 Quick Start

Prerequisites

Installation

First Run

Discord Setup

Telegram Setup

WhatsApp Setup

🌐 TinyOffice Web Portal

Run TinyOffice

📋 Commands

Core Commands

Agent Commands

Team Commands

Chatroom Commands

Provider & Custom Provider Commands

🤖 Using Agents

📐 Architecture

⚙️ Configuration

🎯 Use Cases

Personal AI Assistant

Multi-Agent Workflow

Team Collaboration

Cross-Device Access

📚 Documentation

🐛 Troubleshooting

🙏 Credits

📄 License