# evermind-ai/raven architecture

> Architecture diagram of the GitHub repository evermind-ai/raven, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evermind-ai/raven
- Repository: https://github.com/evermind-ai/raven

## Overview

Raven is a multi-agent host that accepts a task through local, web, protocol, or channel surfaces, assembles a runtime, delegates work to specialized agents, and returns an integrated result. The main execution path is represented by the engine, agent loop, subagent/DAG machinery, and domain agents. Memory delivery and the separate Evolver are additional layers. The tree and excerpts support the central runtime and several capabilities; some plugin wiring is documented but not directly sampled.

Main entry points: [`raven/agent/subagent/manager.py`](https://github.com/evermind-ai/raven/blob/main/raven/agent/subagent/manager.py) (Subagent Manager), [`raven/agent/loop/main.py`](https://github.com/evermind-ai/raven/blob/main/raven/agent/loop/main.py) (Agent Loop), [`raven/core/engine_stack.py`](https://github.com/evermind-ai/raven/blob/main/raven/core/engine_stack.py) (Engine Assembly), [`plugins-dist/design-engine/raven_design/plugin/hook.py`](https://github.com/evermind-ai/raven/blob/main/plugins-dist/design-engine/raven_design/plugin/hook.py) (Design Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User Surfaces"]
  node_mochat["Mochat Channel<br/>[pipeline.py]"]
  node_tui["Terminal UI"]
  node_web_ui["Web Session UI<br/>[pipeline.ts]"]
  node_acp_server["ACP Server<br/>[server.py]"]
end

subgraph group_runtime["Runtime Orchestration"]
  node_engine["Engine Assembly<br/>[engine_stack.py]"]
  node_agent_loop["Agent Loop<br/>[main.py]"]
  node_subagents["Subagent Manager<br/>[manager.py]"]
  node_dag_runner["DAG Runner<br/>[dag_runner.py]"]
end

subgraph group_agents["Specialized Agents"]
  node_research["Research Agent<br/>[flow.py]"]
  node_code["Code Agent<br/>[flow.py]"]
  node_design["Design Agent<br/>[hook.py]"]
  node_oncall["Oncall Agent<br/>[flow.py]"]
end

subgraph group_capabilities["Persistence And Output"]
  node_memory_delivery["Memory Delivery<br/>[store_pipeline.py]"]
  node_render_pipeline["Render Pipeline<br/>[pipeline.py]"]
  node_ppt_ingest["PPT Ingestion<br/>[pipeline.py]"]
end

subgraph group_evolution["Harness Evolution"]
  node_evolver["Evolver Orchestrator<br/>[loop.py]"]
  node_eval_judge["Evaluation Judge<br/>[llm_client.py]"]
  node_promotion_gates{{"Promotion Gates<br/>[pipeline.py]"}}
end

node_user(("User"))
node_model_provider["Model Provider"]
node_memory_backend[("Memory Backend")]

node_user -->|"enters task"| node_tui
node_user -->|"enters task"| node_web_ui
node_user -->|"sends task"| node_acp_server
node_mochat -->|"delivers messages"| node_engine
node_tui -->|"uses runtime"| node_engine
node_acp_server -->|"serves runtime"| node_engine
node_engine -->|"builds loop"| node_agent_loop
node_agent_loop -->|"delegates work"| node_subagents
node_subagents -->|"runs DAGs"| node_dag_runner
node_subagents -->|"dispatches research"| node_research
node_subagents -->|"dispatches coding"| node_code
node_subagents -->|"dispatches design"| node_design
node_subagents -->|"dispatches automation"| node_oncall
node_design -->|"renders assets"| node_render_pipeline
node_design -.->|"ingests sources"| node_ppt_ingest
node_agent_loop -->|"queues turns"| node_memory_delivery
node_memory_delivery -->|"writes memory"| node_memory_backend
node_agent_loop -->|"returns result"| node_user
node_evolver -->|"evaluates runs"| node_eval_judge
node_eval_judge -->|"calls models"| node_model_provider
node_evolver -->|"seeks promotion"| node_promotion_gates

click node_mochat "https://github.com/evermind-ai/raven/blob/main/raven/channels/adapters/mochat/pipeline.py"
click node_tui "https://github.com/evermind-ai/raven/blob/main/ui-tui/src/app/useInputHandlers.ts"
click node_web_ui "https://github.com/evermind-ai/raven/blob/main/ui-web/src/state/session/pipeline.ts"
click node_acp_server "https://github.com/evermind-ai/raven/blob/main/raven/acp/server.py"
click node_engine "https://github.com/evermind-ai/raven/blob/main/raven/core/engine_stack.py"
click node_agent_loop "https://github.com/evermind-ai/raven/blob/main/raven/agent/loop/main.py"
click node_subagents "https://github.com/evermind-ai/raven/blob/main/raven/agent/subagent/manager.py"
click node_dag_runner "https://github.com/evermind-ai/raven/blob/main/raven/agent/subagent/dag_runner.py"
click node_research "https://github.com/evermind-ai/raven/blob/main/agents/raven-research/plugins/research-flow/research_flow/flow.py"
click node_code "https://github.com/evermind-ai/raven/blob/main/agents/raven-code/plugins/code-flow/code_flow/flow.py"
click node_design "https://github.com/evermind-ai/raven/blob/main/plugins-dist/design-engine/raven_design/plugin/hook.py"
click node_oncall "https://github.com/evermind-ai/raven/blob/main/agents/raven-oncall/plugins/oncall-flow/oncall_flow/flow.py"
click node_memory_delivery "https://github.com/evermind-ai/raven/blob/main/raven/memory_engine/store_pipeline.py"
click node_render_pipeline "https://github.com/evermind-ai/raven/blob/main/plugins-dist/design-engine/raven_design/rendering/pipeline.py"
click node_ppt_ingest "https://github.com/evermind-ai/raven/blob/main/plugins-dist/ppt-engine/raven_ppt/services/ingest/pipeline.py"
click node_evolver "https://github.com/evermind-ai/raven/blob/main/evolver/orchestrator/loop.py"
click node_eval_judge "https://github.com/evermind-ai/raven/blob/main/evolver/judge/llm_client.py"
click node_promotion_gates "https://github.com/evermind-ai/raven/blob/main/evolver/orchestrator/gates/pipeline.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mochat,node_tui,node_web_ui,node_acp_server,node_user toneBlue
class node_engine,node_agent_loop,node_subagents,node_dag_runner,node_memory_backend toneAmber
class node_research,node_code,node_design,node_oncall toneMint
class node_memory_delivery,node_render_pipeline,node_ppt_ingest toneRose
class node_evolver,node_eval_judge,node_promotion_gates,node_model_provider toneIndigo
```

## Components

### User Surfaces

- [Mochat Channel](https://github.com/evermind-ai/raven/blob/main/raven/channels/adapters/mochat/pipeline.py): `raven/channels/adapters/mochat/pipeline.py`
- [Terminal UI](https://github.com/evermind-ai/raven/blob/main/ui-tui/src/app/useInputHandlers.ts): `ui-tui/src/app/useInputHandlers.ts`
- [Web Session UI](https://github.com/evermind-ai/raven/blob/main/ui-web/src/state/session/pipeline.ts): `ui-web/src/state/session/pipeline.ts`
- [ACP Server](https://github.com/evermind-ai/raven/blob/main/raven/acp/server.py): `raven/acp/server.py`

### Runtime Orchestration

- [Engine Assembly](https://github.com/evermind-ai/raven/blob/main/raven/core/engine_stack.py): `raven/core/engine_stack.py`
- [Agent Loop](https://github.com/evermind-ai/raven/blob/main/raven/agent/loop/main.py): `raven/agent/loop/main.py`
- [Subagent Manager](https://github.com/evermind-ai/raven/blob/main/raven/agent/subagent/manager.py): `raven/agent/subagent/manager.py`
- [DAG Runner](https://github.com/evermind-ai/raven/blob/main/raven/agent/subagent/dag_runner.py): `raven/agent/subagent/dag_runner.py`

### Specialized Agents

- [Research Agent](https://github.com/evermind-ai/raven/blob/main/agents/raven-research/plugins/research-flow/research_flow/flow.py): `agents/raven-research/plugins/research-flow/research_flow/flow.py`
- [Code Agent](https://github.com/evermind-ai/raven/blob/main/agents/raven-code/plugins/code-flow/code_flow/flow.py): `agents/raven-code/plugins/code-flow/code_flow/flow.py`
- [Design Agent](https://github.com/evermind-ai/raven/blob/main/plugins-dist/design-engine/raven_design/plugin/hook.py): `plugins-dist/design-engine/raven_design/plugin/hook.py`
- [Oncall Agent](https://github.com/evermind-ai/raven/blob/main/agents/raven-oncall/plugins/oncall-flow/oncall_flow/flow.py): `agents/raven-oncall/plugins/oncall-flow/oncall_flow/flow.py`

### Persistence And Output

- [Memory Delivery](https://github.com/evermind-ai/raven/blob/main/raven/memory_engine/store_pipeline.py): `raven/memory_engine/store_pipeline.py`
- [Render Pipeline](https://github.com/evermind-ai/raven/blob/main/plugins-dist/design-engine/raven_design/rendering/pipeline.py): `plugins-dist/design-engine/raven_design/rendering/pipeline.py`
- [PPT Ingestion](https://github.com/evermind-ai/raven/blob/main/plugins-dist/ppt-engine/raven_ppt/services/ingest/pipeline.py): `plugins-dist/ppt-engine/raven_ppt/services/ingest/pipeline.py`

### Harness Evolution

- [Evolver Orchestrator](https://github.com/evermind-ai/raven/blob/main/evolver/orchestrator/loop.py): `evolver/orchestrator/loop.py`
- [Evaluation Judge](https://github.com/evermind-ai/raven/blob/main/evolver/judge/llm_client.py): `evolver/judge/llm_client.py`
- [Promotion Gates](https://github.com/evermind-ai/raven/blob/main/evolver/orchestrator/gates/pipeline.py): `evolver/orchestrator/gates/pipeline.py`

### Other components

- **User**
- **Model Provider**
- **Memory Backend**

## Connections

- User → Terminal UI: enters task
- User → Web Session UI: enters task
- User → ACP Server: sends task
- Mochat Channel → Engine Assembly: delivers messages
- Terminal UI → Engine Assembly: uses runtime
- ACP Server → Engine Assembly: serves runtime
- Engine Assembly → Agent Loop: builds loop
- Agent Loop → Subagent Manager: delegates work
- Subagent Manager → DAG Runner: runs DAGs
- Subagent Manager → Research Agent: dispatches research
- Subagent Manager → Code Agent: dispatches coding
- Subagent Manager → Design Agent: dispatches design
- Subagent Manager → Oncall Agent: dispatches automation
- Design Agent → Render Pipeline: renders assets
- Design Agent → PPT Ingestion: ingests sources
- Agent Loop → Memory Delivery: queues turns
- Memory Delivery → Memory Backend: writes memory
- Agent Loop → User: returns result
- Evolver Orchestrator → Evaluation Judge: evaluates runs
- Evaluation Judge → Model Provider: calls models
- Evolver Orchestrator → Promotion Gates: seeks promotion