Feature: Agent team / swarm support with per-agent session visibility

[mellanon]

Summary

Claude Code's agent teams (swarms) allow an orchestrator to spawn multiple worker agents that coordinate via shared task lists and message passing. In a terminal, users see this via tmux split panes — each agent in its own pane. Maestro is uniquely positioned to provide native multi-pane agent team visibility, where each team member appears as a separate linked session with real-time output, while the orchestrator session shows coordination state.

This is a companion to #429 (TaskList integration) — agent teams rely heavily on shared task lists for coordination, and the two features are most powerful together.

Background: How Claude Code Agent Teams Work

Note: Agent teams are currently experimental, requiring CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. The architecture may evolve, but the core patterns are stable enough that Anthropic used them internally for a 16-agent C compiler project (~100K lines of Rust, 2B input tokens).

Architecture

A team consists of a lead (orchestrator) and teammates (workers), each running as independent Claude Code instances with their own context window:

Team Lead (orchestrator session)
├── Teammate "frontend" (independent claude-code process)
├── Teammate "backend" (independent claude-code process)  
├── Teammate "tests" (independent claude-code process)
└── Shared coordination layer:
    ├── ~/.claude/teams/{team-name}/config.json   (member registry)
    ├── ~/.claude/teams/{team-name}/messages/      (per-agent inbox)
    └── ~/.claude/tasks/{team-name}/*.json         (shared task list)

Team config structure (config.json):

{
  "members": [
    { "name": "qa-pages", "agentId": "abc-123", "agentType": "general-purpose" },
    { "name": "qa-posts", "agentId": "def-456", "agentType": "general-purpose" }
  ]
}

Environment variables set per agent: CLAUDE_CODE_TEAM_NAME, CLAUDE_CODE_AGENT_ID, CLAUDE_CODE_AGENT_TYPE

Coordination Protocol

Mechanism	How It Works
Task list	JSON files at ~/.claude/tasks/{team-name}/. Agents claim tasks via TaskUpdate with file locking to prevent races. Tasks have dependency chains (blockedBy). States: pending → in_progress → completed.
Messaging	SendMessage with types: message (1:1), broadcast (all), shutdown_request/response, plan_approval_response. Messages delivered via per-agent inbox directories, injected as conversation turns.
Lifecycle	Lead spawns teammates via Task tool with team_name param. Teammates go idle between turns (normal — idle ≠ done). Lead sends shutdown_request when done. TeamDelete cleans up both team and task directories.

Agent Lifecycle

Lead spawns teammate (Task tool + team_name)
    → Teammate active (working on claimed tasks)
    → Teammate idle (waiting for input — normal between turns)
    → Teammate receives message (wakes up, resumes)
    → Lead sends shutdown_request
    → Teammate sends shutdown_response (approve/reject)
    → Teammate process terminates
    → Lead calls TeamDelete (cleanup)

Terminal Display Today

Claude Code offers two display modes:

• In-process (default): All teammates inside main terminal. Cycle with Shift+Down. Enter to view, Escape to interrupt.
• Split panes (tmux/iTerm2): Each teammate gets its own pane. Click to interact.

Neither mode provides the kind of rich, structured visibility a GUI application could offer.

Current Maestro Infrastructure

Maestro already has building blocks relevant to agent team support:

Existing Feature	Relevance
ProcessManager	Spawns and tracks multiple independent sessions
Session groups	UI-level grouping with collapse/expand — extensible for team grouping
Parent-child sessions	Worktree sessions already have parentSessionId linking
Group Chat	GroupChatParticipant model with sessionId, agentSessionId, activity tracking
Agent detection	Multi-agent support (claude-code, codex, opencode) with per-agent capabilities
SSH remote	Sessions can execute on remote hosts — distributed teams possible
Output parsers	Per-session JSONL parsing including tool execution events

Key gaps: No team detection, no cross-session task dispatch, no team-level state machine, no worker output aggregation.

Inspiration

The approach is partly inspired by PAI (Personal AI Infrastructure) by Daniel Miessler, which extends Claude Code into a full personal AI operating system with skills, hooks, memory, and structured execution. PAI's Algorithm already orchestrates agent teams on top of Claude Code's experimental teams feature — decomposing work into parallel tracks, assigning typed workers (Engineer, Architect, QATester), and tracking progress via shared task lists and PRD files. Seeing this in action via tmux panes demonstrates both the power and the UX limitations that Maestro could address with a native GUI.

Proposal

Phase 1: Team Detection and Session Linking

When Maestro detects an agent team is active (by monitoring ~/.claude/teams/ for new directories, or detecting TeamCreate tool use in the orchestrator's output stream):

• Auto-create linked sessions — Each teammate spawned by the lead appears as a new Maestro session, automatically grouped under the orchestrator
• Visual grouping — Team sessions displayed as an expandable group in the Left Bar, with the orchestrator at the top and workers indented below
• Session badges — Each team member session shows its role (lead/worker), agent type (from config.json), and current state (active/idle/shutdown)
• Individual output — Click any team member to see their full terminal output, just like any other Maestro session

Detection approach: Poll ~/.claude/teams/ for new directories, or intercept TeamCreate tool_use events in the orchestrator's JSONL output stream. Read config.json to discover member names and types.

Phase 2: Team Coordination Dashboard

• Shared task list overlay — Read ~/.claude/tasks/{team-name}/*.json to show the team's task list with ownership badges, dependency chains, and real-time progress (builds on Feature: Native TaskList panel for Claude Code task tracking and agent team coordination #429)
• Message flow — Surface messages between team members (read from ~/.claude/teams/{team-name}/messages/ inbox directories)
• Lifecycle tracking — Show agent lifecycle states: spawning → active → idle → shutdown. Highlight when a worker is stuck or has errored
• Orchestrator view — When viewing the lead session, show a compact team status bar: N workers | M/P tasks complete | 2 idle. Expandable to see individual worker states.

Phase 3: Native Team Orchestration (Future)

• Maestro-initiated teams — Rather than relying on Claude Code's internal team spawning, Maestro could orchestrate teams natively
• Cross-agent type teams — Mix Claude Code, Codex, and OpenCode agents in a single team
• Resource management — Context window tracking across all team members, cost estimation
• Remote distribution — Leverage existing SSH support to distribute team members across machines

Data Model

AgentTeam {
  id: string
  name: string
  leadSessionId: string
  workerSessions: WorkerSession[]
  taskListPath: string            // ~/.claude/tasks/{team-name}/
  teamConfigPath: string          // ~/.claude/teams/{team-name}/config.json
  status: 'active' | 'completing' | 'shutdown'
  created: timestamp
}

WorkerSession extends Session {
  teamId: string
  teamRole: 'lead' | 'worker'
  workerName: string              // From config.json members array
  agentType: string               // From config.json agentType field
  assignedTasks: string[]         // Currently claimed task IDs
  state: 'spawning' | 'active' | 'idle' | 'shutdown'
}

UX: Inline with Orchestrator, Expandable to Workers

Following the same principle from #429 — team state sits with the agent, not in a separate panel:

• Orchestrator view: Compact team status bar showing worker count, task progress, idle count. Expandable to see individual worker states.
• Worker view: Shows assigned tasks, link back to orchestrator, peer worker list.
• Click-to-jump: From the status bar, click any worker to jump to their session. From a worker, click the orchestrator badge to jump back.
• Auto-group: When a team is created, Maestro auto-creates a session group. When the team shuts down, the group can be collapsed/archived.

Why This Matters

Agent teams are the natural evolution of AI-assisted development — from single-agent sessions to coordinated swarms. Today, monitoring a team requires either cycling through in-process sessions (Shift+Down) or watching tmux panes. Maestro's multi-session GUI is the ideal substrate for team visibility:

• See all agents at once without tmux complexity
• Track coordination (tasks, messages, dependencies) with a real UI
• Debug stuck agents by clicking directly to their output
• Watch the orchestration unfold — who's doing what, what's blocked, what's done

Combined with #429 (TaskList), this gives Maestro a complete multi-agent orchestration visibility layer.

Related

• Feature: Native TaskList panel for Claude Code task tracking and agent team coordination #429 — Native TaskList integration for Claude Code task tracking and agent team coordination
• Integrate Claude Agent SDK for mid-turn interaction, graceful abort, and structured streaming #340 — Claude Agent SDK integration (would provide typed access to team events)
• Live view of agent thoughts + actions during autoruns #292 — Better AI agent state/activity visualization

References

• Claude Code Agent Teams — Official Docs
• Building a C Compiler with Agent Teams — Anthropic Engineering
• PAI (Personal AI Infrastructure) — Daniel Miessler — Open-source framework extending Claude Code; inspiration for team orchestration patterns
• The Algorithm — Daniel Miessler — Execution engine demonstrating agent team decomposition in practice
• From Tasks to Swarms — alexop.dev
• Claude Code's Hidden Multi-Agent System — paddo.dev
• Claude Code Swarms — Addy Osmani

[pedramamini]

I'm not sure how much visibility we have into the agent teams to accomplish viewports from Maestro. It's also going to be extremely specific to the single provider. I will say that I have tested agent teams, and they do seem to be working, although they're quirky in the sense that you might make a request and get a response back from the provider, and then you get to basically follow up on your own. I'm also not 100% sure if they're actually being spawned as agent teams or if they're really being spawned as sub-agents.