@ebowwa/teammates

TypeScript implementation of Claude Code teammates system for multi-agent coordination and messaging.

Features

• Team Management: Create, load, and manage teams of AI agents
• Teammate Lifecycle: Spawn, coordinate, and gracefully shutdown teammates
• Inter-Agent Messaging: Direct messages, broadcasts, and notifications
• Request/Response Pattern: Shutdown requests and plan approval workflows
• Type Safety: Full TypeScript support with Zod validation
• Persistent Storage: Team configs and inboxes stored in ~/.claude/teams/

Installation

bun add @ebowwa/teammates

Quick Start

import { Team, Teammate } from '@ebowwa/teammates';

// Create a new team
const team = await Team.create({
  name: 'my-team',
  description: 'My awesome team',
});

// Spawn a teammate
const explorer = await Teammate.create('my-team', {
  name: 'explorer',
  subagentType: 'Explore',
  prompt: 'Explore the codebase and report findings',
  color: 'blue',
});

// Send a message to the teammate
await explorer.sendTo('team-lead', 'I found 50 TypeScript files!');

// Clean up
await Team.delete('my-team');

Core Concepts

Teams

A Team is a collection of AI agents working together on a shared task. Teams have:

• A unique name
• A team lead (the main Claude session)
• One or more teammates (independent Claude sessions)
• Shared configuration and messaging

Teammates

A Teammate is an independent Claude Code session with:

• A unique agent ID (e.g., explorer@my-team)
• A human-readable name
• An agent type (general-purpose, Explore, Plan, etc.)
• A dedicated inbox for receiving messages

Messages

Teammates communicate through messages of different types:

| Type | Description | |------|-------------| | message | Direct message to a specific teammate | | broadcast | Send to all teammates simultaneously | | shutdown_request | Request a teammate to shut down | | shutdown_response | Approve or deny shutdown | | idle_notification | Notify that teammate is idle |

API Reference

Team

// Create a new team
const team = await Team.create({
  name: 'my-team',
  description: 'Optional description',
  leadAgentType: 'general-purpose',
});

// Load existing team
const team = await Team.load('my-team');

// Get team properties
console.log(team.name);
console.log(team.members);
console.log(team.leadAgentId);

// Find members
const member = team.findMember('explorer@my-team');
const byName = team.findMemberByName('explorer');

// Broadcast to all teammates
await team.broadcast('team-lead', 'Hello everyone!', 'Greeting');

// Delete team (must have no active teammates)
await Team.delete('my-team');

// Check if team exists
const exists = await Team.exists('my-team');

// List all teams
const teams = await Team.listAll();

Teammate

// Create a teammate
const teammate = await Teammate.create('my-team', {
  name: 'explorer',
  subagentType: 'Explore',
  prompt: 'Your task description',
  color: 'blue',
  mode: 'acceptEdits',
  model: 'claude-opus-4-6',
});

// Load existing teammate
const teammate = await Teammate.fromTeam('my-team', 'explorer@my-team');

// Get properties
console.log(teammate.name);
console.log(teammate.agentId);
console.log(teammate.getStatus());

// Send messages
await teammate.sendTo('team-lead', 'Task complete!', 'Report');

// Request shutdown
await teammate.requestShutdown('Finished my work');

// Notify idle
await teammate.notifyIdle('waiting for work');

// Get inbox
const inbox = await teammate.getInbox();
const unread = await teammate.getUnreadMessages();
await teammate.markAsRead();

Messaging

import {
  sendMessage,
  broadcastMessage,
  requestShutdown,
  sendIdleNotification,
} from '@ebowwa/teammates';

// Direct message
await sendMessage('my-team', 'sender@my-team', 'receiver@my-team', 'Hello!');

// Broadcast to all
await broadcastMessage('my-team', 'sender@my-team', ['id1', 'id2'], 'Broadcast!');

// Shutdown request
const requestId = await requestShutdown('my-team', 'lead', 'teammate');

// Idle notification
await sendIdleNotification('my-team', 'teammate', 'lead', 'available');

File Structure

Teams are stored in ~/.claude/teams/{team-name}/:

~/.claude/teams/
└── my-team/
    ├── config.json          # Team configuration
    └── inboxes/
        ├── team-lead.json   # Lead's inbox
        ├── explorer.json    # Explorer's inbox
        └── architect.json   # Architect's inbox

License

MIT

Author

Ebowwa Labs [email protected]