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

$3

``bash


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:

`bash
claude update
`

Installation

$3

Install directly using Claude Code's plugin system:

`bash


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
`

$3

`bash
npm install @claude-flow/teammate-plugin
`

Or with pnpm:

`bash
pnpm add @claude-flow/teammate-plugin
`

$3

`bash


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
`

$3

`bash


Check plugin is loaded

claude plugins list

Or via claude-flow

npx @claude-flow/cli@latest plugins list
`

Quick Start

`typescript
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

$3

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

$3

| 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

$3

The main class for interacting with TeammateTool.

#### Initialization

`typescript
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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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',
});
}
`

$3

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

`typescript
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:

`typescript
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

`typescript
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

`typescript
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

`typescript
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:

`bash
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

$3

`typescript
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');
}
`

$3

Check that mailbox polling is running:

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

$3

Ensure enough teammates have voted:

`typescript
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

$3

`bash
cd v3/plugins/teammate-plugin

Install dependencies

npm install

Run tests

npm test

Run tests with coverage

npm run test:coverage
`

$3

`typescript
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);
`

$3

`bash


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.

$3

`json
{
"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"
]
}
`

$3

`bash


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
`

$3

`bash


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