deep-dive

How Agent Teams and Swarm Coordination Work in Personal AI Infrastructure (PAI)

February 16, 2026 danielmiessler/personal_ai_infrastructure ↗

Agent teams in PAI are coordinated swarms of autonomous workers that share task lists and execute in parallel, triggered by the specific phrase "create an agent team" and orchestrated through the experimental TeamCreate tool.

Personal AI Infrastructure (PAI) by Daniel Miessler extends single-agent workflows into collaborative agent teams that operate as a coordinated swarm. This architecture allows multiple autonomous agents to decompose complex problems, execute criteria in parallel, and synchronize state through shared memory and message passing.

What Are Agent Teams in PAI?

An agent team (also called a swarm) is a coordinated collection of agents that operate on shared work items. All members see the same list of criteria and can report progress, blockers, or results to each other. This design treats agents as autonomous workers capable of tackling complex problems that would overwhelm a single agent.

Key characteristics include:

  • Shared Task Lists: Every team member accesses the same criteria and PRD (Product Requirements Document) slices.
  • Parallel Execution: Workers run simultaneously rather than sequentially.
  • Message Exchange: Agents broadcast findings or request assistance via structured messaging.

How Swarm Coordination Is Triggered

Teams are created only when an agent outputs the exact phrase "create an agent team". This activates the experimental TeamCreate tool, which requires the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to be set.

According to the source documentation in Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md at line 801, this trigger phrase is the critical invocation point. Without this specific output, the system treats the request as a standard single-agent task.

The Agent Team Lifecycle

The lifecycle follows a deterministic sequence defined in the Algorithm component:

  1. Lead Agent Calls TeamCreate: The primary agent identifies the need for parallelization and triggers team creation.
  2. Workers Spawn with Task Tool: Child agents are spawned using the standard Task tool calls that include a team_name parameter.
  3. Independent Algorithm Iteration: Each worker runs its own iteration of the Algorithm against a child PRD or a slice of the parent PRD.
  4. Result Aggregation: The lead agent aggregates results, updates the parent PRD, and marks the team as complete.

This process is documented in Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md at line 805 under the section "When decomposing into child PRDs".

Parallel Agent Orchestration and Load Balancing

When running in loop mode, the ‑a <N> CLI flag tells the algorithm how many agents to run concurrently. The runtime partitions failing criteria among agents using a greedy load-balancer implemented in the partitionCriteria function.

State Management

The system maintains shared state in MEMORY/STATE/algorithms/<session>.json. This file stores:

  • The list of active agents
  • Assigned criteria per agent
  • Current progress and phase history

The LoopAlgorithmState interface defined in Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts at line 80 structures this data, containing parallelAgents, an agents[] array, and phaseHistory.

The partitionCriteria Algorithm

The partitionCriteria function at line 545 of Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts implements greedy load-balancing:

  • It filters for failing criteria
  • Groups criteria by ISC domain (e.g., ISC-API-1 → "API")
  • Assigns the largest domain groups to the least-loaded agents
  • Ensures domain cohesion by keeping related criteria together on the same agent

Code Examples

Running the Algorithm with a Swarm of 4 Agents


# Run a PRD in loop mode using four parallel agents

algorithm -m loop -p PRD-20260213-feature -n 30 -a 4

The ‑a 4 flag instructs the core engine to create a team of four workers. The partitioning logic in partitionCriteria distributes failing criteria across the agents while maintaining domain cohesion.

Minimal TypeScript Snippet for Manual Team Creation

import { spawnSync } from "child_process";

// 1️⃣ Tell the model to create a team (must include the exact trigger phrase)
const createTeamPrompt = `Please create an agent team to audit security.`;
spawnSync("claude", [
  "-p", createTeamPrompt,
  "--allowedTools", "TeamCreate,SendMessage"
]);

// 2️⃣ Spawn three workers that belong to the team
const teamName = "security-audit";
["pentester", "recon", "qatester"].forEach(role => {
  spawnSync("claude", [
    "-p", `Run ${role} tasks on the PRD.`,
    "--allowedTools", "Task", // Task tool will inherit `team_name`
    "--env", `TEAM_NAME=${teamName}`
  ]);
});

The first call must contain the mandatory phrase "create an agent team" to trigger the experimental tool. Subsequent calls inherit the TEAM_NAME environment variable so the algorithm registers them under the same team.

The partitionCriteria Implementation

function partitionCriteria(criteriaInfo: CriteriaInfo, agentCount: number): AgentAssignment[] {
  const failing = criteriaInfo.criteria.filter(c => c.status === "failing");
  if (failing.length === 0) return [];

  // Group by ISC domain (e.g., ISC‑API‑1 → "API")
  function getDomain(id: string) {
    const m = id.match(/^ISC-(.+)-\d+$/);
    return m ? m[1] : id;
  }

  const domainGroups = new Map<string, typeof failing>();
  for (const c of failing) {
    const d = getDomain(c.id);
    if (!domainGroups.has(d)) domainGroups.set(d, []);
    domainGroups.get(d)!.push(c);
  }

  // Greedy load‑balancing: assign the biggest domain to the least‑loaded agent
  const sorted = [...domainGroups.entries()].sort((a, b) => b[1].length - a[1].length);
  const effective = Math.min(agentCount, sorted.length);
  const agents: AgentAssignment[] = Array.from({ length: effective }, (_, i) => ({
    agentId: i + 1,
    criteriaIds: [],
    criteriaDetails: []
  }));

  for (const [, group] of sorted) {
    let min = agents[0];
    for (const a of agents) if (a.criteriaIds.length < min.criteriaIds.length) min = a;
    for (const c of group) {
      min.criteriaIds.push(c.id);
      min.criteriaDetails.push(c);
    }
  }
  return agents.filter(a => a.criteriaIds.length);
}

This function guarantees that criteria belonging to the same domain (e.g., all API-related items) stay together on the same agent, minimizing context switching while balancing workload.

Key Files and Implementation References

Summary

  • Agent teams (swarms) enable parallel execution of complex tasks by coordinating multiple autonomous agents around shared criteria and PRDs.
  • Team creation requires the exact trigger phrase "create an agent team" and the experimental environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
  • Workload distribution uses the partitionCriteria function to group failing criteria by domain and balance them across agents using a greedy algorithm.
  • State synchronization occurs through the LoopAlgorithmState JSON structure stored in MEMORY/STATE/algorithms/<session>.json, enabling real-time dashboard monitoring.
  • Lifecycle management follows a four-phase process: lead creation, worker spawning, parallel execution, and result aggregation.

Frequently Asked Questions

What triggers the creation of an agent team in PAI?

An agent team is created only when an agent outputs the exact phrase "create an agent team". This specific trigger phrase activates the experimental TeamCreate tool, which requires the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to be set. Without this exact phrase, the system processes the request as a standard single-agent task.

How does PAI distribute work among parallel agents?

PAI uses the partitionCriteria function defined in Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts to distribute failing criteria across agents. The function groups criteria by their ISC domain (e.g., grouping all API-related items together), then applies a greedy load-balancing algorithm that assigns the largest domain groups to the least-loaded agents. This ensures domain cohesion while maximizing parallel efficiency.

What is the difference between using the -a CLI flag and the TeamCreate tool?

The ‑a <N> CLI flag runs the algorithm in loop mode with multiple parallel agents managed by the core engine, automatically partitioning criteria and managing state through the LoopAlgorithmState object. In contrast, the TeamCreate tool is an experimental, trigger-based mechanism that allows an agent to dynamically spawn a team during execution, requiring the specific phrase "create an agent team" and manual worker spawning via the Task tool with team_name parameters.

How do agents in a swarm communicate and share state?

Agents communicate through a shared state file stored at MEMORY/STATE/algorithms/<session>.json, which contains the LoopAlgorithmState object with parallelAgents, an agents[] array, and phaseHistory. Additionally, agents can use the SendMessage tool to broadcast findings or request assistance by specifying the team_name parameter, enabling real-time coordination while the dashboard reads the JSON state to display per-agent status and overall progress.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →