### Chatroom Commands

| Command | Description | Example |
| ------------------- | --------------------------------------------- | -------------------------- |
| `chatroom ` | Real-time TUI viewer with type-to-send | `tinyagi chatroom dev` |
| `office` | Start TinyOffice web portal on port 3000 | `tinyagi 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 | `tinyagi provider anthropic` |
| `provider --model ` | Switch provider and model; propagates to matching agents | `tinyagi provider openai --model gpt-5.3-codex` |
| `provider --oauth-token ` | Store OAuth token for a built-in provider | `tinyagi provider anthropic --oauth-token sk-ant-oat01-...` |
| `provider list` | List all custom providers | `tinyagi provider list` |
| `provider add` | Add a new custom provider (interactive) | `tinyagi provider add` |
| `provider remove ` | Remove a custom provider | `tinyagi provider remove proxy` |
| `model [name]` | Show or switch AI model | `tinyagi 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`:**

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

| 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:**

```bash
tinyagi agent provider coder custom:my-proxy
tinyagi agent provider coder custom:my-proxy --model gpt-4o
```

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

```bash
tinyagi provider anthropic --oauth-token sk-ant-oat01-...
tinyagi provider anthropic --api-key sk-ant-...
tinyagi provider openai --api-key sk-...
```

Anthropic supports both `oauth_token` (exported as `CLAUDE_CODE_OAUTH_TOKEN`) and `api_key` (exported as `ANTHROPIC_API_KEY`). OAuth takes priority if both are set. OpenAI keys are saved as `models.openai.api_key` and exported as `OPENAI_API_KEY`. If nothing is configured, the process inherits environment variables directly.

**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](docs/AGENTS.md#custom-providers) 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) | `tinyagi pairing pending` |
| `pairing approved` | Show approved senders | `tinyagi pairing approved` |
| `pairing list` | Show both pending and approved senders | `tinyagi pairing list` |
| `pairing approve ` | Move a sender from pending to approved by code | `tinyagi pairing approve ABCD1234` |
| `pairing unpair ` | Remove an approved sender from the allowlist | `tinyagi pairing unpair telegram 1234567` |

Messaging & in-chat commands

| Command | Description | Example |
| ---------------- | --------------------------- | -------------------------------- |
| `send ` | Send message to AI manually | `tinyagi send "Hello!"` |
| `send ` | Route to specific agent | `tinyagi 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 TinyAGI 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 TinyAGI to latest version | `tinyagi update` |

> **Note:** If you are on v0.0.1 or v0.0.2, the update script was broken. Please re-install instead:
>
> ```bash
> curl -fsSL https://raw.githubusercontent.com/TinyAGI/tinyagi/main/scripts/install.sh | bash
> ```
>
> Your settings and user data will be preserved.

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

**Disable update checks:**

```bash
export TINYAGI_SKIP_UPDATE_CHECK=1
```

Configuration commands

| Command | Description | Example |
| ------------------------ | ---------------------------- | -------------------------------- |
| `reset` | Reset all conversations | `tinyagi reset` |
| `channels reset ` | Reset channel authentication | `tinyagi channels reset whatsapp` |

## 🤖 Using Agents

Use `@agent_id` prefix to route messages to specific agents:

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

Agent configuration

Agents are configured in `.tinyagi/settings.json`:

```json
{
"agents": {
"coder": {
"name": "Code Assistant",
"provider": "anthropic",
"model": "sonnet",
"working_directory": "/Users/me/tinyagi-workspace/coder"
},
"writer": {
"name": "Technical Writer",
"provider": "custom:my-proxy",
"model": "gpt-5.3-codex",
"working_directory": "/Users/me/tinyagi-workspace/writer"
}
}
}
```

Each agent operates in isolation:

- **Separate workspace directory** - `~/tinyagi-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](docs/AGENTS.md) for full details on architecture, use cases, and advanced features.

## 📐 Architecture

Message flow diagram

```text
┌─────────────────────────────────────────────────────────────┐
│ Message Channels │
│ (Discord, Telegram, WhatsApp, Web, API) │
└────────────────────┬────────────────────────────────────────┘
│ enqueueMessage()
↓
┌─────────────────────────────────────────────────────────────┐
│ ~/.tinyagi/tinyagi.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](docs/QUEUE.md) for detailed queue system documentation.

## ⚙️ Configuration

Settings file reference

Located at `.tinyagi/settings.json`:

```json
{
"channels": {
"enabled": ["discord", "telegram", "whatsapp"],
"discord": { "bot_token": "..." },
"telegram": { "bot_token": "..." },
"whatsapp": {}
},
"workspace": {
"path": "/Users/me/tinyagi-workspace",
"name": "tinyagi-workspace"
},
"agents": {
"tinyagi": {
"name": "TinyAGI Agent",
"provider": "anthropic",
"model": "opus",
"working_directory": "/Users/me/tinyagi-workspace/tinyagi"
}
},
"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-6"
}
},
"models": {
"anthropic": { "api_key": "sk-ant-...", "oauth_token": "sk-ant-oat01-..." },
"openai": { "api_key": "sk-..." }
},
"monitoring": {
"heartbeat_interval": 3600
}
}
```

Heartbeat configuration

Edit agent-specific heartbeat prompts:

```bash
nano ~/tinyagi-workspace/coder/heartbeat.md
```

Default heartbeat prompt:

```markdown
Check for:

1. Pending tasks
2. Errors
3. Unread messages

Take action if needed.
```

Directory structure

```text
tinyagi/
├── 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
│ └── visualizer/ # TUI dashboard and chatroom viewer
├── tinyoffice/ # TinyOffice web portal (Next.js)
├── .tinyagi/ # TinyAGI data (created at runtime)
│ ├── settings.json # Configuration
│ ├── tinyagi.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
├── ~/tinyagi-workspace/ # Agent workspaces
│ ├── tinyagi/ # Default agent
│ ├── coder/
│ └── writer/
└── scripts/ # Installation scripts
```

## 🎯 Use Cases

Examples

### Personal AI Assistant

```text
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

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

### Team Collaboration

```text
@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](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](docs/AGENTS.md) - Agent management, routing, and custom providers
- [TEAMS.md](docs/TEAMS.md) - Team collaboration, chain execution, chat rooms, and visualizer
- [QUEUE.md](docs/QUEUE.md) - Queue system and message flow
- [tinyoffice/README.md](tinyoffice/README.md) - TinyOffice web portal
- [PLUGINS.md](docs/PLUGINS.md) - Plugin development guide
- [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - Common issues and solutions

## 🐛 Troubleshooting

Quick fixes & common issues

```bash
# Reset everything (preserves settings)
tinyagi stop && rm -rf .tinyagi/queue/* && tinyagi start

# Reset WhatsApp
tinyagi channels reset whatsapp

# Check status
tinyagi status

# View logs
tinyagi logs all
```

**Common issues:**

- WhatsApp not connecting → Reset auth: `tinyagi channels reset whatsapp`
- Messages stuck → Clear queue: `rm -rf .tinyagi/queue/processing/*`
- Agent not found → Check: `tinyagi agent list`
- Corrupted settings.json → TinyAGI auto-repairs invalid JSON (trailing commas, comments, BOM) and creates a `.bak` backup

**Need help?** [GitHub Issues](https://github.com/TinyAGI/tinyagi/issues) · `tinyagi logs all`

## 🙏 Credits

- Inspired by [OpenClaw](https://openclaw.ai/) by Peter Steinberger
- Built on [Claude Code](https://claude.com/claude-code) and [Codex CLI](https://docs.openai.com/codex)
- Uses [discord.js](https://discord.js.org/), [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js), [node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api)

## 📄 License

MIT

---

**TinyAGI - Tiny but mighty!** 🦞✨