tinyagi README

The project's README from github.com/TinyAGI/tinyagi. As one markdown file: README.md.

TinyAGI

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.

Experimental MIT License Discord Latest Release

✨ Features

Community

Discord

We are actively looking for contributors. Please reach out.

🚀 Quick Start

Prerequisites

Installation & First Run

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

This downloads and installs the tinyagi command globally. Then just run:

tinyagi

That's it. TinyAGI auto-creates default settings, starts the daemon, and opens TinyOffice in your browser. No wizard, no configuration needed.

Development (run from source repo) 
git clone https://github.com/TinyAGI/tinyagi.git
cd tinyagi && npm install && npm run build
npx tinyagi start
npx tinyagi agent list
Other installation methods

From Source:

git clone https://github.com/TinyAGI/tinyagi.git
cd tinyagi && npm install && ./scripts/install.sh
🐳 Docker 
docker compose up -d

Set your API key in a .env file or pass it directly:

ANTHROPIC_API_KEY=sk-ant-... docker compose up -d

The API runs on http://localhost:3777. Data is persisted in a tinyagi-data Docker volume.

📱 Channel Setup Guides

Discord Setup

  1. Go to Discord Developer Portal
  2. Create application → Bot section → Create bot
  3. Copy bot token
  4. Enable "Message Content Intent"
  5. Invite bot using OAuth2 URL Generator

Telegram Setup

  1. Open Telegram → Search @BotFather
  2. Send /newbot → Follow prompts
  3. Copy bot token
  4. Start chat with your bot

WhatsApp Setup

After starting TinyAGI, scan the QR code:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     WhatsApp QR Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[QR CODE HERE]

📱 Settings → Linked Devices → Link a Device

🌐 TinyOffice Web Portal

TinyAGI includes a web portal for managing your agents, teams, tasks, and chat — all from the browser.

TinyOffice Office View

Once you start running TinyAGI locally, you can control it by visiting office.tinyagicompany.com. It connects to your local TinyAGI API at localhost:3777 — no account or sign-up needed.

Alternatively, you can run TinyOffice locally:

tinyagi office  # Builds and starts on http://localhost:3000
TinyOffice Features & Setup
  • Dashboard - Real-time queue/system overview and live event feed
  • Chat Console - Send messages to default agent, @agent, or @team
  • Agents & Teams - Create, edit, and remove agents/teams
  • Tasks (Kanban) - Create tasks, drag across stages, assign to agent/team
  • Logs & Events - Inspect queue logs and streaming events
  • Settings - Edit TinyAGI configuration (settings.json) via UI
  • Office View - Visual simulation of agent interactions
  • Org Chart - Hierarchical visualization of teams and agents
  • Chat Rooms - Slack-style persistent chat rooms per team
  • Projects - Project-level task management with filtered kanban boards

Running Locally

Start TinyAGI first (API default: http://localhost:3777), then:

tinyagi office

This auto-detects when dependencies or builds are needed (e.g. after tinyagi update) and starts the production server on http://localhost:3000.

For development with hot-reload:

cd tinyoffice
npm install
npm run dev

If TinyAGI API is on a different host/port, set:

cd tinyoffice
echo 'NEXT_PUBLIC_API_URL=http://localhost:3777' > .env.local

📋 Commands

Commands work with the tinyagi CLI.

Core Commands

Command Description Example
(no command) Install, configure defaults, start, and open TinyOffice tinyagi
start Start TinyAGI daemon tinyagi start
stop Stop all processes tinyagi stop
restart Restart TinyAGI tinyagi restart
status Show current status and activity tinyagi status
channel setup Configure channels interactively tinyagi channel setup
logs [type] View logs (discord/telegram/whatsapp/queue/heartbeat/all) tinyagi logs queue

Agent Commands

Command Description Example
agent list List all configured agents tinyagi agent list
agent add Add new agent (interactive) tinyagi agent add
agent show <id> Show agent configuration tinyagi agent show coder
agent remove <id> Remove an agent tinyagi agent remove coder
agent reset <id> Reset agent conversation tinyagi agent reset coder
agent provider <id> [provider] Show or set agent's AI provider tinyagi agent provider coder anthropic
agent provider <id> <p> --model <m> Set agent's provider and model tinyagi agent provider coder openai --model gpt-5.3-codex

Team Commands

Command Description Example
team list List all configured teams tinyagi team list
team add Add new team (interactive) tinyagi team add
team show <id> Show team configuration tinyagi team show dev
team remove <id> Remove a team tinyagi team remove dev
team add-agent <t> <a> Add an existing agent to a team tinyagi team add-agent dev reviewer
team remove-agent <t> <a> Remove an agent from a team tinyagi team remove-agent dev reviewer
team visualize [id] Live TUI dashboard for team chains tinyagi team visualize dev

Chatroom Commands

Command Description Example
chatroom <team> 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 <name> --model <model> Switch provider and model; propagates to matching agents tinyagi provider openai --model gpt-5.3-codex
provider <name> --oauth-token <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 <id> 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:

{
  "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:

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:

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 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 <code> Move a sender from pending to approved by code tinyagi pairing approve ABCD1234
pairing unpair <channel> <sender_id> Remove an approved sender from the allowlist tinyagi pairing unpair telegram 1234567

Pairing behavior:

  • First message from unknown sender: TinyAGI generates a code and sends approval instructions.
  • Additional messages while still pending: TinyAGI blocks silently (no repeated pairing message).
  • After approval: messages from that sender are processed normally.
Messaging & in-chat commands
Command Description Example
send <message> Send message to AI manually tinyagi send "Hello!"
send <message> 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:

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:

export TINYAGI_SKIP_UPDATE_CHECK=1
Configuration commands
Command Description Example
reset Reset all conversations tinyagi reset
channels reset <chan> Reset channel authentication tinyagi channels reset whatsapp

🤖 Using Agents

Use @agent_id prefix to route messages to specific agents:

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

{
  "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 for full details on architecture, use cases, and advanced features.

📐 Architecture

Message flow diagram 
┌─────────────────────────────────────────────────────────────┐
│                     Message Channels                         │
│         (Discord, Telegram, WhatsApp, Web, API)             │
└────────────────────┬

tinyagi (TinyAGI/tinyagi)

Searching Database…

3.6K ·GitHub
Tinyagi
这是什么？TinyAGI 是一个开源的编排器（orchestrator），可以把多支 AI 智能体团队当作 24 小时全天候助手来运行，面向一人公司。各个智能体在相互隔离的工作区里工作，并把任务互相交接，你可以通过 Discord、WhatsApp、Telegram 或网页门户联系它们。
是我自己装在自己的电脑上，还是一个托管服务？它运行在你自己的电脑上：安装一个 CLI，它以后台守护进程或 Docker 容器的形式运行，在 localhost:3777 提供本地 API，TinyOffice 网页门户就连接到这个 API。
我该怎么把它跑起来？用 npm 全局安装 tinyagi 命令，然后直接运行 'tinyagi'——它会自动创建默认配置、启动守护进程，并在浏览器中打开 TinyOffice。不需要向导，也不用手动配置。
我需要提前装好哪些东西？在 macOS、Linux 或通过 WSL2 的 Windows 上需要 Node.js v18+。Anthropic 提供方还需要额外安装 Claude Code CLI，OpenAI 提供方则需要 Codex CLI。
接入 Discord 或 Telegram 之前我要了解什么？一开始没有配置任何频道——你需要在 Discord Developer Portal 或通过 @BotFather 自己创建机器人，粘贴它们的 token，然后运行 'tinyagi channel setup'。WhatsApp 是在启动后扫描二维码来连接的。
我的数据存在哪里？存在本地：每个智能体在 ~/tinyagi-workspace 下有自己的工作区，任务队列是你电脑上的 SQLite 数据库，托管的 TinyOffice 页面只是连接到你 localhost:3777 上的本地 API——不需要注册账号。
TinyOffice 是什么？我能在里面管理哪些东西？它是内置的网页门户：包含实时仪表盘、聊天控制台、智能体和团队编辑器、看板任务板、队列日志和流式事件、设置编辑器、组织架构图，以及每个团队类似 Slack 风格的聊天房间。你可以使用托管的 office.tinyagicompany.com 连接你的本地 API，也可以用 'tinyagi office' 自己运行。
我可以用 Docker 跑整套东西吗？可以——把 API key 放进 .env 文件或直接传入，数据会持久化保存在 tinyagi-data 这个 Docker 卷里，所以容器重启后数据不会丢。
直接在聊天消息里我能做什么？在 Discord、Telegram 和 WhatsApp 里，你可以用 '@agentid 消息' 或 '@teamid 消息' 来分派工作，用 /agent 和 /team 列出智能体和团队，用 /reset 重置会话，甚至可以用 /restart 远程重启 TinyAGI。
为什么它主打一人公司？想法是让独立创始人拥有一批全天候在线的 AI 员工：智能体各司其职，保持相互隔离的工作区和各自的会话历史，会把工作交接给队友，并且通过你已经在用的聊天应用 24 小时随时能找到。
What are similar projects?brigade, hermes-agent, ruflo, nanoclaw, openclaw, mission-control, evenfire, taskuary
Which topics is it in?kanban, whatsapp, task-management, ai-assistant, discord, telegram, plugin-system, tui, agent-orchestration, chatbot, sqlite, anthropic
Creator
TinyAGI
Size
19.3 MB
Stars
3.6K
Updated
CommitMar 30Releasev0.0.20Mar 26
Age
8mo
Commits · 90 Days