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 a web portal for managing your agents, teams, tasks, and chat — all from the browser.

Once you start running TinyClaw locally, you can control it by visiting office.tinyagicompany.com. It connects to your local TinyClaw API at localhost:3777 — no account or sign-up needed.

Alternatively, you can run TinyOffice locally:

tinyclaw office  # Builds and starts on http://localhost:3000

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
Org Chart - Hierarchical visualization of teams and agents
Chat Rooms - Slack-style persistent chat rooms per team
Projects - Project-level task management with filtered kanban boards

Running Locally

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

tinyclaw office

This auto-detects when dependencies or builds are needed (e.g. after tinyclaw update) 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! 🦞✨

Name		Name	Last commit message	Last commit date
Latest commit History 132 Commits
.agents/skills		.agents/skills
.github		.github
bin		bin
docs		docs
lib		lib
packages		packages
scripts		scripts
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.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

TinyClaw 🦞

✨ Features

Community

🚀 Quick Start

Prerequisites

Installation

First Run

Discord Setup

Telegram Setup

WhatsApp Setup

🌐 TinyOffice Web Portal

Running Locally

📋 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

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages