ruvnet__ruflo/v3/plugins/teammate-plugin/README.md

@claude-flow/teammate-plugin

Native TeammateTool integration plugin for Claude Flow. Bridges Claude Code v2.1.19+ multi-agent orchestration capabilities with Claude Flow's swarm system.

Requirements

Requirement	Minimum Version	Recommended
Claude Code	>= 2.1.19	Latest
Node.js	>= 18.0.0	>= 20.0.0
npm	>= 9.0.0	>= 10.0.0

IMPORTANT: This plugin requires Claude Code version 2.1.19 or higher. The TeammateTool functionality was introduced in this version and is not available in earlier releases.

Version Check

# Check your Claude Code version
claude --version

# Should output: 2.1.19 or higher

If your version is below 2.1.19, update Claude Code:

claude update

Installation

Via Claude Code CLI (Recommended)

Install directly using Claude Code's plugin system:

# Install from npm registry
claude plugins install @claude-flow/teammate-plugin

# Or install from Claude Flow plugin registry (IPFS-backed)
claude plugins install teammate-plugin --registry claude-flow

Via npm

npm install @claude-flow/teammate-plugin

Or with pnpm:

pnpm add @claude-flow/teammate-plugin

Via Claude Flow CLI

# Install via claude-flow plugin manager
npx @claude-flow/cli@latest plugins install --name @claude-flow/teammate-plugin

# Or add to your claude-flow.config.json
npx @claude-flow/cli@latest config set plugins.teammate-plugin.enabled true

Verify Installation

# Check plugin is loaded
claude plugins list

# Or via claude-flow
npx @claude-flow/cli@latest plugins list

Quick Start

import { createTeammateBridge } from '@claude-flow/teammate-plugin';

// Initialize the bridge
const bridge = await createTeammateBridge();

// Check compatibility
const version = bridge.getVersionInfo();
console.log(`Claude Code: ${version.claudeCode}`);
console.log(`Compatible: ${version.compatible}`);

if (!version.compatible) {
  console.error('Please upgrade Claude Code to >= 2.1.19');
  process.exit(1);
}

// Create a team
const team = await bridge.spawnTeam({
  name: 'my-dev-team',
  topology: 'hierarchical',
  maxTeammates: 6,
  planModeRequired: true,
});

// Spawn teammates (returns AgentInput for Claude Code Task tool)
const coder = await bridge.spawnTeammate({
  name: 'coder-1',
  role: 'coder',
  prompt: 'Implement the authentication feature using JWT',
  teamName: 'my-dev-team',
  model: 'sonnet',
  allowedTools: ['Edit', 'Write', 'Read', 'Bash'],
});

// The agentInput can be passed to Claude Code's Task tool
const agentInput = bridge.buildAgentInput({
  name: 'tester-1',
  role: 'tester',
  prompt: 'Write tests for the authentication feature',
  teamName: 'my-dev-team',
  model: 'haiku',
});

console.log('Pass this to Task tool:', agentInput);

Features

Core Features (from TeammateTool)

Feature	Description	TeammateTool Operation
Team Management	Create, discover, load teams	spawnTeam, discoverTeams
Teammate Spawning	Spawn agents with native support	AgentInput schema
Join/Leave Workflow	Request-approve-reject pattern	requestJoin, approveJoin, rejectJoin
Messaging	Direct and broadcast messages	write, broadcast
Plan Approval	Submit, vote, execute plans	approvePlan, rejectPlan
Swarm Launch	Launch multi-agent execution	launchSwarm, teammateCount
Shutdown	Graceful teammate termination	requestShutdown, approveShutdown

Extended Features (Plugin Additions)

Feature	Description
Delegation	Delegate authority between teammates
Team Context	Shared variables, permissions, environment
Permission Updates	Dynamic permission changes mid-execution
Session Memory	Persist teammate context across sessions
Remote Sync	Push team to Claude.ai (experimental)
Transcript Sharing	Share message history between teammates
Teleport	Resume teams across terminal instances
Plan Control	Pause, resume, modify plans mid-execution

API Reference

TeammateBridge

The main class for interacting with TeammateTool.

Initialization

import { createTeammateBridge, TeammateBridge } from '@claude-flow/teammate-plugin';

// Factory function (recommended)
const bridge = await createTeammateBridge({
  fallbackToMCP: true,  // Fallback to MCP if TeammateTool unavailable
  memory: {
    autoPersist: true,
    persistIntervalMs: 60000,
  },
});

// Or direct instantiation
const bridge = new TeammateBridge(config);
await bridge.initialize();

Team Management

// Create team
const team = await bridge.spawnTeam({
  name: 'my-team',
  topology: 'hierarchical',  // 'flat' | 'hierarchical' | 'mesh'
  maxTeammates: 8,
  planModeRequired: true,
  autoApproveJoin: true,
  delegationEnabled: true,
});

// Discover existing teams
const teams = await bridge.discoverTeams();
// ['team-1', 'team-2', ...]

// Load existing team
const existingTeam = await bridge.loadTeam('team-1');

// Get team state
const state = bridge.getTeamState('my-team');

Teammate Spawning

// Spawn teammate
const teammate = await bridge.spawnTeammate({
  name: 'coder-1',
  role: 'coder',
  prompt: 'Implement feature X',
  teamName: 'my-team',
  model: 'sonnet',  // 'sonnet' | 'opus' | 'haiku'
  allowedTools: ['Edit', 'Write', 'Read'],
  mode: 'default',  // 'default' | 'plan' | 'delegate' | etc.
});

// Build AgentInput for Task tool
const agentInput = bridge.buildAgentInput({
  name: 'reviewer-1',
  role: 'reviewer',
  prompt: 'Review code changes',
  teamName: 'my-team',
});
// Pass agentInput to Claude Code's Task tool

Messaging

// Send direct message
const message = await bridge.sendMessage(
  'my-team',
  'sender-id',
  'recipient-id',
  {
    type: 'task',
    payload: { action: 'implement', target: 'auth' },
    priority: 'high',
  }
);

// Broadcast to all teammates
await bridge.broadcast('my-team', 'coordinator-id', {
  type: 'status',
  payload: { phase: 'implementation' },
});

// Read mailbox
const messages = await bridge.readMailbox('my-team', 'teammate-id');

Plan Approval

// Submit plan
const plan = await bridge.submitPlan('my-team', {
  description: 'Implement authentication feature',
  proposedBy: 'coordinator-id',
  steps: [
    { order: 1, action: 'Create user model', tools: ['Edit'], assignee: 'coder-1' },
    { order: 2, action: 'Add JWT middleware', tools: ['Edit'], assignee: 'coder-1' },
    { order: 3, action: 'Write unit tests', tools: ['Edit'], assignee: 'tester-1' },
  ],
  requiredApprovals: 2,
});

// Approve plan
await bridge.approvePlan('my-team', plan.id, 'reviewer-id');

// Launch swarm (after approval)
const exitPlanInput = await bridge.launchSwarm('my-team', plan.id, 3);
// Pass exitPlanInput to ExitPlanMode tool

Delegation

// Delegate authority
const delegation = await bridge.delegateToTeammate(
  'my-team',
  'lead-id',
  'dev-id',
  ['approve_plan', 'spawn_teammate']
);

// Revoke delegation
await bridge.revokeDelegation('my-team', 'lead-id', 'dev-id');

Team Context

// Update context
await bridge.updateTeamContext('my-team', {
  sharedVariables: {
    apiEndpoint: 'https://api.example.com',
    version: '1.0.0',
  },
  inheritedPermissions: ['read', 'write'],
  environmentVariables: {
    NODE_ENV: 'development',
  },
});

// Get context
const context = bridge.getTeamContext('my-team');

Session Memory

// Save teammate memory
await bridge.saveTeammateMemory('my-team', 'teammate-id');

// Load teammate memory
const memory = await bridge.loadTeammateMemory('my-team', 'teammate-id');

// Share transcript
await bridge.shareTranscript('my-team', 'from-id', 'to-id', {
  start: 0,
  end: 10,
});

Teleport

// Check if teleport is possible
const { canTeleport, blockers } = await bridge.canTeleport('my-team', {
  workingDirectory: '/path/to/new/dir',
  gitBranch: 'feature/auth',
});

// Teleport team
if (canTeleport) {
  const result = await bridge.teleportTeam('my-team', {
    workingDirectory: '/path/to/new/dir',
    gitBranch: 'feature/auth',
  });
}

MCP Tools

The plugin provides 16 MCP tools for use with Claude Code's MCP server:

import { TEAMMATE_MCP_TOOLS, handleMCPTool } from '@claude-flow/teammate-plugin';

// List all tools
console.log(TEAMMATE_MCP_TOOLS.map(t => t.name));
// [
//   'teammate_spawn_team',
//   'teammate_discover_teams',
//   'teammate_spawn',
//   'teammate_send_message',
//   'teammate_broadcast',
//   'teammate_submit_plan',
//   'teammate_approve_plan',
//   'teammate_launch_swarm',
//   'teammate_delegate',
//   'teammate_update_context',
//   'teammate_save_memory',
//   'teammate_share_transcript',
//   'teammate_push_remote',
//   'teammate_teleport',
//   'teammate_get_status',
//   'teammate_cleanup',
// ]

// Handle tool call
const result = await handleMCPTool(bridge, 'teammate_spawn_team', {
  name: 'my-team',
  topology: 'hierarchical',
});

Events

The bridge emits events for all operations:

bridge.on('team:spawned', ({ team, config }) => {
  console.log(`Team ${team} created`);
});

bridge.on('teammate:spawned', ({ teammate, agentInput }) => {
  console.log(`Teammate ${teammate.name} spawned`);
});

bridge.on('plan:approved', ({ team, plan }) => {
  console.log(`Plan ${plan.id} approved`);
});

bridge.on('delegate:granted', ({ team, from, to, permissions }) => {
  console.log(`${from} delegated to ${to}: ${permissions.join(', ')}`);
});

bridge.on('teleport:completed', ({ team, result }) => {
  console.log(`Team ${team} teleported successfully`);
});

Error Handling

import { TeammateError, TeammateErrorCode } from '@claude-flow/teammate-plugin';

try {
  await bridge.launchSwarm('my-team', 'plan-id');
} catch (error) {
  if (error instanceof TeammateError) {
    switch (error.code) {
      case TeammateErrorCode.PLAN_NOT_APPROVED:
        console.log('Plan needs approval first');
        break;
      case TeammateErrorCode.TEAM_NOT_FOUND:
        console.log(`Team not found: ${error.teamName}`);
        break;
      case TeammateErrorCode.VERSION_INCOMPATIBLE:
        console.log('Claude Code version too old');
        break;
    }
  }
}

Configuration

import { createTeammateBridge, DEFAULT_PLUGIN_CONFIG } from '@claude-flow/teammate-plugin';

const bridge = await createTeammateBridge({
  autoInitialize: true,
  fallbackToMCP: true,

  recovery: {
    maxRetries: 3,
    retryDelayMs: 1000,
    exponentialBackoff: true,
    fallbackToMCP: true,
    autoCleanupOnError: true,
  },

  delegation: {
    maxDepth: 3,
    autoExpireMs: 3600000,  // 1 hour
    requireApproval: false,
  },

  remoteSync: {
    enabled: false,
    autoSync: false,
    syncInterval: 30000,
    preserveOnDisconnect: true,
  },

  teleport: {
    autoResume: true,
    gitAware: true,
    preserveMailbox: true,
    preserveMemory: true,
  },

  memory: {
    autoPersist: true,
    persistIntervalMs: 60000,
    maxSizeMb: 100,
  },

  mailbox: {
    pollingIntervalMs: 1000,
    maxMessages: 1000,
    retentionMs: 3600000,
  },
});

Integration with Claude Flow

import { createTeammateBridge } from '@claude-flow/teammate-plugin';
import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';

// Create bridge
const bridge = await createTeammateBridge();

// Map Claude Flow topology to team config
const teamConfig = {
  name: 'cf-team',
  topology: 'hierarchical',  // Maps to Claude Flow's hierarchical
  maxTeammates: 8,
  planModeRequired: true,
};

// Create team
const team = await bridge.spawnTeam(teamConfig);

// Map Claude Flow agent types to teammate configs
const agentMapping = {
  'coder': { role: 'coder', tools: ['Edit', 'Write', 'Read', 'Bash'] },
  'tester': { role: 'tester', tools: ['Read', 'Bash', 'Glob'] },
  'reviewer': { role: 'reviewer', tools: ['Read', 'Grep', 'Glob'] },
  'architect': { role: 'architect', tools: ['Read', 'Glob', 'Grep'] },
};

// Spawn teammates with Claude Flow agent types
for (const [type, config] of Object.entries(agentMapping)) {
  await bridge.spawnTeammate({
    name: `${type}-1`,
    role: config.role,
    prompt: `You are a ${type}...`,
    teamName: 'cf-team',
    allowedTools: config.tools,
  });
}

File Structure

Teams are stored in ~/.claude/teams/:

~/.claude/teams/
├── my-team/
│   ├── config.json        # Team configuration
│   ├── state.json         # Team state (teammates, plans)
│   ├── remote.json        # Remote session info (if synced)
│   ├── mailbox/
│   │   ├── teammate-1.json
│   │   └── teammate-2.json
│   └── memory/
│       ├── teammate-1.json
│       └── teammate-2.json
└── other-team/
    └── ...

Environment Variables

The plugin uses these Claude Code environment variables:

CLAUDE_CODE_TEAM_NAME          # Current team context
CLAUDE_CODE_PLAN_MODE_REQUIRED # Require plan approval
CLAUDE_CODE_TMUX_SESSION       # tmux session name
CLAUDE_CODE_TMUX_PREFIX        # tmux prefix key
CLAUDE_CODE_TEAMMATE_COMMAND   # Custom spawn command

Troubleshooting

Plugin reports TeammateTool not available

const version = bridge.getVersionInfo();
if (!version.compatible) {
  console.log(`Claude Code version: ${version.claudeCode}`);
  console.log(`Required: >= 2.1.19`);
  console.log('Run: claude update');
}

Mailbox messages not received

Check that mailbox polling is running:

// Mailbox is polled automatically, but you can read manually
const messages = await bridge.readMailbox('my-team', 'teammate-id');

Plan approval stuck

Ensure enough teammates have voted:

const team = bridge.getTeamState('my-team');
const plan = team.activePlans.find(p => p.id === planId);

console.log(`Approvals: ${plan.approvals.length}/${plan.requiredApprovals}`);
console.log(`Rejections: ${plan.rejections.length}`);

Testing the Plugin

Run Unit Tests

cd v3/plugins/teammate-plugin

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Verify Plugin Functionality

import { createTeammateBridge, TEAMMATE_MCP_TOOLS } from '@claude-flow/teammate-plugin';

async function verifyPlugin() {
  console.log('=== Plugin Verification ===\n');

  // 1. Check MCP tools are exported
  console.log(`✓ MCP Tools available: ${TEAMMATE_MCP_TOOLS.length}`);

  // 2. Initialize bridge
  const bridge = await createTeammateBridge();
  console.log('✓ Bridge initialized');

  // 3. Check version compatibility
  const version = bridge.getVersionInfo();
  console.log(`✓ Claude Code version: ${version.claudeCode || 'not detected'}`);
  console.log(`✓ Plugin version: ${version.plugin}`);
  console.log(`✓ Compatible: ${version.compatible}`);

  // 4. Test team creation (if compatible)
  if (version.compatible) {
    const team = await bridge.spawnTeam({ name: 'test-team' });
    console.log(`✓ Team created: ${team.name}`);

    // Cleanup
    await bridge.cleanup('test-team');
    console.log('✓ Cleanup successful');
  }

  console.log('\n=== All checks passed! ===');
}

verifyPlugin().catch(console.error);

Verify via CLI

# Check plugin is registered
npx @claude-flow/cli@latest plugins list | grep teammate

# Check plugin info
npx @claude-flow/cli@latest plugins info teammate-plugin

# Test MCP tools
npx @claude-flow/cli@latest mcp tools | grep teammate

Plugin Registry (IPFS)

This plugin is published to the Claude Flow Plugin Registry on IPFS for decentralized distribution.

Registry Entry

{
  "name": "teammate-plugin",
  "package": "@claude-flow/teammate-plugin",
  "version": "1.0.0-alpha.1",
  "description": "Native TeammateTool integration for Claude Code v2.1.19+",
  "author": "Claude Flow Team",
  "license": "MIT",
  "repository": "https://github.com/ruvnet/claude-flow",
  "keywords": ["claude-code", "teammate", "multi-agent", "swarm"],
  "requirements": {
    "claudeCode": ">=2.1.19",
    "node": ">=18.0.0"
  },
  "mcpTools": 21,
  "features": [
    "team-management",
    "teammate-spawning",
    "messaging",
    "plan-approval",
    "delegation",
    "remote-sync",
    "bmssp-optimization"
  ]
}

Install from Registry

# Install from IPFS-backed registry
npx @claude-flow/cli@latest plugins install teammate-plugin --registry ipfs

# Or specify registry CID directly
npx @claude-flow/cli@latest plugins install teammate-plugin --cid <registry-cid>

Verify Registry Integrity

# Check plugin hash matches registry
npx @claude-flow/cli@latest plugins verify teammate-plugin

# View registry metadata
npx @claude-flow/cli@latest plugins registry info

License

MIT

Related

• Claude Flow - Multi-agent orchestration framework
• Claude Code - Anthropic's CLI for Claude
• ADR-027 - Architecture decision record