Sub-agents

Parallel AI agents that investigate and plan independently, then report back to the main agent.

When the main AI agent encounters a task that benefits from parallel investigation, it can spawn sub-agents to work on separate threads simultaneously. Sub-agents run independently and report their findings back, allowing the main agent to synthesize results and proceed with better information.

What Sub-agents Do

Omnilib supports two types of sub-agents:

Explore Sub-agents

Explore sub-agents investigate specific questions across files, code paths, or data. The main agent spawns multiple Explore agents when a task requires understanding several parts of a project at once — for example, tracing how a value flows through different modules, or finding all places a pattern appears across a large codebase.

Each Explore agent reads files, runs semantic searches, and follows references within its assigned scope. When finished, it returns a structured summary to the main agent.

Example scenario: You ask the AI to "refactor how authentication is handled." Rather than reading files sequentially, the main agent spawns Explore sub-agents to simultaneously investigate the API layer, the frontend auth components, the session storage logic, and the test suite. Each sub-agent reports back, and the main agent uses all four summaries to build a complete refactoring plan.

Plan Sub-agents

Plan sub-agents design implementation approaches for specific parts of a larger task. The main agent spawns a Plan sub-agent when it needs to think through a sub-problem deeply before committing to an approach — without blocking the rest of the task.

Plan sub-agents do not execute changes. They produce a structured plan that the main agent reviews and either adopts, modifies, or discards.

Viewing Sub-agent Activity

Sub-agents appear in the chat timeline as spawn badges. Each badge shows:

  • The sub-agent type (Explore or Plan)
  • A brief description of the assigned task
  • A live spinner while the sub-agent is running
  • A checkmark when the sub-agent completes

Click a completed badge to expand it and read the sub-agent's full report — the files it examined, the findings it reached, or the plan it produced.

When Sub-agents Are Used

The main agent decides autonomously when to spawn sub-agents based on task complexity. You do not need to request sub-agents explicitly. They appear when the agent determines that parallel investigation will produce a better result faster than sequential investigation.

Sub-agents are most common in Agent mode and Plan mode when:

  • The task requires understanding multiple independent code paths
  • The codebase is large and the relevant files are spread across many directories
  • A complex feature needs multiple design approaches evaluated in parallel
  • The agent needs to gather context from many sources before it can act

Related

  • AI Modes — Agent and Plan mode, where sub-agents appear most
  • AI Chat — The chat timeline where sub-agent badges appear
  • Floating Assistant — Sub-agents also run in the floating assistant
  • Project Memory — Sub-agent findings can update project memory