> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Recursive Teams: Agents That Spawn Agents > Each agent is a full agent, not a subagent. Any agent can spawn its own team. The tree grows without limit. # 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 ```json theme={null} { "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. ```bash theme={null} # 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. ```json theme={null} { "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. ## Related Recursive teams extend naturally across machines — each level can target different hardware. See [Machine-Level Expansion](/openclis/specs/connector-json/machine-expansion). For how recursive depth combines with agent count, direction, and machines as independent scaling dimensions, see [Dimensional Growth](/openclis/specs/connector-json/dimensional-growth).