Teams

Teams let multiple agents work together on a shared project. A team has a lead agent that coordinates work, member agents that execute tasks, shared inboxes for communication, and a task board for tracking progress.

Core Concepts

Quick Start

From the TUI, create a team and assign work:

/team 3 Build a REST API with auth, database, and tests

This spawns 3 agents and distributes the work across them.

Agent Lifecycle

Spawning

spawn_agent(agent_type: "worker", message: "Implement the auth middleware")

Each spawned agent has a status that progresses through:

pending_init → running → completed (or errored / shutdown)

Managing Agents

Limits

Concurrency is controlled by config:

[agent.agents]
max_threads = 4   # max simultaneous agents
max_depth = 2     # max nesting (agent spawning agent)

Exceeding either limit returns an explicit error.

Roles

Agents are assigned roles that determine their capabilities. Roles come from three sources (checked in order):

1. Built-in roles — shipped with Nyzhi
2. Config roles — defined in [agent.agents.roles]
3. File roles — stored in .nyzhi/agents/*.md (or .claude/agents/*.md)

Built-in Roles

Custom Roles

Define custom roles in your config:

[agent.agents.roles.frontend-specialist]
description = "Expert in React and CSS"
system_prompt = "You are a frontend specialist. Focus on component design, accessibility, and performance."
model = "anthropic/claude-sonnet-4-20250514"
max_steps = 50
allowed_tools = ["read", "write", "edit", "grep", "glob", "bash", "git_status", "git_diff"]

Or create a file at .nyzhi/agents/frontend-specialist.md:

# Frontend Specialist

You are a frontend development expert. Focus on:
- Component architecture
- Accessibility (WCAG 2.1 AA)
- Performance optimization
- Responsive design

Team Configuration

Creating a Team

From the TUI:

/team 3 Implement the payment system

Or programmatically via the team_create tool.

Team Storage

Team data lives under ~/.nyzhi/:

Team Config Schema

{
  "name": "payment-team",
  "members": [
    {
      "name": "lead",
      "agentType": "planner",
      "color": "copper"
    },
    {
      "name": "worker-1",
      "agentType": "worker",
      "model": "deepseek/deepseek-chat"
    }
  ],
  "default_model": "anthropic/claude-sonnet-4-20250514",
  "default_role": "worker",
  "max_steps": 100
}

Communication

Messaging

Agents communicate through typed inboxes:

send_team_message(to: "worker-1", message: "Auth middleware is done. Start on the API routes.")

Broadcast to all members:

send_team_message(to: "*", message: "Database schema is finalized.")

Reading Messages

read_inbox()

Returns unread messages for the calling agent.

Task Board

Teams share a structured task board:

task_create(title: "Implement /api/payments endpoint", assigned_to: "worker-1")
task_update(task_id: "...", status: "in_progress")
task_list()

TUI Slash Commands

CLI Team Commands

# List all teams
nyz teams list

# Show team details
nyz teams show payment-team

# Delete a team and all its artifacts
nyz teams delete payment-team

Pass --team-name to set team context for run/exec:

nyz run --team-name payment-team "Check the status of all tasks"

Hook Integration

Team-specific events you can hook into:

• teammate_idle — fires when a teammate finishes and has no pending work
• task_completed — fires when a task status changes to complete

See Hooks for details.

Next Steps

• Autopilot — automated multi-phase workflows
• Tools — team tool reference
• Hooks — event-driven automation