{"id":47423244,"url":"https://github.com/TinyAGI/tinyagi","last_synced_at":"2026-03-29T13:00:39.686Z","repository":{"id":337335843,"uuid":"1153146773","full_name":"TinyAGI/tinyagi","owner":"TinyAGI","description":"TinyAGI is the agent teams orchestrator for One Person Company. (fka TinyClaw)","archived":false,"fork":false,"pushed_at":"2026-03-26T17:21:01.000Z","size":19792,"stargazers_count":3389,"open_issues_count":69,"forks_count":479,"subscribers_count":20,"default_branch":"main","last_synced_at":"2026-03-26T21:56:01.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://office.tinyagicompany.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TinyAGI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T00:34:11.000Z","updated_at":"2026-03-26T20:52:39.000Z","dependencies_parsed_at":"2026-02-15T23:00:56.809Z","dependency_job_id":null,"html_url":"https://github.com/TinyAGI/tinyagi","commit_stats":null,"previous_names":["jlia0/tinyclaw","tinyagi/tinyclaw","tinyagi/tinyagi"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/TinyAGI/tinyagi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TinyAGI%2Ftinyagi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TinyAGI%2Ftinyagi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TinyAGI%2Ftinyagi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TinyAGI%2Ftinyagi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TinyAGI","download_url":"https://codeload.github.com/TinyAGI/tinyagi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TinyAGI%2Ftinyagi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31144130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-29T11:01:20.541Z","status":"ssl_error","status_checked_at":"2026-03-29T11:01:14.322Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-21T19:00:40.915Z","updated_at":"2026-03-29T13:00:39.677Z","avatar_url":"https://github.com/TinyAGI.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/tinyagi.png\" alt=\"TinyAGI\" width=\"600\" /\u003e\n  \u003ch1\u003eTinyAGI 🦞\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eMulti-agent, Multi-team, Multi-channel, 24/7 AI assistant\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003eRun multiple teams of AI agents that collaborate with each other simultaneously with isolated workspaces.\u003c/p\u003e\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/stability-experimental-orange.svg\" alt=\"Experimental\" /\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://discord.gg/jH6AcEChuD\"\u003e\n      \u003cimg src=\"https://img.shields.io/discord/1353722981163208785?logo=discord\u0026logoColor=white\u0026label=Discord\u0026color=7289DA\" alt=\"Discord\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/TinyAGI/tinyagi/releases/latest\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/release/TinyAGI/tinyagi?label=Latest\u0026color=green\" alt=\"Latest Release\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/c5ef5d3c-d9cf-4a00-b619-c31e4380df2e\" width=\"600\" controls\u003e\u003c/video\u003e\n\u003c/div\u003e\n\n## ✨ Features\n\n- ✅ **Multi-agent** - Run multiple isolated AI agents with specialized roles\n- ✅ **Multi-team collaboration** - Agents hand off work to teammates via chain execution and fan-out\n- ✅ **Multi-channel** - Discord, WhatsApp, and Telegram\n- ✅ **Web portal (TinyOffice)** - Browser-based dashboard for chat, agents, teams, tasks, logs, and settings\n- ✅ **Team chat rooms** - Persistent async chat rooms per team with real-time CLI viewer\n- ✅ **Multiple AI providers** - Anthropic Claude, OpenAI Codex, and custom providers (any OpenAI/Anthropic-compatible endpoint)\n- ✅ **Auth token management** - Store API keys per provider, no separate CLI auth needed\n- ✅ **Parallel processing** - Agents process messages concurrently\n- ✅ **Live TUI dashboard** - Real-time team visualizer and chatroom viewer\n- ✅ **Persistent sessions** - Conversation context maintained across restarts\n- ✅ **SQLite queue** - Atomic transactions, retry logic, dead-letter management\n- ✅ **Plugin system** - Extend TinyAGI with custom plugins for message hooks and event listeners\n- ✅ **24/7 operation** - Runs as a background process or Docker container\n\n## Community\n\n[Discord](https://discord.com/invite/jH6AcEChuD)\n\nWe are actively looking for contributors. Please reach out.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- macOS, Linux and Windows (WSL2)\n- Node.js v18+\n- [Claude Code CLI](https://claude.com/claude-code) (for Anthropic provider)\n- [Codex CLI](https://docs.openai.com/codex) (for OpenAI provider)\n\n### Installation \u0026 First Run\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/TinyAGI/tinyagi/main/scripts/install.sh | bash\n```\n\nThis downloads and installs the `tinyagi` command globally. Then just run:\n\n```bash\ntinyagi\n```\n\nThat's it. TinyAGI auto-creates default settings, starts the daemon, and opens TinyOffice in your browser. No wizard, no configuration needed.\n\n- **Default workspace:** `~/tinyagi-workspace`\n- **Default agent:** `tinyagi` (Anthropic/Opus)\n- **Channels:** none initially — add later with `tinyagi channel setup`\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDevelopment (run from source repo)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/TinyAGI/tinyagi.git\ncd tinyagi \u0026\u0026 npm install \u0026\u0026 npm run build\nnpx tinyagi start\nnpx tinyagi agent list\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther installation methods\u003c/b\u003e\u003c/summary\u003e\n\n**From Source:**\n\n```bash\ngit clone https://github.com/TinyAGI/tinyagi.git\ncd tinyagi \u0026\u0026 npm install \u0026\u0026 ./scripts/install.sh\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐳 Docker\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ndocker compose up -d\n```\n\nSet your API key in a `.env` file or pass it directly:\n\n```bash\nANTHROPIC_API_KEY=sk-ant-... docker compose up -d\n```\n\nThe API runs on `http://localhost:3777`. Data is persisted in a `tinyagi-data` Docker volume.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📱 Channel Setup Guides\u003c/b\u003e\u003c/summary\u003e\n\n### Discord Setup\n\n1. Go to [Discord Developer Portal](https://discord.com/developers/applications)\n2. Create application → Bot section → Create bot\n3. Copy bot token\n4. Enable \"Message Content Intent\"\n5. Invite bot using OAuth2 URL Generator\n\n### Telegram Setup\n\n1. Open Telegram → Search `@BotFather`\n2. Send `/newbot` → Follow prompts\n3. Copy bot token\n4. Start chat with your bot\n\n### WhatsApp Setup\n\nAfter starting TinyAGI, scan the QR code:\n\n```text\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n     WhatsApp QR Code\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n[QR CODE HERE]\n\n📱 Settings → Linked Devices → Link a Device\n```\n\n\u003c/details\u003e\n\n---\n\n## 🌐 TinyOffice Web Portal\n\nTinyAGI includes a web portal for managing your agents, teams, tasks, and chat — all from the browser.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/tinyoffice.png\" alt=\"TinyOffice Office View\" width=\"700\" /\u003e\n\u003c/div\u003e\n\nOnce you start running TinyAGI locally, you can control it by visiting **[office.tinyagicompany.com](https://office.tinyagicompany.com/)**. It connects to your local TinyAGI API at `localhost:3777` — no account or sign-up needed.\n\nAlternatively, you can run TinyOffice locally:\n\n```bash\ntinyagi office  # Builds and starts on http://localhost:3000\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTinyOffice Features \u0026 Setup\u003c/b\u003e\u003c/summary\u003e\n\n- **Dashboard** - Real-time queue/system overview and live event feed\n- **Chat Console** - Send messages to default agent, `@agent`, or `@team`\n- **Agents \u0026 Teams** - Create, edit, and remove agents/teams\n- **Tasks (Kanban)** - Create tasks, drag across stages, assign to agent/team\n- **Logs \u0026 Events** - Inspect queue logs and streaming events\n- **Settings** - Edit TinyAGI configuration (`settings.json`) via UI\n- **Office View** - Visual simulation of agent interactions\n- **Org Chart** - Hierarchical visualization of teams and agents\n- **Chat Rooms** - Slack-style persistent chat rooms per team\n- **Projects** - Project-level task management with filtered kanban boards\n\n### Running Locally\n\nStart TinyAGI first (API default: `http://localhost:3777`), then:\n\n```bash\ntinyagi office\n```\n\nThis auto-detects when dependencies or builds are needed (e.g. after `tinyagi update`) and starts the production server on `http://localhost:3000`.\n\nFor development with hot-reload:\n\n```bash\ncd tinyoffice\nnpm install\nnpm run dev\n```\n\nIf TinyAGI API is on a different host/port, set:\n\n```bash\ncd tinyoffice\necho 'NEXT_PUBLIC_API_URL=http://localhost:3777' \u003e .env.local\n```\n\n\u003c/details\u003e\n\n## 📋 Commands\n\nCommands work with the `tinyagi` CLI.\n\n### Core Commands\n\n| Command       | Description                                               | Example               |\n| ------------- | --------------------------------------------------------- | --------------------- |\n| *(no command)* | Install, configure defaults, start, and open TinyOffice  | `tinyagi`            |\n| `start`       | Start TinyAGI daemon                                     | `tinyagi start`      |\n| `stop`        | Stop all processes                                        | `tinyagi stop`       |\n| `restart`     | Restart TinyAGI                                          | `tinyagi restart`    |\n| `status`      | Show current status and activity                          | `tinyagi status`     |\n| `channel setup` | Configure channels interactively                        | `tinyagi channel setup` |\n| `logs [type]` | View logs (discord/telegram/whatsapp/queue/heartbeat/all) | `tinyagi logs queue` |\n\n### Agent Commands\n\n| Command                               | Description                     | Example                                                      |\n| ------------------------------------- | ------------------------------- | ------------------------------------------------------------ |\n| `agent list`                          | List all configured agents      | `tinyagi agent list`                                        |\n| `agent add`                           | Add new agent (interactive)     | `tinyagi agent add`                                         |\n| `agent show \u003cid\u003e`                     | Show agent configuration        | `tinyagi agent show coder`                                  |\n| `agent remove \u003cid\u003e`                   | Remove an agent                 | `tinyagi agent remove coder`                                |\n| `agent reset \u003cid\u003e`                    | Reset agent conversation        | `tinyagi agent reset coder`                                 |\n| `agent provider \u003cid\u003e [provider]`      | Show or set agent's AI provider | `tinyagi agent provider coder anthropic`                    |\n| `agent provider \u003cid\u003e \u003cp\u003e --model \u003cm\u003e` | Set agent's provider and model  | `tinyagi agent provider coder openai --model gpt-5.3-codex` |\n\n### Team Commands\n\n| Command                     | Description                        | Example                                   |\n| --------------------------- | ---------------------------------- | ----------------------------------------- |\n| `team list`                 | List all configured teams          | `tinyagi team list`                      |\n| `team add`                  | Add new team (interactive)         | `tinyagi team add`                       |\n| `team show \u003cid\u003e`            | Show team configuration            | `tinyagi team show dev`                  |\n| `team remove \u003cid\u003e`          | Remove a team                      | `tinyagi team remove dev`                |\n| `team add-agent \u003ct\u003e \u003ca\u003e`    | Add an existing agent to a team    | `tinyagi team add-agent dev reviewer`    |\n| `team remove-agent \u003ct\u003e \u003ca\u003e` | Remove an agent from a team        | `tinyagi team remove-agent dev reviewer` |\n| `team visualize [id]`       | Live TUI dashboard for team chains | `tinyagi team visualize dev`             |\n\n### Chatroom Commands\n\n| Command             | Description                                   | Example                    |\n| ------------------- | --------------------------------------------- | -------------------------- |\n| `chatroom \u003cteam\u003e`   | Real-time TUI viewer with type-to-send        | `tinyagi chatroom dev`    |\n| `office`            | Start TinyOffice web portal on port 3000      | `tinyagi office`          |\n\nEvery 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.\n\n**API endpoints:**\n\n```\nGET  /api/chatroom/:teamId          # Get messages (?limit=100\u0026since=0)\nPOST /api/chatroom/:teamId          # Post a message (body: { \"message\": \"...\" })\n```\n\n### Provider \u0026 Custom Provider Commands\n\n| Command                                       | Description                                              | Example                                          |\n| --------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------ |\n| `provider [name]`                             | Show or switch global AI provider                        | `tinyagi provider anthropic`                    |\n| `provider \u003cname\u003e --model \u003cmodel\u003e`             | Switch provider and model; propagates to matching agents | `tinyagi provider openai --model gpt-5.3-codex` |\n| `provider \u003cname\u003e --oauth-token \u003ctoken\u003e`        | Store OAuth token for a built-in provider                | `tinyagi provider anthropic --oauth-token sk-ant-oat01-...` |\n| `provider list`                               | List all custom providers                                | `tinyagi provider list`                         |\n| `provider add`                                | Add a new custom provider (interactive)                  | `tinyagi provider add`                          |\n| `provider remove \u003cid\u003e`                        | Remove a custom provider                                 | `tinyagi provider remove proxy`                 |\n| `model [name]`                                | Show or switch AI model                                  | `tinyagi model opus`                            |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCustom provider details\u003c/b\u003e\u003c/summary\u003e\n\nCustom providers let you use any OpenAI or Anthropic-compatible API endpoint (e.g., OpenRouter, proxy servers, self-hosted models).\n\n**Define a custom provider in `settings.json`:**\n\n```json\n{\n  \"custom_providers\": {\n    \"my-proxy\": {\n      \"name\": \"My Proxy\",\n      \"harness\": \"claude\",\n      \"base_url\": \"https://proxy.example.com/v1\",\n      \"api_key\": \"sk-...\",\n      \"model\": \"claude-sonnet-4-6\"\n    }\n  }\n}\n```\n\n| Field      | Required | Description                          |\n| ---------- | -------- | ------------------------------------ |\n| `name`     | Yes      | Human-readable display name          |\n| `harness`  | Yes      | CLI to use: `claude` or `codex`      |\n| `base_url` | Yes      | API endpoint URL                     |\n| `api_key`  | Yes      | API key for authentication           |\n| `model`    | No       | Default model name for CLI           |\n\n**Assign a custom provider to an agent:**\n\n```bash\ntinyagi agent provider coder custom:my-proxy\ntinyagi agent provider coder custom:my-proxy --model gpt-4o\n```\n\n**Auth token storage** — store credentials for built-in providers so you don't need separate CLI auth:\n\n```bash\ntinyagi provider anthropic --oauth-token sk-ant-oat01-...\ntinyagi provider anthropic --api-key sk-ant-...\ntinyagi provider openai --api-key sk-...\n```\n\nAnthropic 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.\n\n**API endpoints:**\n\n```\nGET    /api/custom-providers              # List custom providers\nPUT    /api/custom-providers/:id          # Create or update\nDELETE /api/custom-providers/:id          # Delete\n```\n\nSee [docs/AGENTS.md](docs/AGENTS.md#custom-providers) for more details.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePairing commands\u003c/b\u003e\u003c/summary\u003e\n\nUse sender pairing to control who can message your agents.\n\n| Command                                | Description                                        | Example                                    |\n| -------------------------------------- | -------------------------------------------------- | ------------------------------------------ |\n| `pairing pending`                      | Show pending sender approvals (with pairing codes) | `tinyagi pairing pending`                 |\n| `pairing approved`                     | Show approved senders                              | `tinyagi pairing approved`                |\n| `pairing list`                         | Show both pending and approved senders             | `tinyagi pairing list`                    |\n| `pairing approve \u003ccode\u003e`               | Move a sender from pending to approved by code     | `tinyagi pairing approve ABCD1234`        |\n| `pairing unpair \u003cchannel\u003e \u003csender_id\u003e` | Remove an approved sender from the allowlist       | `tinyagi pairing unpair telegram 1234567` |\n\nPairing behavior:\n\n- First message from unknown sender: TinyAGI generates a code and sends approval instructions.\n- Additional messages while still pending: TinyAGI blocks silently (no repeated pairing message).\n- After approval: messages from that sender are processed normally.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMessaging \u0026 in-chat commands\u003c/b\u003e\u003c/summary\u003e\n\n| Command          | Description                 | Example                          |\n| ---------------- | --------------------------- | -------------------------------- |\n| `send \u003cmessage\u003e` | Send message to AI manually | `tinyagi send \"Hello!\"`         |\n| `send \u003cmessage\u003e` | Route to specific agent     | `tinyagi send \"@coder fix bug\"` |\n\nThese commands work in Discord, Telegram, and WhatsApp:\n\n| Command             | Description                          | Example                 |\n| ------------------- | ------------------------------------ | ----------------------- |\n| `@agent_id message` | Route message to specific agent      | `@coder fix the bug`    |\n| `@team_id message`  | Route message to team leader         | `@dev fix the auth bug` |\n| `/agent`            | List all available agents            | `/agent`                |\n| `/team`             | List all available teams             | `/team`                 |\n| `@agent_id /reset`  | Reset specific agent conversation    | `@coder /reset`         |\n| `/reset`            | Reset conversation (WhatsApp/global) | `/reset` or `!reset`    |\n| `/restart`          | Restart TinyAGI process             | `/restart`              |\n| `message`           | Send to default agent (no prefix)    | `help me with this`     |\n\n**Note:** The `@agent_id` routing prefix requires a space after it (e.g., `@coder fix` not `@coderfix`).\n\n**Access control note:** before routing, channel clients apply sender pairing allowlist checks.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUpdate commands\u003c/b\u003e\u003c/summary\u003e\n\n| Command  | Description                       | Example           |\n| -------- | --------------------------------- | ----------------- |\n| `update` | Update TinyAGI to latest version | `tinyagi update` |\n\n\u003e **Note:** If you are on v0.0.1 or v0.0.2, the update script was broken. Please re-install instead:\n\u003e\n\u003e ```bash\n\u003e curl -fsSL https://raw.githubusercontent.com/TinyAGI/tinyagi/main/scripts/install.sh | bash\n\u003e ```\n\u003e\n\u003e Your settings and user data will be preserved.\n\n**Auto-detection:** TinyAGI checks for updates on startup (once per hour).\n\n**Disable update checks:**\n\n```bash\nexport TINYAGI_SKIP_UPDATE_CHECK=1\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConfiguration commands\u003c/b\u003e\u003c/summary\u003e\n\n| Command                  | Description                  | Example                          |\n| ------------------------ | ---------------------------- | -------------------------------- |\n| `reset`                  | Reset all conversations      | `tinyagi reset`                 |\n| `channels reset \u003cchan\u003e`  | Reset channel authentication | `tinyagi channels reset whatsapp` |\n\n\u003c/details\u003e\n\n## 🤖 Using Agents\n\nUse `@agent_id` prefix to route messages to specific agents:\n\n```text\n@coder fix the authentication bug\n@writer document the API endpoints\nhelp me with this  ← goes to tinyagi agent (no prefix needed)\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAgent configuration\u003c/b\u003e\u003c/summary\u003e\n\nAgents are configured in `.tinyagi/settings.json`:\n\n```json\n{\n  \"agents\": {\n    \"coder\": {\n      \"name\": \"Code Assistant\",\n      \"provider\": \"anthropic\",\n      \"model\": \"sonnet\",\n      \"working_directory\": \"/Users/me/tinyagi-workspace/coder\"\n    },\n    \"writer\": {\n      \"name\": \"Technical Writer\",\n      \"provider\": \"custom:my-proxy\",\n      \"model\": \"gpt-5.3-codex\",\n      \"working_directory\": \"/Users/me/tinyagi-workspace/writer\"\n    }\n  }\n}\n```\n\nEach agent operates in isolation:\n\n- **Separate workspace directory** - `~/tinyagi-workspace/{agent_id}/`\n- **Own conversation history** - Maintained by CLI\n- **Custom configuration** - `.claude/`, `heartbeat.md` (root), `AGENTS.md`\n- **Independent resets** - Reset individual agent conversations\n\nSee [docs/AGENTS.md](docs/AGENTS.md) for full details on architecture, use cases, and advanced features.\n\n\u003c/details\u003e\n\n## 📐 Architecture\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMessage flow diagram\u003c/b\u003e\u003c/summary\u003e\n\n```text\n┌─────────────────────────────────────────────────────────────┐\n│                     Message Channels                         │\n│         (Discord, Telegram, WhatsApp, Web, API)             │\n└────────────────────┬────────────────────────────────────────┘\n                     │ enqueueMessage()\n                     ↓\n┌─────────────────────────────────────────────────────────────┐\n│               ~/.tinyagi/tinyagi.db (SQLite)               │\n│                                                              │\n│  messages: pending → processing → completed / dead          │\n│  responses: pending → acked                                  │\n│                                                              │\n└────────────────────┬────────────────────────────────────────┘\n                     │ Queue Processor\n                     ↓\n┌─────────────────────────────────────────────────────────────┐\n│              Parallel Processing by Agent                    │\n│                                                              │\n│  Agent: coder        Agent: writer       Agent: assistant   │\n│  ┌──────────┐       ┌──────────┐        ┌──────────┐       │\n│  │ Message 1│       │ Message 1│        │ Message 1│       │\n│  │ Message 2│ ...   │ Message 2│  ...   │ Message 2│ ...   │\n│  │ Message 3│       │          │        │          │       │\n│  └────┬─────┘       └────┬─────┘        └────┬─────┘       │\n│       │                  │                     │            │\n└───────┼──────────────────┼─────────────────────┼────────────┘\n        ↓                  ↓                     ↓\n   claude CLI         claude CLI             claude CLI\n  (workspace/coder)  (workspace/writer)  (workspace/assistant)\n```\n\n\u003c/details\u003e\n\n**Key features:**\n\n- **SQLite queue** - Atomic transactions via WAL mode, no race conditions\n- **Parallel agents** - Different agents process messages concurrently\n- **Sequential per agent** - Preserves conversation order within each agent\n- **Retry \u0026 dead-letter** - Failed messages retry up to 5 times, then enter dead-letter queue\n- **Isolated workspaces** - Each agent has its own directory and context\n\nSee [docs/QUEUE.md](docs/QUEUE.md) for detailed queue system documentation.\n\n## ⚙️ Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSettings file reference\u003c/b\u003e\u003c/summary\u003e\n\nLocated at `.tinyagi/settings.json`:\n\n```json\n{\n  \"channels\": {\n    \"enabled\": [\"discord\", \"telegram\", \"whatsapp\"],\n    \"discord\": { \"bot_token\": \"...\" },\n    \"telegram\": { \"bot_token\": \"...\" },\n    \"whatsapp\": {}\n  },\n  \"workspace\": {\n    \"path\": \"/Users/me/tinyagi-workspace\",\n    \"name\": \"tinyagi-workspace\"\n  },\n  \"agents\": {\n    \"tinyagi\": {\n      \"name\": \"TinyAGI Agent\",\n      \"provider\": \"anthropic\",\n      \"model\": \"opus\",\n      \"working_directory\": \"/Users/me/tinyagi-workspace/tinyagi\"\n    }\n  },\n  \"teams\": {\n    \"dev\": {\n      \"name\": \"Development Team\",\n      \"agents\": [\"coder\", \"reviewer\"],\n      \"leader_agent\": \"coder\"\n    }\n  },\n  \"custom_providers\": {\n    \"my-proxy\": {\n      \"name\": \"My Proxy\",\n      \"harness\": \"claude\",\n      \"base_url\": \"https://proxy.example.com/v1\",\n      \"api_key\": \"sk-...\",\n      \"model\": \"claude-sonnet-4-6\"\n    }\n  },\n  \"models\": {\n    \"anthropic\": { \"api_key\": \"sk-ant-...\", \"oauth_token\": \"sk-ant-oat01-...\" },\n    \"openai\": { \"api_key\": \"sk-...\" }\n  },\n  \"monitoring\": {\n    \"heartbeat_interval\": 3600\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHeartbeat configuration\u003c/b\u003e\u003c/summary\u003e\n\nEdit agent-specific heartbeat prompts:\n\n```bash\nnano ~/tinyagi-workspace/coder/heartbeat.md\n```\n\nDefault heartbeat prompt:\n\n```markdown\nCheck for:\n\n1. Pending tasks\n2. Errors\n3. Unread messages\n\nTake action if needed.\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDirectory structure\u003c/b\u003e\u003c/summary\u003e\n\n```text\ntinyagi/\n├── packages/                # Monorepo packages\n│   ├── core/                #   Shared types, config, queue, agent invocation\n│   ├── main/                #   Queue processor entry point\n│   ├── teams/               #   Team conversation orchestration\n│   ├── server/              #   API server (REST + SSE)\n│   ├── channels/            #   Channel clients (Discord, Telegram, WhatsApp)\n│   ├── cli/                 #   CLI commands\n│   └── visualizer/          #   TUI dashboard and chatroom viewer\n├── tinyoffice/              # TinyOffice web portal (Next.js)\n├── .tinyagi/               # TinyAGI data (created at runtime)\n│   ├── settings.json        #   Configuration\n│   ├── tinyagi.db          #   SQLite queue database\n│   ├── logs/                #   All logs\n│   ├── channels/            #   Channel state\n│   ├── files/               #   Uploaded files\n│   ├── pairing.json         #   Sender allowlist state\n│   ├── chats/               #   Team conversation history\n│   │   └── {team_id}/       #     Per-team chat logs\n│   ├── .claude/             #   Template for agents\n│   ├── heartbeat.md         #   Template for agents\n│   └── AGENTS.md            #   Template for agents\n├── ~/tinyagi-workspace/    # Agent workspaces\n│   ├── tinyagi/            #   Default agent\n│   ├── coder/\n│   └── writer/\n└── scripts/                 # Installation scripts\n```\n\n\u003c/details\u003e\n\n## 🎯 Use Cases\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n### Personal AI Assistant\n\n```text\nYou: \"Remind me to call mom\"\nClaude: \"I'll remind you!\"\n[1 hour later via heartbeat]\nClaude: \"Don't forget to call mom!\"\n```\n\n### Multi-Agent Workflow\n\n```text\n@coder Review and fix bugs in auth.ts\n@writer Document the changes\n@reviewer Check the documentation quality\n```\n\n### Team Collaboration\n\n```text\n@dev fix the auth bug\n# → Routes to team leader (@coder)\n# → Coder fixes bug, mentions @reviewer in response\n# → Reviewer automatically invoked, reviews changes\n# → Combined response sent back to user\n```\n\nTeams support sequential chains (single handoff) and parallel fan-out (multiple teammate mentions). See [docs/TEAMS.md](docs/TEAMS.md) for details.\n\n### Cross-Device Access\n\n- WhatsApp on phone, Discord on desktop, Telegram anywhere, CLI for automation\n- All channels share agent conversations!\n\n\u003c/details\u003e\n\n## 📚 Documentation\n\n- [AGENTS.md](docs/AGENTS.md) - Agent management, routing, and custom providers\n- [TEAMS.md](docs/TEAMS.md) - Team collaboration, chain execution, chat rooms, and visualizer\n- [QUEUE.md](docs/QUEUE.md) - Queue system and message flow\n- [tinyoffice/README.md](tinyoffice/README.md) - TinyOffice web portal\n- [PLUGINS.md](docs/PLUGINS.md) - Plugin development guide\n- [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - Common issues and solutions\n\n## 🐛 Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQuick fixes \u0026 common issues\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Reset everything (preserves settings)\ntinyagi stop \u0026\u0026 rm -rf .tinyagi/queue/* \u0026\u0026 tinyagi start\n\n# Reset WhatsApp\ntinyagi channels reset whatsapp\n\n# Check status\ntinyagi status\n\n# View logs\ntinyagi logs all\n```\n\n**Common issues:**\n\n- WhatsApp not connecting → Reset auth: `tinyagi channels reset whatsapp`\n- Messages stuck → Clear queue: `rm -rf .tinyagi/queue/processing/*`\n- Agent not found → Check: `tinyagi agent list`\n- Corrupted settings.json → TinyAGI auto-repairs invalid JSON (trailing commas, comments, BOM) and creates a `.bak` backup\n\n\u003c/details\u003e\n\n**Need help?** [GitHub Issues](https://github.com/TinyAGI/tinyagi/issues) · `tinyagi logs all`\n\n## 🙏 Credits\n\n- Inspired by [OpenClaw](https://openclaw.ai/) by Peter Steinberger\n- Built on [Claude Code](https://claude.com/claude-code) and [Codex CLI](https://docs.openai.com/codex)\n- 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)\n\n## 📄 License\n\nMIT\n\n---\n\n**TinyAGI - Tiny but mighty!** 🦞✨\n\n[![Star History Chart](https://api.star-history.com/image?repos=TinyAGI/tinyagi\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=TinyAGI%2Ftinyagi\u0026type=date\u0026legend=top-left)","funding_links":[],"categories":["\u003ca name=\"TypeScript\"\u003e\u003c/a\u003eTypeScript","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTinyAGI%2Ftinyagi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTinyAGI%2Ftinyagi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTinyAGI%2Ftinyagi/lists"}