@nbonamy/claude-crew

v1.0.6

Published

4 days ago

Async agent-to-agent communication for Claude Code via MCP

0High
0Medium
0Low

nbonamy

Claude Crew

Async agent-to-agent communication for Claude Code via MCP.

Installation

Install the crew plugin from the marketplace:

# Add the nbonamy marketplace
claude plugin marketplace add nbonamy/claude-marketplace

# Install the crew plugin
claude plugin install crew@nbonamy

Then add the crew MCP server:

User install (recommended): claude mcp add --transport http crew --scope user http://localhost:3333/mcp
Local install: claude mcp add --transport http crew --scope local http://localhost:3333/mcp

Finally, follow the Quick Start section below to start the server.

If you installed the marketplace or plugin using the /plugin command in Claude Code, you need to exit and restart Claude Code.

Quick Start

Terminal 1: Start the shared server

npx @nbonamy/claude-crew

Terminal 2: Start Claude Code

claude

The plugin connects to the HTTP server on http://localhost:3333/mcp. Now you have /crew:send, /crew:check, /crew:list available!

Multiple Claude Code instances can connect to the same server.

Usage

Basic Workflow

Terminal 1 (~/project-desktop):

$ claude

Agent registered with crew as: project-desktop
Your crew session ID is: fa0b9d64-10f5-4086-a911-b310747efc00
Use this session ID when calling crew MCP tools (check-messages, send-message, etc.)

> /crew:list
# Shows all registered agents

> /crew:send ask server to run the tests and send me a report
# Message sent!

Terminal 2 (~/project-server):

$ claude

Agent registered with crew as: project-server
Your crew session ID is: 50714b14-d077-48c7-a41b-c9c8fe6e3f63
Use this session ID when calling crew MCP tools (check-messages, send-message, etc.)

> /crew:check
# [UNREAD] From: project-desktop
# Message: Can you run the tests?

> Running tests...
# (agent executes the request)

> Sending report to desktop: All 42 tests green!
# Message sent!

Commands

`/crew:list`

List all registered agents with their session IDs, folders, and message counts.

`/crew:send`

Send a message to another agent. Natural language parsing - e.g., /crew:send a message to server about running tests or just /crew:send and Claude deduces from context.

`/crew:check`

Check your messages. Claude will:

Retrieve all pending messages (uses session ID from startup)
Mark them as read
Reply to questions, execute instructions, or display results

How It Works

Server Components

MCP Server (Streamable HTTP Transport)
- Listens on http://localhost:3333/mcp
- Provides 5 MCP tools: register-agent, unregister-agent, list-agents, send-message, check-messages
- Each HTTP connection gets its own server instance sharing the same in-memory storage
REST API (for Hooks)
- POST /api/register - Called by SessionStart hook
- POST /api/unregister - Called by SessionEnd hook
- These bypass MCP since hooks run before MCP connection is established
In-Memory Storage
- Agents: Map of sessionId → {sessionId, name, baseFolder, timestamps}
- Messages: Array of {id, from, to, content, timestamp, read}
- Shared across all MCP server instances

Plugin Components

SessionStart Hook
- Runs when Claude Code starts
- Calls REST API /api/register to register agent with its folder path
- Returns hookSpecificOutput with additionalContext containing:
  - Agent name
  - Session ID
  - Instructions for using crew MCP tools
- Session ID is required for all crew MCP tool calls
SessionEnd Hook
- Runs when Claude Code exits
- Calls REST API /api/unregister to remove agent from crew
Commands
- /crew:list - List all registered agents
- /crew:send - Send message to another agent
- /crew:check - Check and respond to messages

Development Mode Setup

1. Start the Server

# Using npm package (simplest)
npx @nbonamy/claude-crew

# Development (with hot reload)
make dev

# Production (with pm2)
make start
make logs    # View logs
make stop    # Stop server

2. Configure MCP Server

Choose a scope:

local - Only for current project
user - Available in all projects on your machine

# User scope (recommended)
claude mcp add --transport http crew --scope user http://localhost:3333/mcp

# Local scope (current project only)
claude mcp add --transport http crew --scope local http://localhost:3333/mcp

# Verify
claude mcp list

3. Install Plugin

IMPORTANT: Use --plugin-dir - don't copy to ~/.claude/plugins/ (won't register properly)

claude --plugin-dir ~/src/claude-crew/plugin

Agent Naming

Agents are automatically named from their base folder:

/Users/name/projects/station1-desktop → "station1-desktop"
/Users/name/work/api-server → "api-server"
/tmp/test → "test"

Use /crew:list to see all agent names and find the right recipient.

Message Flow

Registration: SessionStart hook → REST API /api/register → Agent registered → hookSpecificOutput with session ID & instructions added to context
Send: /crew:send → Claude calls send-message MCP tool → Message queued
Check: /crew:check → Claude calls check-messages MCP tool → Messages retrieved
Response: Claude reads message → Executes instruction or replies automatically
Cleanup: SessionEnd hook → REST API /api/unregister → Agent unregistered

Development

Makefile Commands

make install   # Install dependencies
make build     # Build TypeScript
make dev       # Watch mode (hot reload)
make start     # Start with pm2
make stop      # Stop pm2
make restart   # Restart pm2
make logs      # View pm2 logs
make clean     # Clean build artifacts

Server Logs

The server logs all operations:

✓ Agent registered: project-desktop (fa0b9d64...) from /Users/name/projects/desktop
📋 List agents: 2 registered
✉ Message sent: project-server → project-desktop (Can you run the tests?)
📬 Check messages: project-desktop (1 message, marked as read)
✓ Agent unregistered: project-desktop

Testing Endpoints

# Health check
curl http://localhost:3333/health

# Register agent (REST API)
curl -X POST http://localhost:3333/api/register \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"test123","baseFolder":"/tmp/test"}'

# List agents (REST API)
curl http://localhost:3333/api/list

Troubleshooting

Plugin not showing up

Don't copy to ~/.claude/plugins/ - use --plugin-dir instead. Manual copying doesn't register the plugin in installed_plugins.json.

Hook hangs on startup

Check that the server is running (curl http://localhost:3333/health). Hooks have a 30-second timeout.

Messages not received

Both agents must be registered. Use /crew:list to verify registration. Check server logs with make logs.

Session ID issues

The startup hook should output your session ID. If not, check the hook logs or restart Claude Code.

Environment Variables

PORT - Server port (default: 3333)
AGENT_MANAGER_URL - Server URL for hooks (default: http://localhost:3333)

License

MIT