🐾 TinyClaw Guide

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

tinyclaw start

export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc  # or ~/.zshrc

tinyclaw setup

{
  "workspace": {
    "path": "/Users/me/tinyclaw-workspace",
    "name": "tinyclaw-workspace"
  },
  "channels": {
    "enabled": ["discord", "telegram", "whatsapp"],
    "discord": { "bot_token": "..." },
    "telegram": { "bot_token": "..." },
    "whatsapp": {}
  },
  "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"
    }
  },
  "teams": {
    "dev": {
      "name": "Development Team",
      "agents": ["coder", "reviewer"],
      "leader_agent": "coder"
    }
  },
  "monitoring": {
    "heartbeat_interval": 3600
  }
}

# Add a new agent via CLI
tinyclaw agent add \
  --name coder \
  --provider anthropic \
  --model opus \
  --role "Primary development agent — writes, tests, and ships code"

# Add a reviewer agent
tinyclaw agent add \
  --name reviewer \
  --provider anthropic \
  --model sonnet \
  --role "Review code for bugs, security issues, and performance"

# Add a writer agent (different provider)
tinyclaw agent add \
  --name writer \
  --provider openai \
  --model gpt-5.3-codex \
  --role "Technical Writer — document the API and write user guides"

tinyclaw agent list          # List all agents
tinyclaw agent info coder    # Show agent details
tinyclaw agent remove coder  # Remove an agent

# Switch provider for an agent
tinyclaw provider anthropic --model sonnet
tinyclaw provider openai --model gpt-4o
tinyclaw provider openai --model gpt-5.3-codex

# Or switch separately
tinyclaw provider anthropic   # Switch provider only
tinyclaw model opus            # Switch model only
tinyclaw model gpt-5.2         # Switch to OpenAI model

# Reset specific agent(s) conversation history
tinyclaw reset coder
tinyclaw reset coder writer reviewer

# In-chat: reset current agent's conversation
/reset coder

# Create a dev team with a leader
tinyclaw team add \
  --name dev \
  --agents coder,reviewer,builder \
  --leader coder

# List teams
tinyclaw team list

# Visualize team activity (live TUI)
tinyclaw team visualize dev

# In your chat channel:
@dev fix the authentication bug

# TinyClaw automatically:
# → Routes to team leader (@coder)
# → @coder fixes bug, mentions @reviewer in response
# → @reviewer automatically invoked, reviews changes
# → Combined response sent back to you

{
  "teams": {
    "dev": {
      "name": "Development Team",
      "agents": ["coder", "reviewer", "builder"],
      "leader_agent": "coder"
    },
    "content": {
      "name": "Content Team",
      "agents": ["writer", "editor", "seo"],
      "leader_agent": "writer"
    }
  }
}

# Route to specific agent
@coder fix the authentication bug
@writer document the API endpoints
@reviewer check the documentation quality
@researcher find papers on transformers

# Route to team
@dev build the new payment feature

# No prefix → goes to default agent
help me with this task

# Example: Agent set up to remind you
# You say: "Remind me to call mom"
# Agent: "I'll remind you!"
# [1 hour later via heartbeat]
# Agent: "Don't forget to call mom!"

# Set heartbeat in settings.json
{
  "monitoring": {
    "heartbeat_interval": 3600  // seconds
  }
}

tinyclaw channels reset discord  # Shows Discord reset instructions

tinyclaw channels reset telegram  # Shows Telegram reset instructions

tinyclaw channels reset whatsapp  # Clear WhatsApp session

# Send a message to default agent
tinyclaw send "What's the weather?"

# Send to specific agent
tinyclaw send "@coder review the latest changes"

# Attach to live tmux session (interactive)
tmux attach -t tinyclaw
# or
tinyclaw attach

# 1. Start TinyClaw first (provides the API at :3777)
tinyclaw start

# 2. Navigate to TinyOffice directory
cd tinyoffice

# 3. Install dependencies
npm install

# 4. Set backend URL (default: http://localhost:3777)
export NEXT_PUBLIC_API_URL=http://localhost:3777

# 5. Start development server
npm run dev

# 6. Open in browser
open http://localhost:3000

// plugins/my-logger/index.js
module.exports = {
  name: 'my-logger',
  version: '1.0.0',

  // Called for every incoming message
  onMessage: async (message, context) => {
    console.log(`[Plugin] Message from ${message.channel}: ${message.text}`);
    return message; // pass through (or modify)
  },

  // Called on system events
  onEvent: async (event) => {
    if (event.type === 'agent.complete') {
      console.log(`Agent ${event.agentId} finished task`);
    }
  }
};

workspace/
└── coder/
    ├── .agent/
    │   └── skills/
    │       ├── browser-automation.md
    │       ├── skill-creator.md
    │       └── tinyclaw-admin.md
    └── .claude/
        └── CLAUDE.md           # Agent context & instructions

# .agent/skills/database-expert.md

# Database Expert Skill

You are an expert in SQL, PostgreSQL, Redis, and MongoDB.

## When to use this skill
- When asked about database queries, optimization, or design
- When debugging slow queries or schema issues

## Key capabilities
- Write optimized SQL queries
- Design normalized schemas
- Troubleshoot performance issues

tinyclaw pairing pending          # List pending pairing requests
tinyclaw pairing approve <code>  # Approve a sender by code
tinyclaw pairing list             # List all approved senders
tinyclaw pairing unpair <id>     # Remove a sender's approval

# Clone both repos
git clone https://github.com/TinyAGI/tinyclaw.git
git clone https://github.com/shwdsun/tinyclaw-infra.git

# Configure environment
cd tinyclaw-infra
cp .env.example .env
# Edit .env: set API_KEY, provider keys, bot tokens

# Start all services
docker compose up -d

# Prometheus metrics available at :9090

# docker-compose.override.yml
worker-coder:
  build:
    context: .
    dockerfile: docker/Dockerfile.worker
  environment:
    - GATEWAY_URL=http://gateway:8080
    - API_KEY=${API_KEY}
    - AGENT_ID=coder
    - PROVIDER=anthropic
    - MODEL=sonnet
    - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  volumes:
    - code-workspace:/workspace
  networks:
    - workers

# Add to PATH manually
export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc  # or ~/.zshrc for zsh

# Or use the script directly
./tinyclaw.sh start

brew install bash
# Then add /usr/local/bin/bash to /etc/shells

# Re-install instead of updating (settings preserved)
curl -fsSL https://raw.githubusercontent.com/TinyAGI/tinyclaw/main/scripts/remote-install.sh | bash

tinyclaw logs all                  # All logs
tmux attach -t tinyclaw            # Live session
systemctl --user status tinyclaw.service  # Systemd status