> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent System

> A hierarchical agent team with cross-model peer review, reasoning-based routing, and full visibility into agent communication.

# Multi-Agent System

Hubify Labs runs a **hierarchical multi-agent system** designed to mirror the structure of a real research group. The system is built on three principles: hierarchy for efficiency, cross-model review for accuracy, and full transparency for trust.

## Architecture

```
                  ┌──────────────┐
                  │   Captain    │  ← You
                  │  (Human)     │
                  └──────┬───────┘
                         │
                  ┌──────▼───────┐
                  │ Orchestrator │  ← Claude Opus 4.8
                  │  (Router)    │
                  └──┬───┬───┬───┘
            ┌────────┘   │   └────────┐
     ┌──────▼──────┐ ┌──▼────┐ ┌─────▼──────┐
     │Research Lead│ │Paper  │ │Compute Lead│
     │ (Opus 4.8) │ │Lead   │ │ (Haiku 4.5)│
     └──┬────┬────┘ └──┬────┘ └─────┬──────┘
        │    │         │             │
     Workers Workers  Workers     Workers
     (Haiku) (Haiku)  (Haiku)     (Haiku)
```

## Reasoning-Based Routing

Every task has a reasoning requirement. The orchestrator routes accordingly:

<Tabs>
  <Tab title="High Reasoning">
    **Models:** Claude Opus 4.8, GPT-5.5, Gemini 3.1 Pro, Grok 4

    **Tasks:** Research strategy, paper drafting, peer review, novel scientific analysis, hypothesis generation, cross-survey interpretation.

    **Handled by:** Orchestrator or Lead agents.
  </Tab>

  <Tab title="Medium Reasoning">
    **Models:** Claude Sonnet 5, GPT-5.5 Mini, Gemini 3.1 Flash

    **Tasks:** Data analysis, code generation, experiment configuration, statistical testing, literature summarization.

    **Handled by:** Lead agents or senior Workers.
  </Tab>

  <Tab title="Low Reasoning">
    **Models:** Claude Haiku 4.5

    **Tasks:** Data formatting, file management, wiki updates, figure export, LaTeX compilation, log parsing.

    **Handled by:** Worker agents.
  </Tab>
</Tabs>

## Cross-Model Peer Review

<Warning>
  Every significant output is reviewed by models from at least two different providers. Same-provider review is not permitted.
</Warning>

The review matrix uses five providers across five labs:

| Output from     | Reviewed by                                         |
| --------------- | --------------------------------------------------- |
| Claude Opus 4.8 | GPT-5.5, Gemini 3.1 Pro, Grok 4, Sonar Pro          |
| GPT-5.5         | Claude Opus 4.8, Gemini 3.1 Pro, Grok 4, Sonar Pro  |
| Gemini 3.1 Pro  | Claude Opus 4.8, GPT-5.5, Grok 4, Sonar Pro         |
| Grok 4          | Claude Opus 4.8, GPT-5.5, Gemini 3.1 Pro, Sonar Pro |

Reviews check for:

* Factual accuracy and hallucination detection
* Logical consistency with prior results
* Mathematical and statistical correctness
* Missing citations or prior work
* Overstatements and unsupported claims

## Activity Feed

All agent communication is visible in the **Activity Feed**, a real-time, color-coded stream:

```
[10:42] [done] Research Lead completed EXP-054 (MCMC base chain)
[10:43] [info] Orchestrator -> Paper Lead: "Integrate EXP-054 results into Section 4"
[10:44] [info] Paper Lead -> Draft Worker: "Update posterior table with new chain means"
[10:45] [warn] QC Worker flagged EXP-055: convergence R-hat = 1.08 (threshold: 1.05)
[10:46] [crit] Research Lead escalated: "EXP-055 needs longer chains. Request H200 pod."
```

## Tilldone Pattern

When a worker fails a task, the lead agent **takes over** rather than just reporting the failure:

1. Worker attempts the task
2. Worker fails (error, bad output, QC failure)
3. Lead agent receives the failure with full context
4. Lead agent executes the task itself using higher reasoning
5. If the lead also fails, it escalates to the orchestrator

This pattern ensures tasks complete without constant human intervention.

## Adding Agents

```bash theme={null}
# Add a specialized lead
hubify agent add --role lead --name "Cosmology Lead" --model claude-opus \
  --specialty "MCMC analysis, CMB power spectra, dark energy constraints"

# Add workers
hubify agent add --role worker --name "Figure Generator" --model claude-haiku
hubify agent add --role worker --name "Data Processor" --model claude-haiku

# View the full roster
hubify agent list --tree
```

## Agent Metrics

Each agent tracks:

* Tasks completed vs failed
* Average task duration
* QC pass rate
* Review acceptance rate
* Cost per task