git clone https://github.com/TinyAGI/tinyagi.git
cd tinyagi && npm install && npm run build
npx tinyagi start
npx tinyagi agent list

From Source:

git clone https://github.com/TinyAGI/tinyagi.git
cd tinyagi && npm install && ./scripts/install.sh

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.

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

• 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

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"
    }
  }
}

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.

Use sender pairing to control who can message your agents.

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.

These commands work in Discord, Telegram, and WhatsApp:

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.

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

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.

┌─────────────────────────────────────────────────────────────┐
│                     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)

Located at .tinyagi/settings.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
  }
}

Edit agent-specific heartbeat prompts:

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

Default heartbeat prompt:

Check for:

1. Pending tasks
2. Errors
3. Unread messages

Take action if needed.

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

Personal AI Assistant

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

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

Team Collaboration

@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 for details.

Cross-Device Access

• WhatsApp on phone, Discord on desktop, Telegram anywhere, CLI for automation
• All channels share agent conversations!

# 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