- 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
+ ZooBot โ Your personal AI agent team, running free in the cloud โ๏ธ
+
-
-
-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`:**
+Create `~/.zoobot/settings.json` (or set environment variables):
```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"
+ "workspace": {
+ "path": "~/zoo-bot-workspace"
+ },
+ "models": {
+ "provider": "groq",
+ "groq": {
+ "model": "llama-3.3-70b-versatile"
+ }
+ },
+ "GROQ_API_KEY": "your-groq-api-key-here",
+ "agents": {
+ "assistant": {
+ "name": "ZooBot Assistant",
+ "provider": "groq",
+ "model": "llama-3.3-70b-versatile",
+ "working_directory": "~/zoo-bot-workspace/assistant",
+ "system_prompt": "You are a helpful AI assistant."
}
}
}
```
-| 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:**
+Or use environment variables:
```bash
-tinyagi agent provider coder custom:my-proxy
-tinyagi 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:
-
-```bash
-tinyagi provider anthropic --auth-token sk-ant-...
-tinyagi provider openai --auth-token sk-...
-```
-
-Tokens are saved in `settings.json` under `models.
-
-
-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
+## ๐ Documentation
-| Command | Description | Example |
-| -------- | --------------------------------- | ----------------- |
-| `update` | Update TinyAGI to latest version | `tinyagi update` |
+- [Installation Guide](docs/INSTALL.md)
+- [Agent Configuration](docs/AGENTS.md)
+- [Team Collaboration](docs/TEAMS.md)
+- [Channel Setup (Discord, Telegram, etc.)](docs/PLUGINS.md)
+- [Message Patterns](docs/MESSAGE-PATTERNS.md)
+- [Queue System](docs/QUEUE.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
-> **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).
+## ๐ ๏ธ Usage
-**Disable update checks:**
+### Single Agent Mode
```bash
-export TINYAGI_SKIP_UPDATE_CHECK=1
-```
-
-
-
-
-## ๐ค Using Agents
+# Start interactive chat with your agent
+npm run chat
-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)
+# Run a single command
+npm run agent -- "Hello, help me write a Python script"
```
-Configuration commands
-
-| Command | Description | Example |
-| ------------------------ | ---------------------------- | -------------------------------- |
-| `reset` | Reset all conversations | `tinyagi reset` |
-| `channels reset
-
-
-## ๐ Architecture
-
-Agent configuration
-
-Agents are configured in `.tinyagi/settings.json`:
+### Team Mode
-```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"
- }
- }
-}
-```
+```bash
+# Create a team of agents
+zoobot team create dev "coder,reviewer,tester"
-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.
-
-
-
+### Channel Mode
-**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)
+# Send task to team
+zoobot team message dev "Build a REST API for task management"
```
-
-
-
-Settings file reference
-
-Located at `.tinyagi/settings.json`:
+```bash
+# Start Telegram bot
+npm run telegram
-```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": { "auth_token": "sk-ant-..." },
- "openai": { "auth_token": "sk-..." }
- },
- "monitoring": {
- "heartbeat_interval": 3600
- }
-}
+# Start Discord bot
+npm run discord
```
-
-
-
-Heartbeat configuration
-
-Edit agent-specific heartbeat prompts:
+### Web Dashboard (TinyOffice)
```bash
-nano ~/tinyagi-workspace/coder/heartbeat.md
+# Start TinyOffice web interface
+npm run visualizer
```
-Default heartbeat prompt:
-
-```markdown
-Check for:
+---
-1. Pending tasks
-2. Errors
-3. Unread messages
+## ๐งฉ Skills
-Take action if needed.
-```
-
-
-
+| Skill | Description |
+|-------|-------------|
+| `agent-browser` | Automate web browsers |
+| `imagegen` | Generate images via AI |
+| `memory` | Persistent memory management |
+| `schedule` | Schedule tasks with cron |
+| `tasks` | Task management |
+| `skill-creator` | Create new skills |
-## ๐ฏ 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 (tinyagi.sh helpers)
-โ โโโ 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/
-โโโ lib/ # Runtime scripts
-โโโ scripts/ # Installation scripts
-โโโ tinyagi.sh # Main script
-```
+ZooBot comes with built-in skills:
-
-
-
-## ๐ 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
+## ๐ง API Reference
-### Personal AI Assistant
+### Environment Variables
-```text
-You: "Remind me to call mom"
-Claude: "I'll remind you!"
-[1 hour later via heartbeat]
-Claude: "Don't forget to call mom!"
-```
+| Variable | Description |
+|----------|-------------|
+| `GROQ_API_KEY` | Your Groq API key |
+| `OPENAI_API_KEY` | Your OpenAI API key |
+| `ANTHROPIC_AUTH_TOKEN` | Your Anthropic auth token |
+| `ZOOBOT_HOME` | Config directory (default: `~/.zoobot`) |
+| `ZOOBOT_WORKSPACE` | Workspace directory |
-### Multi-Agent Workflow
+### Programmatic Usage
-```text
-@coder Review and fix bugs in auth.ts
-@writer Document the changes
-@reviewer Check the documentation quality
-```
+```typescript
+import { ZooBot } from '@zoobot/core';
-### Team Collaboration
+const bot = new ZooBot({
+ provider: 'groq',
+ model: 'llama-3.3-70b-versatile',
+ apiKey: process.env.GROQ_API_KEY
+});
-```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
+const response = await bot.invoke({
+ agentId: 'assistant',
+ message: 'Hello!'
+});
```
-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`
+## ๐ License
-## ๐ Credits
+MIT License - see [LICENSE](LICENSE) for details.
-- 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
+## ๐ Acknowledgments
-MIT
+ZooBot is based on [TinyAGI](https://github.com/TinyAGI/TinyAGI) by TinyAGI contributors. We've extended it with direct API support for free LLM providers and additional features.
---
-**TinyAGI - Tiny but mighty!** ๐ฆโจ
-
-[](https://www.star-history.com/?repos=TinyAGI%2Ftinyagi&type=date&legend=top-left)
\ No newline at end of file
+Quick fixes & common issues
+---
-```bash
-# Reset everything (preserves settings)
-tinyagi stop && rm -rf .tinyagi/queue/* && tinyagi start
+## ๐จ Brand Assets
-# Reset WhatsApp
-tinyagi channels reset whatsapp
+
-# Check status
-tinyagi status
+Logo and brand assets are available in [`docs/assets/`](docs/assets/).
-# View logs
-tinyagi logs all
-```
+---
-**Common issues:**
+## ๐ค Contributing
-- 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
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
- 
- 
- 
-