TinyAGI ๐ฆ
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.
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.
--model
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
Messaging & in-chat commands
| Command | Description | Example |
| ---------------- | --------------------------- | -------------------------------- |
| `send
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
```
## ๐ค 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)
```
Configuration commands
| Command | Description | Example |
| ------------------------ | ---------------------------- | -------------------------------- |
| `reset` | Reset all conversations | `tinyagi reset` |
| `channels reset
## ๐ Architecture
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.
**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
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)
```
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.
```
## ๐ฏ Use Cases
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
```
## ๐ 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
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!
**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!** ๐ฆโจ
[](https://www.star-history.com/?repos=TinyAGI%2Ftinyagi&type=date&legend=top-left)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