stevengonsalvez/swarm-join

/swarm-join

Join an existing swarm team as a worker agent.

Usage

/swarm-join <team-id> --as <agent-name>

Arguments

| Argument | Required | Description | |----------|----------|-------------| | <team-id> | Yes | The swarm team ID to join (e.g., swarm-1738585396) | | --as | Yes | Agent name to use (e.g., agent-3) |

Process

When you receive this command:

1. Parse Arguments

   TEAM_ID="$1"        # First positional argument
   AGENT_NAME="$2"     # Value after --as
   

2. Validate Team Exists

   source {{HOME_TOOL_DIR}}/utils/swarm-lib.sh
   
   if ! swarm_get_team "$TEAM_ID" > /dev/null 2>&1; then
     echo "Error: Team $TEAM_ID not found"
     echo "Available teams:"
     swarm_list_teams
     exit 1
   fi
   

3. Check Capacity

   TEAM_JSON=$(swarm_get_team "$TEAM_ID")
   MAX_MEMBERS=$(echo "$TEAM_JSON" | jq -r '.config.max_members')
   CURRENT_COUNT=$(echo "$TEAM_JSON" | jq -r '.members | length')
   
   if [ "$CURRENT_COUNT" -ge "$MAX_MEMBERS" ]; then
     echo "Error: Team at max capacity ($MAX_MEMBERS members)"
     exit 1
   fi
   

4. Check Name Availability

   if echo "$TEAM_JSON" | jq -e ".members[] | select(.name == \"$AGENT_NAME\")" > /dev/null; then
     echo "Error: Agent name '$AGENT_NAME' already in use"
     exit 1
   fi
   

5. Spawn Agent

   AGENT_SESSION=$(swarm_spawn_agent "$TEAM_ID" "$AGENT_NAME")
   echo "Joined team as: $AGENT_NAME"
   echo "Session: $AGENT_SESSION"
   

6. Notify Leader

   swarm_send_message "$TEAM_ID" "$AGENT_NAME" "leader" "status" \
     '{"event": "joined", "message": "Agent '"$AGENT_NAME"' joined the team"}'
   

7. Report

   echo ""
   echo "========================================"
   echo "Joined Swarm: $TEAM_ID"
   echo "========================================"
   echo "Agent Name: $AGENT_NAME"
   echo "Session: $AGENT_SESSION"
   echo ""
   echo "Your inbox: {{HOME_TOOL_DIR}}/swarm/$TEAM_ID/inbox/$AGENT_NAME.jsonl"
   echo ""
   echo "Commands:"
   echo "  Check inbox:    /swarm-inbox"
   echo "  Send to leader: /swarm-inbox --to leader --msg \"message\""
   echo "  Team status:    /swarm-status $TEAM_ID"
   echo "========================================"
   

Example

# Join an existing team as agent-3
/swarm-join swarm-1738585396 --as agent-3

# List available teams first
{{HOME_TOOL_DIR}}/utils/swarm-lib.sh list-teams

Post-Join Behavior

After joining, the agent should:

1. Poll Inbox - Check for task assignments every 5 seconds
2. Report Ready - Notify leader you're available for work
3. Wait for Assignment - Leader will send task via inbox

Agent Responsibilities

As a team member, you must:

1. Monitor Your Inbox

   # Your inbox location
   {{HOME_TOOL_DIR}}/swarm/{team-id}/inbox/{agent-name}.jsonl
   

2. Execute Assigned Tasks

   • Tasks arrive as inbox messages with type task
   • Claim in Beads: bd update <task-id> --assignee <agent-name> --status in_progress

3. Report Progress

   • Send status updates to leader at key milestones
   • Use /swarm-inbox --to leader --msg "..." or library function

4. Handle Completion

   • Close task in Beads: bd close <task-id> --reason "Done"
   • Notify leader of completion
   • Wait for next assignment

Error Handling

| Error | Resolution | |-------|------------| | Team not found | Check team ID with swarm_list_teams | | At max capacity | Wait for a slot or increase max_members in team.json | | Name already used | Choose a different agent name | | Session conflict | An agent with this name may still be running |