# dirac-run/dirac architecture

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

- Interactive diagram: https://gitdiagram.com/dirac-run/dirac
- Repository: https://github.com/dirac-run/dirac

## Overview

Dirac is a multi-interface AI coding agent for long-running engineering tasks. Users submit or steer a task through VS Code, the CLI, or an ACP client; task orchestration uses configured model providers and codebase context/tools to produce changes that users can review. The README also documents goal-driven work, subagents, structural inspection and editing, permissions, hooks, and repository guidance. The graph preserves those product branches using paths visible in the tree; sampled excerpts do not establish every runtime call, so uncertain wiring is omitted.

Main entry points: [`src/core/controller/task/TaskController.ts`](https://github.com/dirac-run/dirac/blob/master/src/core/controller/task/TaskController.ts) (Task control), [`cli/src/agent/DiracAgent.ts`](https://github.com/dirac-run/dirac/blob/master/cli/src/agent/DiracAgent.ts) (Agent runtime), [`src/integrations/editor/CommentReviewController.ts`](https://github.com/dirac-run/dirac/blob/master/src/integrations/editor/CommentReviewController.ts) (Review interface), [`src/core/goal`](https://github.com/dirac-run/dirac/tree/master/src/core/goal) (Goal runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_vscode["VS Code"]
  node_cli["Terminal CLI"]
  node_acp["ACP client"]
end

subgraph group_execution["Task execution"]
  node_task_controller["Task control<br/>[TaskController.ts]"]
  node_agent["Agent runtime<br/>[DiracAgent.ts]"]
  node_provider_selection["Provider selection"]
  node_model_api["Model adapters"]
end

subgraph group_engineering["Codebase work"]
  node_context["Context management"]
  node_code_tools["Code tools"]
  node_permissions["Permission controls"]
  node_hooks["Hooks"]
end

subgraph group_goals["Long-running work"]
  node_goals_runtime["Goal runtime"]
  node_goal_control["Goal controls"]
end

subgraph group_persistence["State and review"]
  node_storage_context["Storage context<br/>[storage-context.ts]"]
  node_task_storage[("Task records<br/>[taskStorage.ts]")]
  node_checkpoints["Checkpoints"]
  node_review_contract["Review interface"]
  node_vscode_review["VS Code review"]
  node_cli_review["CLI review"]
end

node_developer(("Engineer"))
node_model_service(("Model services"))

node_developer -->|"submits tasks"| node_vscode
node_developer -->|"submits tasks"| node_cli
node_developer -->|"submits tasks"| node_acp
node_vscode -->|"task requests"| node_task_controller
node_cli -->|"task requests"| node_task_controller
node_acp -->|"task requests"| node_task_controller
node_task_controller -->|"runs tasks"| node_agent
node_agent -->|"selects provider"| node_provider_selection
node_provider_selection -->|"configures adapter"| node_model_api
node_model_api -->|"sends requests"| node_model_service
node_agent -->|"assembles context"| node_context
node_agent -->|"uses tools"| node_code_tools
node_agent -->|"checks actions"| node_permissions
node_agent -->|"runs hooks"| node_hooks
node_task_controller -->|"persists task data"| node_task_storage
node_storage_context -->|"provides storage"| node_task_storage
node_task_controller -->|"manages checkpoints"| node_checkpoints
node_agent -->|"reports review comments"| node_review_contract
node_review_contract -->|"renders comments"| node_vscode_review
node_review_contract -->|"renders comments"| node_cli_review
node_task_controller -->|"coordinates goals"| node_goals_runtime
node_developer -->|"steers goals"| node_goal_control
node_goal_control -->|"controls goals"| node_goals_runtime
node_goals_runtime -->|"creates tasks"| node_task_controller

click node_vscode "https://github.com/dirac-run/dirac/tree/master/src/hosts/vscode"
click node_cli "https://github.com/dirac-run/dirac/tree/master/cli/src"
click node_acp "https://github.com/dirac-run/dirac/tree/master/cli/src/acp"
click node_task_controller "https://github.com/dirac-run/dirac/blob/master/src/core/controller/task/TaskController.ts"
click node_agent "https://github.com/dirac-run/dirac/blob/master/cli/src/agent/DiracAgent.ts"
click node_provider_selection "https://github.com/dirac-run/dirac/blob/master/src/core/api/modelProviderSelection.ts"
click node_model_api "https://github.com/dirac-run/dirac/tree/master/src/core/api/providers"
click node_context "https://github.com/dirac-run/dirac/tree/master/src/core/context"
click node_code_tools "https://github.com/dirac-run/dirac/tree/master/src/core/prompts/system-prompt/tools"
click node_permissions "https://github.com/dirac-run/dirac/tree/master/src/core/permissions"
click node_hooks "https://github.com/dirac-run/dirac/tree/master/src/core/hooks"
click node_goals_runtime "https://github.com/dirac-run/dirac/tree/master/src/core/goal"
click node_goal_control "https://github.com/dirac-run/dirac/tree/master/src/core/controller/goal"
click node_storage_context "https://github.com/dirac-run/dirac/blob/master/src/shared/storage/storage-context.ts"
click node_task_storage "https://github.com/dirac-run/dirac/blob/master/src/core/storage/taskStorage.ts"
click node_checkpoints "https://github.com/dirac-run/dirac/blob/master/src/integrations/checkpoints/CheckpointStorageManager.ts"
click node_review_contract "https://github.com/dirac-run/dirac/blob/master/src/integrations/editor/CommentReviewController.ts"
click node_vscode_review "https://github.com/dirac-run/dirac/blob/master/src/hosts/vscode/review/VscodeCommentReviewController.ts"
click node_cli_review "https://github.com/dirac-run/dirac/blob/master/cli/src/controllers/CliCommentReviewController.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_vscode,node_cli,node_acp toneBlue
class node_task_controller,node_agent,node_provider_selection,node_model_api toneAmber
class node_context,node_code_tools,node_permissions,node_hooks toneMint
class node_goals_runtime,node_goal_control toneRose
class node_storage_context,node_task_storage,node_checkpoints,node_review_contract,node_vscode_review,node_cli_review,node_developer,node_model_service toneIndigo
```

## Components

### User interfaces

- [VS Code](https://github.com/dirac-run/dirac/tree/master/src/hosts/vscode): `src/hosts/vscode`
- [Terminal CLI](https://github.com/dirac-run/dirac/tree/master/cli/src): `cli/src`
- [ACP client](https://github.com/dirac-run/dirac/tree/master/cli/src/acp): `cli/src/acp`

### Task execution

- [Task control](https://github.com/dirac-run/dirac/blob/master/src/core/controller/task/TaskController.ts): `src/core/controller/task/TaskController.ts`
- [Agent runtime](https://github.com/dirac-run/dirac/blob/master/cli/src/agent/DiracAgent.ts): `cli/src/agent/DiracAgent.ts`
- [Provider selection](https://github.com/dirac-run/dirac/blob/master/src/core/api/modelProviderSelection.ts): `src/core/api/modelProviderSelection.ts`
- [Model adapters](https://github.com/dirac-run/dirac/tree/master/src/core/api/providers): `src/core/api/providers`

### Codebase work

- [Context management](https://github.com/dirac-run/dirac/tree/master/src/core/context): `src/core/context`
- [Code tools](https://github.com/dirac-run/dirac/tree/master/src/core/prompts/system-prompt/tools): `src/core/prompts/system-prompt/tools`
- [Permission controls](https://github.com/dirac-run/dirac/tree/master/src/core/permissions): `src/core/permissions`
- [Hooks](https://github.com/dirac-run/dirac/tree/master/src/core/hooks): `src/core/hooks`

### Long-running work

- [Goal runtime](https://github.com/dirac-run/dirac/tree/master/src/core/goal): `src/core/goal`
- [Goal controls](https://github.com/dirac-run/dirac/tree/master/src/core/controller/goal): `src/core/controller/goal`

### State and review

- [Storage context](https://github.com/dirac-run/dirac/blob/master/src/shared/storage/storage-context.ts): `src/shared/storage/storage-context.ts`
- [Task records](https://github.com/dirac-run/dirac/blob/master/src/core/storage/taskStorage.ts): `src/core/storage/taskStorage.ts`
- [Checkpoints](https://github.com/dirac-run/dirac/blob/master/src/integrations/checkpoints/CheckpointStorageManager.ts): `src/integrations/checkpoints/CheckpointStorageManager.ts`
- [Review interface](https://github.com/dirac-run/dirac/blob/master/src/integrations/editor/CommentReviewController.ts): `src/integrations/editor/CommentReviewController.ts`
- [VS Code review](https://github.com/dirac-run/dirac/blob/master/src/hosts/vscode/review/VscodeCommentReviewController.ts): `src/hosts/vscode/review/VscodeCommentReviewController.ts`
- [CLI review](https://github.com/dirac-run/dirac/blob/master/cli/src/controllers/CliCommentReviewController.ts): `cli/src/controllers/CliCommentReviewController.ts`

### Other components

- **Engineer**
- **Model services**

## Connections

- Engineer → VS Code: submits tasks
- Engineer → Terminal CLI: submits tasks
- Engineer → ACP client: submits tasks
- VS Code → Task control: task requests
- Terminal CLI → Task control: task requests
- ACP client → Task control: task requests
- Task control → Agent runtime: runs tasks
- Agent runtime → Provider selection: selects provider
- Provider selection → Model adapters: configures adapter
- Model adapters → Model services: sends requests
- Agent runtime → Context management: assembles context
- Agent runtime → Code tools: uses tools
- Agent runtime → Permission controls: checks actions
- Agent runtime → Hooks: runs hooks
- Task control → Task records: persists task data
- Storage context → Task records: provides storage
- Task control → Checkpoints: manages checkpoints
- Agent runtime → Review interface: reports review comments
- Review interface → VS Code review: renders comments
- Review interface → CLI review: renders comments
- Task control → Goal runtime: coordinates goals
- Engineer → Goal controls: steers goals
- Goal controls → Goal runtime: controls goals
- Goal runtime → Task control: creates tasks