Skip to content

TEAMS.md

Latest commit

 

History

History
265 lines (189 loc) · 9.27 KB

TEAMS.md

File metadata and controls

265 lines (189 loc) · 9.27 KB

Teams

Teams are named groups of agents that collaborate by passing messages to each other. When an agent responds with [@teammate: message] mentions, those become new messages in the queue, processed naturally by each agent's own promise chain. No central orchestrator — agents communicate directly.

How It Works

User: "@dev fix the auth bug"
           │
           ▼
   ┌───────────────┐
   │  Team: @dev   │
   │  Leader: coder│
   └───────┬───────┘
           ▼
   ┌───────────────┐    [@reviewer: please review]
   │   @coder      │──────────────────────────────┐
   │  "Fixed bug"  │                               ▼
   └───────────────┘                      ┌───────────────┐
                                          │  @reviewer    │
                                          │  "LGTM!"      │
                                          └───────────────┘
           │
           ▼
   All branches resolved → aggregate:
   @coder: Fixed the bug in auth.ts...
   ---
   @reviewer: Changes look good, approved!

Message Flow

  1. User sends @team_id message (or @agent_id where agent belongs to a team)
  2. Queue processor resolves the team and invokes the leader agent
  3. [@teammate: message] tags in the response become new messages in the queue
  4. Each mentioned agent processes its message via its own promise chain (parallel across agents)
  5. If an agent's response mentions more teammates, those become new messages too
  6. When all branches resolve (pending === 0), responses are aggregated and sent to the user

For detailed message patterns (fan-out, backflow, cross-talk, shared context), see MESSAGE-PATTERNS.md.

Team Context Auto-Detection

Even when messaging an agent directly (e.g., @coder fix this), team context is automatically activated if that agent belongs to a team. Teammate mentions in the response will still trigger message passing.

Configuration

Teams are stored in ~/.tinyagi/settings.json:

{
  "teams": {
    "dev": {
      "name": "Development Team",
      "agents": ["coder", "reviewer", "writer"],
      "leader_agent": "coder"
    }
  }
}
Field Description
name Human-readable display name
agents Array of agent IDs (must exist in agents config)
leader_agent Agent that receives @team_id messages first (must be in agents array)

Team IDs and agent IDs share the @ routing namespace, so they cannot collide. The interactive team add wizard enforces this.

Teammate Mention Formats

Agents can mention teammates in two ways:

Tag Format (recommended for multiple handoffs)

[@reviewer: Please check my changes to auth.ts]
[@writer: Document the new login flow]

This allows the agent to send a specific message to each teammate. The tag content becomes the message passed to that teammate.

Bare Mention (legacy, single handoff only)

@reviewer please check my changes

When using bare mentions, only the first valid teammate is matched and the full response is forwarded.

Message Patterns

See MESSAGE-PATTERNS.md for detailed documentation on:

  • Sequential handoff — one agent mentions one teammate
  • Fan-out — one agent mentions multiple teammates (parallel)
  • Backflow — agents message back to whoever mentioned them
  • Cross-talk — agents message each other after a fan-out
  • Shared context — text outside bracket tags delivered to all mentioned agents
  • Pending response indicator — prevents agents from re-mentioning teammates who are still processing

Chat Room

Every team has a persistent chat room — like an async Slack channel. Agents choose when to post to it using the [#team_id: message] tag. Chat room messages are not automatic; agents decide whether to broadcast to the room, DM specific teammates via [@agent: message], or just respond to the user.

How It Works

When an agent posts [#dev: message]:

  1. The message is persisted to the chat_messages table (for durability)
  2. The message is enqueued for every other teammate with the format: [Chat room #dev — @agent]: message
  3. When a teammate is next invoked, all pending chat room messages are batched and delivered together with its primary message

Usage

[#dev: I've finished the auth refactor, tests passing]

This broadcasts to everyone in the dev team. Agents can use this from any context, not just team conversations.

Chat Room vs. Conversation Tracker

These serve different audiences:

Conversation Tracker Chat Room
Audience The user The agents
Purpose Aggregate responses → single reply to user Give agents visibility into each other's work
Lifecycle Per-request (message → aggregated response) Persistent per-team
Mechanism In-memory Conversation with pending counter Queue-based message broadcasting
Storage In-memory only (lost on crash) chat_messages table (survives restarts)

The conversation tracker is still needed because:

  • Pending counter: knows when all agents are done so it can respond to the user
  • Response aggregation: combines multi-agent responses into one message for the user's channel
  • Loop protection: maxMessages cap prevents runaway chains
  • File collection: accumulates [send_file:] paths across all agents

The chat room is opt-in — agents decide when shared visibility is useful. The conversation tracker handles the user-facing response lifecycle regardless.

Viewing the Chat Room

CLI — real-time TUI with type-to-send:

tinyagi chatroom dev     # Watch and post to #dev chat room

The viewer polls for new messages every second and displays them in a scrolling log. Type a message and press Enter to post it to the chat room (delivered to all agents as [Chat room #team — @user]). Press q (when input is empty) or Esc to quit.

API — for programmatic access:

GET  /api/chatroom/:teamId          — Get recent messages (?limit=100&since=0)
POST /api/chatroom/:teamId          — Post a message (body: { "message": "..." })

Chat History

Team conversations are saved to ~/.tinyagi/chats/{team_id}/ as timestamped Markdown files.

Each file contains:

  • Team name and metadata (date, channel, sender, message count)
  • The original user message
  • Each agent's response with agent name

Example file (~/.tinyagi/chats/dev/2026-02-13_14-30-00.md):

# Team Conversation: Development Team (@dev)
**Date:** 2026-02-13T14:30:00.000Z
**Channel:** discord | **Sender:** alice
**Messages:** 3

------

## User Message

Fix the auth bug in login.ts

------

## Code Assistant (@coder)

I found and fixed the bug...

------

## Code Reviewer (@reviewer)

Changes look good, approved!

Live Visualizer

Monitor team chains in real-time with the TUI dashboard:

tinyagi team visualize         # Watch all teams
tinyagi team visualize dev     # Watch specific team

The visualizer displays:

  • Agent cards with status (idle, active, done, error), provider/model, and leader indicator
  • Chain flow showing handoff arrows between agents
  • Activity log of recent events with timestamps
  • Status bar with queue depth and processing counts

Press q to quit.

CLI Commands

tinyagi team list              # List all teams
tinyagi team add               # Add a new team (interactive wizard)
tinyagi team show dev          # Show team configuration
tinyagi team remove dev        # Remove a team
tinyagi team add-agent dev reviewer     # Add @reviewer to @dev
tinyagi team remove-agent dev reviewer  # Remove @reviewer from @dev
tinyagi team visualize [id]    # Live TUI dashboard

In-Chat Commands

Command Description
/team List all available teams
@team_id message Route to team's leader agent
@agent_id message Route to agent directly (team context still active if agent is in a team)

Events

Team conversations emit events via SSE (GET /api/events/stream) for the visualizer and web dashboard:

Event Description
team_chain_start Conversation begins (team ID, agents, leader)
chain_step_done Agent responds (includes response text)
chain_handoff Agent mentions a teammate (from → to)
team_chain_end Conversation complete (total messages, agent list)

Example: Setting Up a Dev Team

# 1. Create agents
tinyagi agent add    # Create "coder" agent
tinyagi agent add    # Create "reviewer" agent

# 2. Create team
tinyagi team add     # Interactive: name "dev", agents [coder, reviewer], leader: coder

# 3. Send a message
tinyagi send "@dev fix the auth bug"

# 4. Watch it work
tinyagi team visualize dev

See Also