TinyClaw: Multi-Agent AI Teams for Discord, WhatsApp, Telegram

TinyClaw: A Multi‑Agent AI Team Framework

1. What is TinyClaw?

TinyClaw is a community‑driven, MIT‑licensed tool that turns a handful of AI providers (Claude, OpenAI, etc.) into a team of agents. Each agent runs in its own isolated workspace, keeps its own conversation history, and can hand off work to coworkers using a simple, prefix‑based command system. The name TinyClaw reflects the idea that small code can still manage complex collaboration.

Key concepts: - Agent – a single AI instance with a defined role. - Team – a group of agents that chain together or fan‑out when processing a query. - Channel – where the agents receive messages (Discord, WhatsApp, Telegram, heartbeat).

All of the heavy lifting is done by the CLI and simple JSON configuration files, so you can run TinyClaw on macOS, Linux, or WSL‑2 Windows.

2. Core Features

3. Architectural Overview

TinyClaw’s architecture is intentionally simple, making it easy to debug or extend:

1. Channels – Bots listen for incoming messages and write a JSON file to ~/.tinyclaw/queue/incoming/.
2. Queue Processor – A watchdog that moves each file to processing/, then dispatches it to the appropriate agent.
3. Agents – Each agent runs in its own isolated directory under ~/tinyclaw-workspace/<agent_id>/. The agent uses the configured provider’s CLI (Claude’s claude or OpenAI’s codex).
4. Persistence – Conversations and agent state live inside the workspace directory. On shutdown, the file-based queue is cleared, but logs remain.
5. Visualization – tinyclaw team visualize <id> opens a curses‑style UI that shows live message history and agent status.

This flow keeps the system deterministic while still permitting high throughput.

4. Quick‑Start Guide

Below is a step‑by‑step setup that gets a running TinyClaw instance in minutes.

Prerequisites – macOS/Linux/WSL2 with Node v18+, tmux, jq, a Bash 4.0+ (macOS: brew install bash), Claude Code CLI, and Codex CLI.

4.1 One‑liner Install (recommended)

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

4.2 Manual Build From Source

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

4.3 First Run & Setup Wizard

tinyclaw start   # Boots the Tmux session and interactive wizard

After completion, TinyClaw starts its daemon and you can interact from any connected channel.

5. Configuring Agents and Teams

Agent and team settings are stored in ~/.tinyclaw/settings.json.

5.1 Example Configuration

{
  "channels": {
    "enabled": ["discord", "telegram", "whatsapp"],
    "discord": { "bot_token": "YOUR_DISCORD_TOKEN" },
    "telegram": { "bot_token": "YOUR_TELEGRAM_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"
    },
    "coder": {
      "name": "Code Assistant",
      "provider": "anthropic",
      "model": "sonnet",
      "working_directory": "/Users/me/tinyclaw-workspace/coder"
    }
  },
  "teams": {
    "dev": {
      "name": "Development Team",
      "agents": ["coder", "reviewer"],
      "leader_agent": "coder"
    }
  },
  "monitoring": {
    "heartbeat_interval": 3600
  }
}

• Each agent directory contains its own .claude/, heartbeat.md, and AGENTS.md templates.
• Teams can chain or fan‑out; the leader agent receives the original request.

5.2 Adding New Agents

tinyclaw agent add

5.3 Removing Agents & Teams

tinyclaw agent remove coder
tinyclaw team remove dev

6. Channel Set‑Up Guides

• Discord – Create a bot in the Developer Portal, enable Message Content Intent, and paste the token.
• Telegram – Use BotFather to create a bot and fetch its token.
• WhatsApp – After startup, scan the QR code that appears in the terminal.

See the docs directory for full screenshots and detailed instructions.

7. Using the CLI

TinyClaw’s CLI has dozens of commands. Below are the most common: | Command | Purpose | |---------|---------| | tinyclaw start/stop/restart | Control the daemon. | | tinyclaw status | Show current processes and agents. | | tinyclaw setup | Re‑run the wizard to change configuration. | | tinyclaw logs <type> | Tail logs (discord, whatsapp, queue, etc.). | | tinyclaw attach | Attach to the running Tmux session. | | tinyclaw agent list | View configured agents. | | tinyclaw team visualize <id> | Open the live dashboard. | | tinyclaw update | Self‑update from GitHub releases. |

7.1 In‑chat Commands

When a user sends a message through a channel the following prefixes apply: - @agent_id <msg> – directs to a specific agent. - @team_id <msg> – forwards to the team leader. - /agent and /team – list available agents or teams.

A message without a prefix goes to the default agent.

8. Advanced Features

8.1 Heartbeat Monitoring

Agents can be scheduled to run routine “check‑ins” by editing ~/tinyclaw-workspace/<agent_id>/heartbeat.md. The default prompt is:

Check for:
1. Pending tasks
2. Errors
3. Unread messages
Take action if needed.

8.2 Sender Pairing

To prevent spam, TinyClaw generates a pairing code on the first message from an unknown sender. The code must be approved via tinyclaw pairing approve <code>.

8.3 Team Visualization

Running tinyclaw team visualize dev opens a curses UI that shows each agent’s pending messages in real time, making it easy to debug and observe AI chatter.

9. Use Cases

1. Personal AI Assistant – Remind yourself, manage a to‑do list, and schedule events.
2. Code Review Pipeline – @coder fixes a bug, @reviewer checks style, then the result is sent back to the user.
3. Documentation Generator – @writer creates API docs from code comments.
4. Multi‑Channel Presence – One conversation can be accessed from Discord, WhatsApp, or Telegram simultaneously.

10. Community & Contributing

TinyClaw is open for contributions. The main repo is on GitHub with 2.2k stars and 318 forks. Community channels: - Discord – https://discord.com/invite/jH6AcEChuD - GitHub Issues – report bugs or suggest features.

The project follows a simple CI workflow: tests run on every PR, and the release process is automated via GitHub Actions. New contributors can start by picking open issues or adding documentation.

11. License & Credit

MIT license. TinyClaw was inspired by OpenClaw and leverages Claude Code and Codex CLIs, as well as popular Node libraries: discord.js, whatsapp-web.js, node-telegram-bot-api.

12. Conclusion

TinyClaw offers a plug‑and‑play environment for experimenting with sophisticated agent orchestration without the overhead of a massive stack. Its tiny footprint belies a rich set of features that let developers build chat‑centric workflows, integrate multiple AI models, and monitor agent conversations live. Try it out today – with a one‑liner install, you’ll have a multi‑team, cross‑platform AI assistant up and running in minutes. Happy hacking!