Skip to main content

​
Recursive Teams: Agents That Spawn Agents

In connector.json, every worker is a full agent — not a subagent. Any agent can spawn its own team, which can spawn more teams. The tree has no depth limit.

​
Subagent vs Agent

Subagent (how others do it):
  Parent owns the child.
  Child has limited tools.
  Child cannot spawn its own children.
  Depth: typically 1-2 levels.

Agent (connector.json):
  Every worker is a full terminal session.
  Full tool access. Full context window.
  Can run its own connector.json inside.
  Depth: unlimited.
The difference is architectural. A subagent is a function call inside the parent’s process. A connector.json agent is a separate PTY session — independent, full-featured, capable of everything the parent can do.

​
How Recursive Spawning Works

Main Session (you)
  ↓ niia run project.connector.json
  ├── Agent: "architect" (Opus)
  │     ↓ reads codebase, decides to split into frontend + backend
  │     ↓ niia run frontend.connector.json  ← spawns its own team
  │     ├── Agent: "react-dev" (Sonnet)
  │     ├── Agent: "css-expert" (Haiku)
  │     └── Agent: "test-writer" (Haiku)
  │
  ├── Agent: "backend-lead" (Opus)
  │     ↓ niia run backend.connector.json  ← spawns its own team
  │     ├── Agent: "api-dev" (Sonnet)
  │     ├── Agent: "db-migration" (Codex)
  │     │     ↓ niia run migration.connector.json  ← goes deeper
  │     │     ├── Agent: "schema-design" (Haiku)
  │     │     └── Agent: "data-backfill" (Haiku)
  │     └── Agent: "security-review" (Codex)
  │
  └── Agent: "qa-lead" (Gemini)
        ↓ waits for architect + backend to finish
        ↓ niia run qa.connector.json
        ├── Agent: "e2e-tester" (Sonnet)
        ├── Agent: "load-tester" (Haiku)
        └── Agent: "accessibility" (Gemini)
4 levels deep. 14 agents total. 5 different LLMs. Each agent is a real PTY session. Each can spawn more.

​
The Spec

{
  "connector": "2.0",
  "name": "full-project",

  "pipeline": {
    "phases": [
      {
        "name": "plan",
        "model": "opus",
        "prompt": "Analyze the project. Break it into frontend and backend workstreams. For each, create a connector.json and run it with 'niia run'.",
        "capabilities": {
          "can_spawn_teams": true,
          "connector_templates": ["frontend.json", "backend.json", "qa.json"]
        }
      }
    ]
  }
}
The agent itself decides how to decompose the work. It writes its own connector.json files. It runs them. The main session doesn’t need to know the full tree upfront.

​
Main Session Observability

The main session (you) can see and control the entire tree. 
# See all active sessions across all levels
niia serve --list
  Session 1: architect (Opus)        → running
  Session 2: react-dev (Sonnet)      → running  [spawned by: architect]
  Session 3: css-expert (Haiku)      → idle     [spawned by: architect]
  Session 4: backend-lead (Opus)     → running
  Session 5: api-dev (Sonnet)        → running  [spawned by: backend-lead]
  Session 6: db-migration (Codex)    → running  [spawned by: backend-lead]
  Session 7: schema-design (Haiku)   → done     [spawned by: db-migration]
  ...

# Read any agent's output, at any depth
niia get-answer --session 7 "schema"

# Send message to any agent, at any depth
niia write --session 6 $'pause the migration, schema changed\r'

# Stop an entire subtree
niia stop --session 4 --recursive    # stops backend-lead + all its children
You see everything. You can intervene anywhere. But you don’t have to — the agents manage their own sub-teams.

​
Scratchpad Hierarchy

Each team level has its own scratchpad. Parent can read child scratchpads. 
scratchpad/                          ← main level
├── architect-findings.md
├── frontend/                        ← architect's sub-team
│   ├── react-components.md
│   ├── css-tokens.md
│   └── test-results.md
├── backend/                         ← backend-lead's sub-team
│   ├── api-design.md
│   ├── migration/                   ← db-migration's sub-team
│   │   ├── schema.sql
│   │   └── backfill-status.md
│   └── security-report.md
└── qa/                              ← qa-lead's sub-team
    ├── e2e-results.md
    └── load-test-metrics.md
Information flows up naturally. Each agent writes to its level. Parent agents read child scratchpads for synthesis.

​
Why This Is Different

​
Claude Code Teams

Leader spawns teammates. Teammates cannot spawn more teammates. Flat hierarchy. One level deep.

​
Codex Plugin

One subprocess call. No spawning at all.

​
connector.json

Any agent can be a leader. Any leader can have a team. Trees, not lists. Depth is unlimited. 
Claude Teams:      Leader → [Worker, Worker, Worker]
                   1 level. Fixed.

connector.json:    Agent → [Agent → [Agent → [Agent...]]]
                   N levels. Dynamic.
                   Each agent decides its own decomposition.

​
The Compound Effect

Level 0: 1 agent (you + main session)
Level 1: 3 agents (architect, backend, qa)
Level 2: 8 agents (sub-teams)
Level 3: 4 agents (sub-sub-teams)
Total:   16 agents working simultaneously

Cost:    Level 2-3 uses cheap models (Haiku)
         Level 0-1 uses expensive models (Opus)
         Average cost per agent is low
         Total throughput is massive
One connector.json at the top. 16 agents across 4 levels. 5 different LLMs. Automatic cost optimization. All managed by the same daemon infrastructure. This isn’t orchestration. This is an AI organization.

​
Safety

Recursive spawning is powerful. Safeguards are essential. 
{
  "limits": {
    "max_depth": 4,
    "max_total_agents": 20,
    "max_cost_usd": 50,
    "timeout_per_agent_ms": 1800000
  }
}
  • max_depth: how deep the tree can go
  • max_total_agents: total across all levels
  • max_cost_usd: spending cap for the entire tree
  • timeout_per_agent_ms: no single agent runs forever
The daemon enforces these. Agents can’t override their own limits. Note: capabilities and limits are planned fields not yet in the core spec. They represent the governance layer for recursive execution. Recursive teams extend naturally across machines — each level can target different hardware. See Machine-Level Expansion. For how recursive depth combines with agent count, direction, and machines as independent scaling dimensions, see Dimensional Growth.