# dheerax/orchy architecture

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

- Interactive diagram: https://gitdiagram.com/dheerax/orchy
- Repository: https://github.com/dheerax/orchy

## Overview

Orchy is a VS Code extension that lets an external AI assistant propose and manage multi-agent coding runs. The main workflow is MCP tool requests to the extension daemon, plan approval, agent execution in isolated Git worktrees, deliverable verification, and merge; the VS Code panel exposes session, pipeline, and Git-history views. The extension host owns persistent session state, replayed from an append-only event log. Major orchestration internals and UI sources were not excerpted, so their detailed call paths are shown only where documented, or left unverified.

Main entry points: [`src/extension.ts`](https://github.com/dheerax/orchy/blob/main/src/extension.ts) (Extension host), [`src/core/orchestrator.ts`](https://github.com/dheerax/orchy/blob/main/src/core/orchestrator.ts) (Run orchestrator), [`src/daemon/server.ts`](https://github.com/dheerax/orchy/blob/main/src/daemon/server.ts) (HTTP daemon), [`src/core/sessionRegistry.ts`](https://github.com/dheerax/orchy/blob/main/src/core/sessionRegistry.ts) (Session registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_mcp["MCP tools<br/>[orchy-mcp.mjs]"]
  node_extension["Extension host<br/>[extension.ts]"]
  node_daemon["HTTP daemon<br/>[server.ts]"]
end

subgraph group_planning["Planning and policy"]
  node_planner["Plan DAG<br/>[planner.ts]"]
  node_project["Project config<br/>[projectConfig.ts]"]
  node_models["Model policy<br/>[modelPolicy.ts]"]
  node_doctor["Setup checks<br/>[doctor.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.ts]"]
  node_worktrees["Git worktrees<br/>[worktreeManager.ts]"]
  node_backend["OpenCode backend<br/>[opencodeBackend.ts]"]
  node_opencode_client["OpenCode client<br/>[opencodeClient.ts]"]
  node_verifier["Deliverable verifier"]
  node_contracts["Contract checker<br/>[contractChecker.ts]"]
end

subgraph group_state["Session state"]
  node_registry["Session registry<br/>[sessionRegistry.ts]"]
  node_eventlog[("Event log<br/>[eventLog.ts]")]
end

subgraph group_experience["VS Code experience"]
  node_panel["Mission control<br/>[graphPanel.ts]"]
  node_transcript["Transcript view"]
end

node_assistant(("AI assistant"))
node_opencode_service["OpenCode server"]

node_assistant -->|"invokes tools"| node_mcp
node_mcp -->|"forwards HTTP"| node_daemon
node_extension -->|"starts and configures"| node_daemon
node_daemon -->|"dispatches requests"| node_orchestrator
node_daemon -->|"reads sessions"| node_registry
node_daemon -->|"loads config"| node_project
node_daemon -->|"checks plan status"| node_planner
node_extension -->|"wires orchestration"| node_orchestrator
node_extension -->|"checks repository"| node_worktrees
node_extension -->|"runs setup checks"| node_doctor
node_extension -->|"uses verification"| node_verifier
node_extension -->|"uses session state"| node_registry
node_extension -->|"registers panel"| node_panel
node_extension -->|"registers transcript"| node_transcript
node_registry -->|"replays and reads"| node_eventlog
node_orchestrator -.->|"builds and runs plans"| node_planner
node_orchestrator -.->|"creates isolated branches"| node_worktrees
node_orchestrator -.->|"starts agent sessions"| node_backend
node_orchestrator -.->|"verifies deliverables"| node_verifier
node_orchestrator -.->|"checks promises"| node_contracts
node_orchestrator -.->|"updates sessions"| node_registry
node_backend -->|"uses API client"| node_opencode_client
node_opencode_client -.->|"sends API requests"| node_opencode_service
node_backend -->|"applies model policy"| node_models
node_worktrees -.->|"provides isolated directories"| node_opencode_service
node_panel -.->|"renders session state"| node_registry
node_transcript -.->|"reads session records"| node_registry
node_transcript -.->|"loads live transcript"| node_backend

click node_mcp "https://github.com/dheerax/orchy/blob/main/mcp/orchy-mcp.mjs"
click node_extension "https://github.com/dheerax/orchy/blob/main/src/extension.ts"
click node_daemon "https://github.com/dheerax/orchy/blob/main/src/daemon/server.ts"
click node_planner "https://github.com/dheerax/orchy/blob/main/src/core/planner.ts"
click node_project "https://github.com/dheerax/orchy/blob/main/src/core/projectConfig.ts"
click node_models "https://github.com/dheerax/orchy/blob/main/src/core/modelPolicy.ts"
click node_doctor "https://github.com/dheerax/orchy/blob/main/src/core/doctor.ts"
click node_orchestrator "https://github.com/dheerax/orchy/blob/main/src/core/orchestrator.ts"
click node_worktrees "https://github.com/dheerax/orchy/blob/main/src/core/worktreeManager.ts"
click node_backend "https://github.com/dheerax/orchy/blob/main/src/backends/opencodeBackend.ts"
click node_opencode_client "https://github.com/dheerax/orchy/blob/main/src/backends/opencodeClient.ts"
click node_verifier "https://github.com/dheerax/orchy/blob/main/src/core/deliverableVerifier.ts"
click node_contracts "https://github.com/dheerax/orchy/blob/main/src/core/contractChecker.ts"
click node_registry "https://github.com/dheerax/orchy/blob/main/src/core/sessionRegistry.ts"
click node_eventlog "https://github.com/dheerax/orchy/blob/main/src/core/eventLog.ts"
click node_panel "https://github.com/dheerax/orchy/blob/main/src/ui/graphPanel.ts"
click node_transcript "https://github.com/dheerax/orchy/blob/main/src/ui/transcriptDocument.ts"

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_mcp,node_extension,node_daemon toneBlue
class node_planner,node_project,node_models,node_doctor toneAmber
class node_orchestrator,node_worktrees,node_backend,node_opencode_client,node_verifier,node_contracts,node_opencode_service toneMint
class node_registry,node_eventlog toneRose
class node_panel,node_transcript,node_assistant toneIndigo
```

## Components

### Entry points

- [MCP tools](https://github.com/dheerax/orchy/blob/main/mcp/orchy-mcp.mjs): `mcp/orchy-mcp.mjs`
- [Extension host](https://github.com/dheerax/orchy/blob/main/src/extension.ts): `src/extension.ts`
- [HTTP daemon](https://github.com/dheerax/orchy/blob/main/src/daemon/server.ts): `src/daemon/server.ts`

### Planning and policy

- [Plan DAG](https://github.com/dheerax/orchy/blob/main/src/core/planner.ts): `src/core/planner.ts`
- [Project config](https://github.com/dheerax/orchy/blob/main/src/core/projectConfig.ts): `src/core/projectConfig.ts`
- [Model policy](https://github.com/dheerax/orchy/blob/main/src/core/modelPolicy.ts): `src/core/modelPolicy.ts`
- [Setup checks](https://github.com/dheerax/orchy/blob/main/src/core/doctor.ts): `src/core/doctor.ts`

### Agent runtime

- [Run orchestrator](https://github.com/dheerax/orchy/blob/main/src/core/orchestrator.ts): `src/core/orchestrator.ts`
- [Git worktrees](https://github.com/dheerax/orchy/blob/main/src/core/worktreeManager.ts): `src/core/worktreeManager.ts`
- [OpenCode backend](https://github.com/dheerax/orchy/blob/main/src/backends/opencodeBackend.ts): `src/backends/opencodeBackend.ts`
- [OpenCode client](https://github.com/dheerax/orchy/blob/main/src/backends/opencodeClient.ts): `src/backends/opencodeClient.ts`
- [Deliverable verifier](https://github.com/dheerax/orchy/blob/main/src/core/deliverableVerifier.ts): `src/core/deliverableVerifier.ts`
- [Contract checker](https://github.com/dheerax/orchy/blob/main/src/core/contractChecker.ts): `src/core/contractChecker.ts`

### Session state

- [Session registry](https://github.com/dheerax/orchy/blob/main/src/core/sessionRegistry.ts): `src/core/sessionRegistry.ts`
- [Event log](https://github.com/dheerax/orchy/blob/main/src/core/eventLog.ts): `src/core/eventLog.ts`

### VS Code experience

- [Mission control](https://github.com/dheerax/orchy/blob/main/src/ui/graphPanel.ts): `src/ui/graphPanel.ts`
- [Transcript view](https://github.com/dheerax/orchy/blob/main/src/ui/transcriptDocument.ts): `src/ui/transcriptDocument.ts`

### Other components

- **AI assistant**
- **OpenCode server**

## Connections

- AI assistant → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → HTTP daemon: forwards HTTP (evidence: `README.md`)
- Extension host → HTTP daemon: starts and configures (evidence: `src/extension.ts`)
- HTTP daemon → Run orchestrator: dispatches requests (evidence: `src/daemon/server.ts`)
- HTTP daemon → Session registry: reads sessions (evidence: `src/daemon/server.ts`)
- HTTP daemon → Project config: loads config (evidence: `src/daemon/server.ts`)
- HTTP daemon → Plan DAG: checks plan status (evidence: `src/daemon/server.ts`)
- Extension host → Run orchestrator: wires orchestration (evidence: `src/extension.ts`)
- Extension host → Git worktrees: checks repository (evidence: `src/extension.ts`)
- Extension host → Setup checks: runs setup checks (evidence: `src/extension.ts`)
- Extension host → Deliverable verifier: uses verification (evidence: `src/extension.ts`)
- Extension host → Session registry: uses session state (evidence: `src/extension.ts`)
- Extension host → Mission control: registers panel (evidence: `src/extension.ts`)
- Extension host → Transcript view: registers transcript (evidence: `src/extension.ts`)
- Session registry → Event log: replays and reads (evidence: `src/core/sessionRegistry.ts`)
- Run orchestrator → Plan DAG: builds and runs plans
- Run orchestrator → Git worktrees: creates isolated branches
- Run orchestrator → OpenCode backend: starts agent sessions
- Run orchestrator → Deliverable verifier: verifies deliverables
- Run orchestrator → Contract checker: checks promises
- Run orchestrator → Session registry: updates sessions
- OpenCode backend → OpenCode client: uses API client (evidence: `src/backends/opencodeBackend.ts`)
- OpenCode client → OpenCode server: sends API requests
- OpenCode backend → Model policy: applies model policy (evidence: `src/backends/opencodeBackend.ts`)
- Git worktrees → OpenCode server: provides isolated directories
- Mission control → Session registry: renders session state
- Transcript view → Session registry: reads session records
- Transcript view → OpenCode backend: loads live transcript
