Architecture

AutoResearch is a hub-and-spoke system. The Orchestrator sits at the center, reading shared state from disk, dispatching tasks to agents, and writing decisions back to disk.

System Topology

graph TB
    subgraph Orchestrator["Orchestrator (Claude Opus)"]
        O[Main Claude Code Session]
    end

    subgraph State["Shared State (.omc/research/)"]
        S1[pipeline.yaml]
        S2[ideas/]
        S3[experiments/]
        S4[papers/]
        S5[reviews/]
    end

    subgraph Agents
        P[Planner<br/>Claude Opus]
        W[Writer<br/>Claude Opus]
        SC[Scout<br/>Gemini]
        C[Coder<br/>Codex]
        J[Judge<br/>Codex]
    end

    O -->|reads/writes| State
    O -->|dispatches| P
    O -->|dispatches| W
    O -->|dispatches| SC
    O -->|dispatches| C
    O -->|dispatches| J

    P -->|writes| State
    W -->|writes| State
    SC -->|writes| State
    C -->|writes| State
    J -->|writes| State

    style Orchestrator fill:#f9f0ff,stroke:#7c3aed
    style State fill:#fef3c7,stroke:#d97706
    style Agents fill:#ecfdf5,stroke:#059669

Hub-and-Spoke, Not Peer-to-Peer

Agents never communicate directly with each other. All coordination flows through the Orchestrator and the shared state on disk. This keeps the system predictable and debuggable.

Agent Roster

Agent	LLM	Invocation	Lifecycle	Role
Orchestrator	Claude Opus	Main session	Persistent	Decision-making, coordination
Planner	Claude Opus	Sub-agent	Per-task	Experiment design, decomposition
Writer	Claude Opus	Clean session	Per-section	Paper writing, LaTeX
Scout	Gemini	Tmux worker	Per-task	Literature search, idea generation
Coder	Codex	Tmux worker	Persistent	Code implementation, debugging
Judge	Codex	codex exec	Stateless	Evaluation, review, verdicts

Invocation types matter

• Sub-agent: Runs inside Claude Code as a spawned sub-agent. Shares some context.
• Tmux worker: Runs in a named tmux session. Persistent, can be monitored.
• codex exec: One-shot stateless execution. No memory between calls. Perfect for independent evaluation.

Cross-LLM Review Principle

A core architectural rule: the model that creates an artifact must not be the sole reviewer of that artifact.

Artifact	Created By	Reviewed By	Why
Research idea	Claude (Orchestrator)	Codex (Judge)	Independent novelty/feasibility check
Experiment code	Codex (Coder)	Claude (Orchestrator)	Design alignment, logic review
Training results	Codex (Coder runs)	Claude + Codex	Cross-check interpretation
Paper draft	Claude (Writer)	Codex + Claude + Gemini	Three-model review panel
Literature survey	Gemini (Scout)	Claude (Orchestrator)	Relevance filtering

This is not optional

Cross-LLM review is an architectural invariant, not a best practice. The omc-orchestrator hook enforces that no agent self-reviews its own output for gate decisions.

Two-Tier Information Architecture

AutoResearch separates information into two tiers:

Tier 1: Context (Working Memory)

• Lives in the LLM's context window
• Fast to access, limited in size
• Ephemeral — lost when a session ends or context fills up
• Contains: current task, recent decisions, active plan

Tier 2: Disk (Long-Term Memory)

• Lives in .omc/research/ on the filesystem
• Unlimited in size, slightly slower to access
• Persistent — survives session restarts, crashes, context resets
• Contains: all plans, results, papers, reviews, pipeline state

graph LR
    subgraph Tier1["Tier 1: Context"]
        T1A[Current task]
        T1B[Recent decisions]
        T1C[Active plan summary]
    end

    subgraph Tier2["Tier 2: Disk"]
        T2A[pipeline.yaml]
        T2B[Full experiment logs]
        T2C[All paper drafts]
        T2D[Complete review history]
    end

    Tier1 -->|"overflow / session end"| Tier2
    Tier2 -->|"session start / context fill"| Tier1

    style Tier1 fill:#dbeafe,stroke:#2563eb
    style Tier2 fill:#fef3c7,stroke:#d97706

The golden rule

Context is cache. Disk is source of truth. Any information that matters must be on disk. Context can always be rebuilt from disk.

Next

• Quick Start — commands and workflows
• Research State — deep dive into .omc/research/
• Context Management — how context overflow is handled