# cristicretu/diri architecture

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

- Interactive diagram: https://gitdiagram.com/cristicretu/diri
- Repository: https://github.com/cristicretu/diri

## Overview

Diri is a native desktop workspace for running and coordinating coding agents across local and SSH-hosted machines, with isolated worktrees, persistent sessions, and in-context review. The main workflow is to launch an agent session, keep its terminal alive independently of the app, monitor its status, and review resulting changes. The README also documents agent-to-agent delegation and a phone companion. The graph emphasizes these product paths; source excerpts reveal holder internals, but most UI, orchestration, and remote wiring is unsampled, so those links are documented or left unverified.

Main entry points: [`diri/crates/diri-engine/src/control.rs`](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/control.rs) (Session control), [`diri/crates/diri-app/src/workspace_workbench.rs`](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/workspace_workbench.rs) (Workspace UI), [`diri/crates/diri-engine/src/holder/server.rs`](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/server.rs) (Session holder), [`diri/crates/diri-app/src/main.rs`](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/main.rs) (Desktop app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop app<br/>[main.rs]"]
  node_workspace_ui["Workspace UI"]
  node_agent_catalog["Agent catalog<br/>[agent_catalog.rs]"]
  node_terminal_view["Terminal pane<br/>[controller.rs]"]
  node_usage["Usage dashboard<br/>[dashboard.rs]"]
end

subgraph group_engine["Session engine"]
  node_engine["Engine daemon<br/>[lib.rs]"]
  node_control["Session control<br/>[control.rs]"]
  node_worktrees["Worktree management<br/>[worktree_scan.rs]"]
  node_agent_process["Agent CLI process<br/>[pty.rs]"]
  node_holder_manager["Holder manager<br/>[manager.rs]"]
  node_holder["Session holder<br/>[server.rs]"]
  node_holder_protocol["Holder protocol<br/>[protocol.rs]"]
  node_output_log[("Output log<br/>[log_feed.rs]")]
end

subgraph group_remote["Remote and phone"]
  node_remote_manager["Remote manager<br/>[manager.rs]"]
  node_web_gateway["Phone web gateway<br/>[api.rs]"]
  node_phone["Diri phone app<br/>[AppModel.swift]"]
end

subgraph group_review["Coordination and review"]
  node_review_ui["Change review<br/>[git_review.rs]"]
  node_notes["Notes and tasks<br/>[doc.rs]"]
  node_mcp["Agent MCP tools<br/>[tasks.rs]"]
end

node_user(("User"))
node_ssh_host(("SSH host"))
node_external_agent(("Agent CLI"))

node_user -->|"opens"| node_desktop_app
node_desktop_app -.->|"presents"| node_workspace_ui
node_workspace_ui -.->|"offers agents"| node_agent_catalog
node_workspace_ui -.->|"requests sessions"| node_control
node_workspace_ui -.->|"assigns worktrees"| node_worktrees
node_control -->|"launches holders"| node_holder_manager
node_holder_manager -->|"hosts sessions"| node_holder
node_holder -->|"owns PTY"| node_agent_process
node_holder -->|"serves requests"| node_holder_protocol
node_holder -.->|"writes output"| node_output_log
node_terminal_view -.->|"attaches session"| node_control
node_terminal_view -.->|"reads output"| node_output_log
node_agent_process -->|"runs CLI"| node_external_agent
node_user -->|"reviews changes"| node_review_ui
node_review_ui -.->|"reviews worktree"| node_worktrees
node_user -->|"plans tasks"| node_notes
node_mcp -.->|"coordinates agents"| node_control
node_control -.->|"manages remote"| node_remote_manager
node_remote_manager -.->|"runs helper"| node_ssh_host
node_user -.->|"monitors remotely"| node_phone
node_phone -->|"calls HTTP API"| node_web_gateway
node_web_gateway -.->|"controls sessions"| node_control
node_desktop_app -.->|"shows usage"| node_usage

click node_desktop_app "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/main.rs"
click node_workspace_ui "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/workspace_workbench.rs"
click node_agent_catalog "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/agent_catalog.rs"
click node_terminal_view "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/terminal_pane/controller.rs"
click node_review_ui "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/git_review.rs"
click node_notes "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-notes/src/doc.rs"
click node_mcp "https://github.com/cristicretu/diri/blob/main/diri/crates/dirijor-mcp/src/bridge/tasks.rs"
click node_engine "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/lib.rs"
click node_control "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/control.rs"
click node_worktrees "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/worktree_scan.rs"
click node_agent_process "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/pty.rs"
click node_holder_manager "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/manager.rs"
click node_holder "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/server.rs"
click node_holder_protocol "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/protocol.rs"
click node_output_log "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/log_feed.rs"
click node_remote_manager "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/remote/manager.rs"
click node_web_gateway "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-web/src/api.rs"
click node_phone "https://github.com/cristicretu/diri/blob/main/ios/DiriPhone/Net/AppModel.swift"
click node_usage "https://github.com/cristicretu/diri/blob/main/diri/crates/diri-usage/src/transcripts/dashboard.rs"

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_desktop_app,node_workspace_ui,node_agent_catalog,node_terminal_view,node_usage,node_user toneBlue
class node_engine,node_control,node_worktrees,node_agent_process,node_holder_manager,node_holder,node_holder_protocol,node_output_log toneAmber
class node_remote_manager,node_web_gateway,node_phone toneMint
class node_review_ui,node_notes,node_mcp toneRose
class node_ssh_host,node_external_agent toneIndigo
```

## Components

### Desktop experience

- [Desktop app](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/main.rs): `diri/crates/diri-app/src/main.rs`
- [Workspace UI](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/workspace_workbench.rs): `diri/crates/diri-app/src/workspace_workbench.rs`
- [Agent catalog](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/agent_catalog.rs): `diri/crates/diri-app/src/agent_catalog.rs`
- [Terminal pane](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/terminal_pane/controller.rs): `diri/crates/diri-app/src/terminal_pane/controller.rs`
- [Usage dashboard](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-usage/src/transcripts/dashboard.rs): `diri/crates/diri-usage/src/transcripts/dashboard.rs`

### Session engine

- [Engine daemon](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/lib.rs): `diri/crates/diri-engine/src/lib.rs`
- [Session control](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/control.rs): `diri/crates/diri-engine/src/control.rs`
- [Worktree management](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/worktree_scan.rs): `diri/crates/diri-engine/src/worktree_scan.rs`
- [Agent CLI process](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/pty.rs): `diri/crates/diri-engine/src/pty.rs`
- [Holder manager](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/manager.rs): `diri/crates/diri-engine/src/holder/manager.rs`
- [Session holder](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/server.rs): `diri/crates/diri-engine/src/holder/server.rs`
- [Holder protocol](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/protocol.rs): `diri/crates/diri-engine/src/holder/protocol.rs`
- [Output log](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/holder/log_feed.rs): `diri/crates/diri-engine/src/holder/log_feed.rs`

### Remote and phone

- [Remote manager](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-engine/src/remote/manager.rs): `diri/crates/diri-engine/src/remote/manager.rs`
- [Phone web gateway](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-web/src/api.rs): `diri/crates/diri-web/src/api.rs`
- [Diri phone app](https://github.com/cristicretu/diri/blob/main/ios/DiriPhone/Net/AppModel.swift): `ios/DiriPhone/Net/AppModel.swift`

### Coordination and review

- [Change review](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-app/src/git_review.rs): `diri/crates/diri-app/src/git_review.rs`
- [Notes and tasks](https://github.com/cristicretu/diri/blob/main/diri/crates/diri-notes/src/doc.rs): `diri/crates/diri-notes/src/doc.rs`
- [Agent MCP tools](https://github.com/cristicretu/diri/blob/main/diri/crates/dirijor-mcp/src/bridge/tasks.rs): `diri/crates/dirijor-mcp/src/bridge/tasks.rs`

### Other components

- **User**
- **SSH host**
- **Agent CLI**

## Connections

- User → Desktop app: opens (evidence: `README.md`)
- Desktop app → Workspace UI: presents
- Workspace UI → Agent catalog: offers agents
- Workspace UI → Session control: requests sessions
- Workspace UI → Worktree management: assigns worktrees (evidence: `README.md`)
- Session control → Holder manager: launches holders
- Holder manager → Session holder: hosts sessions (evidence: `diri/crates/diri-engine/src/holder/manager.rs`)
- Session holder → Agent CLI process: owns PTY (evidence: `diri/crates/diri-engine/src/holder/server.rs`)
- Session holder → Holder protocol: serves requests (evidence: `diri/crates/diri-engine/src/holder/server.rs`)
- Session holder → Output log: writes output (evidence: `diri/crates/diri-engine/src/holder/server.rs`)
- Terminal pane → Session control: attaches session
- Terminal pane → Output log: reads output
- Agent CLI process → Agent CLI: runs CLI (evidence: `README.md`)
- User → Change review: reviews changes (evidence: `README.md`)
- Change review → Worktree management: reviews worktree (evidence: `README.md`)
- User → Notes and tasks: plans tasks (evidence: `README.md`)
- Agent MCP tools → Session control: coordinates agents (evidence: `README.md`)
- Session control → Remote manager: manages remote
- Remote manager → SSH host: runs helper (evidence: `diri/crates/diri-engine/src/remote/manager.rs`)
- User → Diri phone app: monitors remotely (evidence: `README.md`)
- Diri phone app → Phone web gateway: calls HTTP API
- Phone web gateway → Session control: controls sessions
- Desktop app → Usage dashboard: shows usage (evidence: `diri/crates/diri-app/src/main.rs`)
