Skip to content
/

TinyAGI

tinyagi · TinyAGI/tinyagi · ★ 3.6k · last commit 2026-03-30

24/7 multi-agent multi-team platform with Discord/Telegram/WhatsApp channels, peer-to-peer message-passing coordination, and a Next.js web portal for one-person-company workflows.

Best whenAgents should coordinate through message-passing ([@agent: message] syntax) in their responses, not through explicit orchestrator function calls — enabling e…
Skip ifMentioning agents just to acknowledge or say thanks (triggers wasted invocation), Repeating context the recipient already has
vs seeds
claude-flowuses an M…
Primitive shape
No installable primitives
00

Summary

TinyAGI — Summary

TinyAGI is a Node.js multi-agent orchestration platform for "one-person company" workflows, featuring multi-team collaboration, multi-channel messaging (Telegram, WhatsApp, Discord), a browser-based web dashboard (TinyOffice), a live TUI dashboard, and a tinyagi CLI binary. Agents communicate via a [@agent: message] / [#team: message] syntax injected into AGENTS.md prompt files; the SQLite queue handles concurrency with atomic transactions, retry logic, and dead-letter management. TinyOffice is a Next.js web app serving as the primary management interface (dashboard, kanban, org chart, chat rooms, agent/team CRUD).

TinyAGI occupies a unique position as the only framework in this batch with built-in multi-channel messaging (Discord/Telegram/WhatsApp) as a first-class feature. Unlike Eigent (Electron) or Aperant (Electron), TinyAGI runs as a background daemon + web portal accessible from any browser. Compared to claude-flow (closest seed), TinyAGI replaces the MCP toolserver with a simpler SQLite queue + REST API, adds real messaging channels, and provides a Next.js web portal rather than a terminal TUI.

01

Overview

TinyAGI — Overview

Origin

TinyAGI was created by the TinyAGI organization. 3,568 stars, 10 contributors, MIT license. Version 0.0.20 as of 2026-05-26.

Philosophy

The README tagline: "Multi-agent, Multi-team, Multi-channel, 24/7 AI assistant."

TinyAGI is designed for the "one-person company" use case: a small team (or solo founder) who wants specialized agents collaborating asynchronously across messaging platforms, with a web dashboard providing visibility and control. The platform runs 24/7 as a background process or Docker container.

Key design principles:

  • Async team model: Agents are "teammates" who send DMs ([@agent: message]) and post to team channels ([#team: message]). Communication is message-passing, not direct function calls.
  • Multi-channel first: Discord, WhatsApp, Telegram are not afterthoughts — they are first-class input/output channels with full setup documentation.
  • Zero config default: curl | bash install + tinyagi command launches everything including a browser tab pointing to TinyOffice.

AGENTS.md as the Protocol File

TinyAGI's AGENTS.md is not a static config — it is a dynamic protocol document that agents read and write. The file documents agent IDs, system prompts, messaging syntax, and memory index. Each agent's workspace gets its own AGENTS.md written by the agent at first run.

SOUL.md

The SOUL.md file in the root defines the agent's personality and values — a top-level personality specification separate from the task-specific AGENTS.md.

02

Architecture

TinyAGI — Architecture

Distribution

  • Type: npm package (CLI binary tinyagi)
  • Install: curl -fsSL .../install.sh | bash — global tinyagi command
  • Docker: docker compose up -d

Package Structure

tinyagi/
├── packages/
│   ├── core/           # Agent loop, queue, SQLite management
│   ├── teams/          # Team collaboration logic
│   ├── channels/       # Discord, Telegram, WhatsApp adapters
│   ├── cli/            # tinyagi CLI entry point
│   ├── server/         # REST API (port 3777)
│   ├── main/           # Main orchestration entry
│   └── visualizer/     # TUI visualizer + chatroom viewer
├── tinyoffice/         # Next.js web portal
│   └── src/
├── AGENTS.md           # Global agent protocol document
├── SOUL.md             # Personality/values specification
├── heartbeat.md        # Heartbeat monitoring doc
└── docker-compose.yml

Config Files

  • settings.json — TinyAGI configuration (editable via TinyOffice UI)
  • AGENTS.md — Global + per-workspace agent protocol
  • SOUL.md — Personality specification
  • ~/tinyagi-workspace/ — Default workspace directory

Required Runtime

  • Node.js v18+
  • Claude Code CLI (for Anthropic provider) or Codex CLI (for OpenAI provider)
  • Optional: Docker (for containerized deployment)

Target AI Tools

Claude Code (Anthropic), Codex (OpenAI), or any OpenAI/Anthropic-compatible endpoint.

Tech Stack

  • Core: Node.js + TypeScript + SQLite (croner for cron)
  • Web portal: Next.js (TinyOffice, served at localhost:3000)
  • API: REST at localhost:3777
  • Channels: Discord.js, Telegram bot, WhatsApp (QR-code web session)
  • TUI: Node.js terminal visualizer (custom)
03

Components

TinyAGI — Components

CLI Binary (tinyagi)

Command Purpose
tinyagi Start daemon + open TinyOffice in browser
tinyagi agent list List configured agents
tinyagi channel setup Configure messaging channels
tinyagi office Build + start TinyOffice web portal
tinyagi update Update to latest version
tinyagi start Start daemon only

Agent Communication Protocol (in AGENTS.md)

Syntax Meaning
[@agent_id: message] Direct message to a single agent
[@agent_id1,agent_id2: message] Parallel fan-out to multiple agents (same message)
[@coder: msg1] [@reviewer: msg2] Parallel fan-out (different messages)
[#team_id: message] Broadcast to team chat room

TinyOffice Web Portal (Next.js, localhost:3000)

View Purpose
Dashboard Real-time queue/system overview + live event feed
Chat Console Send messages to default agent, @agent, or @team
Agents & Teams Create, edit, remove agents/teams
Tasks (Kanban) Create tasks, drag across stages, assign to agent/team
Logs & Events Queue logs and streaming events
Settings Edit 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

State & Memory

File Purpose
AGENTS.md (per workspace) Agent config, system prompt, messaging rules, memory index
memory/<path> Hierarchical memory files indexed in AGENTS.md
SQLite (internal) Message queue with retry/dead-letter management

Channel Adapters

  • Discord bot
  • Telegram bot
  • WhatsApp (QR-code session)
05

Prompts

TinyAGI — Prompts

TinyAGI's primary prompt file is AGENTS.md, which is both a config document and a runtime protocol specification injected into each agent session.

Verbatim excerpt 1 — AGENTS.md Direct Messages section

## Direct Messages (`[@agent: ...]`)

Use `[@agent_id: message]` to send a direct message to a teammate. Messages cannot be empty
— `[@agent_id]` alone is not allowed.

### Single teammate
- `[@coder: Can you fix the login bug?]`

### Multiple teammates (parallel fan-out)
All mentioned agents are invoked in parallel.
**Separate tags** — each gets a different message:
- `[@coder: Fix the auth bug in login.ts] [@reviewer: Review the PR for security issues]`
**Comma-separated** — all get the same message:
- `[@coder,reviewer,tester: Please share your status update.]`

Prompting technique: Protocol specification as prompt context. The AGENTS.md file teaches agents the messaging syntax by example, then the system enforces routing by parsing the [@agent: ...] tags in responses. This is a novel hybrid: the prompt IS the API contract.

Verbatim excerpt 2 — Communication Guidelines section

## Communication Guidelines

- **Keep messages short.** 2-3 sentences. Don't repeat context the recipient already has.
- **Minimize round-trips.** Ask complete questions, give complete answers.
- **Don't re-mention agents who haven't responded yet.** If you see `[N other teammate
  response(s) are still being processed...]`, wait.
- **Only mention teammates when you need something from them.** Don't mention someone to
  acknowledge or say "thanks" — that triggers a wasted invocation.
- **Respond to the user's task, not to the system.** If you have nothing new, say so in one line.

Prompting technique: Efficiency iron laws. Prevents token waste from "thanks" messages and redundant context repetition. Explicitly bans acknowledgment-only responses that would trigger wasted agent invocations.

Verbatim excerpt 3 — Memory section

## Memory

Persistent hierarchical memory. This index shows all remembered knowledge (name + summary).
To read full content, open the file at `memory/<path>`

Prompting technique: Indexed memory reference. The AGENTS.md memory section is a live index that the agent maintains. New knowledge is written to memory/<path> files and the index entry added to AGENTS.md — teaching the agent to manage its own knowledge base.

09

Uniqueness

TinyAGI — Uniqueness & Positioning

differs_from_seeds

TinyAGI is closest to claude-flow in scope (multi-agent, persistent SQLite state, 24/7 operation) but the routing mechanism is fundamentally different. Claude-flow uses an MCP toolserver where the orchestrator explicitly calls spawn_agent tools; TinyAGI uses a peer-to-peer message-passing protocol where agents embed [@agent: message] tags in their responses and the queue system parses and routes them. This is the swarm/gossip pattern, not the hierarchical queen+workers pattern. No other seed uses this approach. TinyAGI also adds multi-channel messaging (Discord/Telegram/WhatsApp) as a first-class feature absent from all 11 seeds. The dual UI surfaces (Next.js web portal + terminal TUI) are unique in the corpus; no other seed ships a full-stack web application as its management interface. The AGENTS.md as a dynamic, self-written protocol document (agents update their own AGENTS.md at first run) is a novel pattern not found in any seed.

Positioning

  • Only framework in the corpus with Discord/WhatsApp/Telegram as first-class I/O channels.
  • Only framework with a full Next.js web portal (kanban + org chart + chat rooms) as primary UI.
  • The [@agent: message] syntax creates an emergent multi-agent coordination protocol inside LLM response text — novel peer-to-peer approach.
  • "One-person company" positioning: designed for a founder with a team of AI employees, not a developer managing coding sessions.

Observable Failure Modes

  1. Message loop risk: Agent A mentions Agent B, B mentions A back → infinite loop. The communication guidelines address this ("don't re-mention agents who haven't responded yet") but enforcement is prompt-only.
  2. WhatsApp fragility: WhatsApp integration uses QR-code sessions (not official API) — fragile, may break with WhatsApp updates.
  3. Claude Code provider requirement: The "AI provider" is the Claude Code or Codex CLI — users must separately install and authenticate these tools.
  4. No TDD or code quality gates: TinyAGI is a messaging/coordination platform, not a development methodology. No test enforcement.
  5. Experimental stability label: README shows "stability-experimental" badge — not production-ready.
04

Workflow

TinyAGI — Workflow

Phase Flow

Phase Description Artifact
1. Install + Config curl-pipe install; tinyagi auto-creates settings settings.json, default agent
2. Channel Setup tinyagi channel setup configures Discord/Telegram/WhatsApp Channel adapter config
3. Agent/Team Create Via TinyOffice or CLI Agent entry in SQLite
4. Task Create Via TinyOffice kanban or channel message Task in queue
5. Message Routing [@agent: task] dispatches to specific agent; [#team: task] broadcasts Agent invocation
6. Parallel Execution Fan-out invocations processed concurrently by SQLite queue Agent responses
7. Result Routing Responses returned to requester or published to channel Message
8. Memory Update Agent updates workspace AGENTS.md memory index memory/<path> files

Approval Gates

None. TinyAGI is designed for async 24/7 operation. Human approval is informal (channel messages to the human from the agent when stuck).

Message-Passing Protocol

Unique to TinyAGI: agents communicate using [@agent: message] and [#team: message] syntax inside their response text. The queue system parses these tags and routes them as new messages to the referenced agents/teams. This enables asynchronous team collaboration without direct function calls.

24/7 Operation

Runs as background process or Docker container. Agents process messages concurrently as they arrive from channels.

06

Memory Context

TinyAGI — Memory & Context

Memory Type

Hybrid: file-based (markdown files) + SQLite (message queue + state).

Memory Architecture

  • AGENTS.md — per-workspace protocol document with memory index section
  • memory/<path> — hierarchical markdown memory files indexed in AGENTS.md
  • SQLite — atomic message queue with retry/dead-letter management; persistent conversation history

Memory Persistence

Project-level per workspace. Each workspace (~/tinyagi-workspace/ or custom) has its own AGENTS.md and memory/ directory.

Cross-Session Handoff

Built-in via persistent sessions documented in README: "conversation context maintained across restarts." SQLite state and markdown memory both survive process restarts.

Context Compaction

Not explicitly addressed. Claude Code's default compaction applies to individual agent sessions; AGENTS.md and memory/ provide the recovery layer.

Streaming

REST API at localhost:3777 provides streaming events. TinyOffice subscribes to live event feed for real-time dashboard updates.

07

Orchestration

TinyAGI — Orchestration

Multi-Agent Pattern

Swarm (peer-to-peer message passing). Agents communicate via [@agent_id: message] tags parsed from their responses. There is no central orchestrator making routing decisions — each agent can message any other agent directly. Teams add an optional grouping layer ([#team_id: message]). This is the closest to a swarm or gossip pattern in the corpus.

Execution Mode

Background daemon (24/7). TinyAGI runs as a persistent background process. Agents process incoming messages from channels (Discord/Telegram/WhatsApp) and inter-agent messages continuously.

Multi-Model

Yes — supports Claude Code (Anthropic) and Codex (OpenAI) as providers. Different agents in the same team can run on different providers.

Isolation Mechanism

Process-level only. Each agent invocation is a separate Claude Code or Codex process but no git-branch or container isolation.

Max Concurrent Agents

Not specified. SQLite queue manages concurrency with atomic transactions.

Consensus

None. Peer-to-peer message routing; agents coordinate through messages, not consensus protocols.

Prompt Chaining

Yes. One agent's response (containing [@agent_id: message] tags) becomes the next agent's input. The system parses and routes the tags, creating emergent conversation chains.

08

Ui Cli Surface

TinyAGI — UI / CLI Surface

CLI Binary

  • Binary name: tinyagi
  • Language: Node.js (packages/cli/bin/tinyagi.mjs)
  • Install: curl | bash → global tinyagi command
  • NOT a thin wrapper: tinyagi manages the SQLite queue, agent daemon, channel adapters, and web portal startup — it is the full runtime.

Subcommands

tinyagi                    # Start daemon + open TinyOffice
tinyagi start              # Start daemon only
tinyagi agent list         # List agents
tinyagi channel setup      # Configure Discord/Telegram/WhatsApp
tinyagi office             # Build + start TinyOffice (localhost:3000)
tinyagi update             # Update to latest

Local UI Surface

TinyOffice — Web Portal (Primary GUI)

  • Type: Web dashboard
  • Port: localhost:3000
  • Tech stack: Next.js
  • Access: Run tinyagi office or visit office.tinyagicompany.com (connects to local API at localhost:3777)

TinyOffice Features

View Description
Dashboard Real-time queue/system overview + live event feed
Chat Console Send messages to agent, @agent, or @team
Agents & Teams CRUD for agents and teams
Tasks (Kanban) Create tasks, drag stages, assign to agents
Logs & Events Queue logs and streaming events
Settings Edit settings.json via UI
Office View Visual simulation of agent interactions
Org Chart Hierarchical team/agent visualization
Chat Rooms Slack-style persistent team chat rooms
Projects Project kanban with agent assignment

TUI Visualizer (Secondary)

  • Type: Terminal TUI
  • Port: N/A (CLI)
  • Stack: Node.js terminal (custom visualizer package)
  • Features: Real-time team visualizer, chatroom viewer

API (Internal)

  • Port: localhost:3777
  • Protocol: REST + streaming events
  • Purpose: Bridge between TinyOffice and the TinyAGI daemon

IDE Integration

None. TinyAGI is a standalone daemon + web portal.

Observability

  • Live event feed: TinyOffice dashboard streams queue events
  • Queue logs: Inspection of message queue state, retry counts, dead-letter items
  • Org chart: Visualizes agent hierarchy and team structure
  • Channel monitoring: Messages in/out via Discord/Telegram/WhatsApp visible in chat rooms

Comparison with CLAUDE-FLOW UI

Claude-flow has no local UI. TinyAGI has both a web portal (Next.js at :3000) and a TUI, making it the only framework in this batch that ships TWO local UI surfaces alongside a CLI binary. Claude-flow's execution is driven by slash-commands; TinyAGI's execution is event-driven (incoming channel messages → queue → agents). The web portal's kanban + org chart are the closest thing in this batch to a multi-agent "control room" — more organizational visibility than claude-flow's hive-mind-status command output.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…