# ian688/modus architecture

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

- Interactive diagram: https://gitdiagram.com/ian688/modus
- Repository: https://github.com/ian688/modus

## Overview

Modus is a local Python agent runtime with CLI and Electron/Web desktop interfaces. The main workflow is a user task entering through a UI, being managed as a bounded run, routed through an agent mode, and executed through governed tools; results and run events are persisted for review and replay. Major documented branches include MOA, Peri, external agent runtimes, browser automation, and the desktop preview workspace. Some subsystems are represented from README capabilities and the source index; their internal call paths were not sampled.

Main entry points: [`src/modus/desktop/server.py`](https://github.com/ian688/modus/blob/main/src/modus/desktop/server.py) (Desktop Server), [`src/modus/tools/executor.py`](https://github.com/ian688/modus/blob/main/src/modus/tools/executor.py) (Tool Executor), [`src/modus/runtime/controller.py`](https://github.com/ian688/modus/blob/main/src/modus/runtime/controller.py) (Run Controller), [`src/modus/tools/registry.py`](https://github.com/ian688/modus/blob/main/src/modus/tools/registry.py) (Tool Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_desktop_shell["Electron Shell<br/>[main.js]"]
  node_desktop_server["Desktop Server<br/>[server.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_runs["Run Orchestration"]
  node_run_controller["Run Controller<br/>[controller.py]"]
  node_run_budget["Run Budget<br/>[budget.py]"]
  node_run_state["Run State<br/>[state.py]"]
  node_completion_gate["Completion Gate<br/>[completion_gate.py]"]
end

subgraph group_agent["Agent Modes"]
  node_query_engine["Query Engine<br/>[query_engine.py]"]
  node_default_runner["Default Runner<br/>[default_runner.py]"]
  node_moa_runner["MOA Runner<br/>[moa_runner.py]"]
  node_peri_runner["Peri Runner<br/>[peri_runner.py]"]
  node_external_runner["External Runner<br/>[external_runner.py]"]
end

subgraph group_tools["Tools and Safety"]
  node_tool_registry["Tool Registry<br/>[registry.py]"]
  node_tool_executor["Tool Executor<br/>[executor.py]"]
  node_tool_definitions["Tool Definitions<br/>[base.py]"]
  node_approval_policy["Approval Policy<br/>[approval.py]"]
  node_browser_runtime["Browser Runtime<br/>[browser-runtime.js]"]
  node_mcp_client["MCP Client<br/>[mcp_client.py]"]
end

subgraph group_desktop["Desktop Services"]
  node_desktop_db[("Run Database<br/>[db.py]")]
  node_preview_host["Preview Host<br/>[preview-host.ts]"]
  node_preview_adapters["Preview Adapters<br/>[browser-preview.ts]"]
  node_model_discovery["Model Discovery<br/>[model_discovery.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))

node_user -->|"uses desktop"| node_desktop_shell
node_user -->|"runs tasks"| node_cli
node_desktop_shell -->|"starts and checks"| node_desktop_server
node_desktop_server -->|"routes runs"| node_default_runner
node_desktop_server -->|"routes runs"| node_moa_runner
node_desktop_server -->|"routes runs"| node_peri_runner
node_desktop_server -->|"routes runs"| node_external_runner
node_cli -.->|"runs queries"| node_query_engine
node_default_runner -.->|"shares run controls"| node_run_controller
node_run_controller -->|"guards lifecycle"| node_run_state
node_run_controller -.->|"shares run limits"| node_run_budget
node_run_controller -->|"checks completion"| node_completion_gate
node_desktop_server -->|"persists run data"| node_desktop_db
node_query_engine -->|"supplies tools"| node_tool_registry
node_tool_registry -->|"registers tools"| node_tool_definitions
node_tool_executor -->|"executes handlers"| node_tool_definitions
node_tool_executor -->|"resolves tools"| node_tool_registry
node_tool_executor -->|"checks budget"| node_run_budget
node_tool_executor -->|"requests approval"| node_approval_policy
node_desktop_server -.->|"supports model setup"| node_model_discovery
node_desktop_server -->|"loads settings"| node_config
node_desktop_server -.->|"offers preview workspace"| node_preview_host
node_preview_host -.->|"mounts adapters"| node_preview_adapters
node_desktop_shell -->|"starts browser runtime"| node_browser_runtime
node_browser_runtime -.->|"serves browser tools"| node_tool_executor
node_tool_registry -.->|"registers MCP tools"| node_mcp_client
node_desktop_server -->|"records approvals"| node_desktop_db
node_desktop_server -->|"records events"| node_desktop_db

click node_desktop_shell "https://github.com/ian688/modus/blob/main/electron/main.js"
click node_desktop_server "https://github.com/ian688/modus/blob/main/src/modus/desktop/server.py"
click node_cli "https://github.com/ian688/modus/blob/main/src/modus/entrypoints/cli.py"
click node_query_engine "https://github.com/ian688/modus/blob/main/src/modus/agent/query_engine.py"
click node_default_runner "https://github.com/ian688/modus/blob/main/src/modus/desktop/default_runner.py"
click node_moa_runner "https://github.com/ian688/modus/blob/main/src/modus/desktop/moa_runner.py"
click node_peri_runner "https://github.com/ian688/modus/blob/main/src/modus/desktop/peri_runner.py"
click node_external_runner "https://github.com/ian688/modus/blob/main/src/modus/desktop/external_runner.py"
click node_run_controller "https://github.com/ian688/modus/blob/main/src/modus/runtime/controller.py"
click node_run_budget "https://github.com/ian688/modus/blob/main/src/modus/runtime/budget.py"
click node_run_state "https://github.com/ian688/modus/blob/main/src/modus/runtime/state.py"
click node_completion_gate "https://github.com/ian688/modus/blob/main/src/modus/desktop/completion_gate.py"
click node_tool_registry "https://github.com/ian688/modus/blob/main/src/modus/tools/registry.py"
click node_tool_executor "https://github.com/ian688/modus/blob/main/src/modus/tools/executor.py"
click node_tool_definitions "https://github.com/ian688/modus/blob/main/src/modus/tools/base.py"
click node_approval_policy "https://github.com/ian688/modus/blob/main/src/modus/policy/approval.py"
click node_browser_runtime "https://github.com/ian688/modus/blob/main/electron/browser-runtime.js"
click node_desktop_db "https://github.com/ian688/modus/blob/main/src/modus/desktop/db.py"
click node_preview_host "https://github.com/ian688/modus/blob/main/electron/renderer/preview/preview-host.ts"
click node_preview_adapters "https://github.com/ian688/modus/blob/main/electron/renderer/preview/adapters/browser-preview.ts"
click node_model_discovery "https://github.com/ian688/modus/blob/main/src/modus/desktop/model_discovery.py"
click node_config "https://github.com/ian688/modus/blob/main/src/modus/config.py"
click node_mcp_client "https://github.com/ian688/modus/blob/main/src/modus/mcp_client.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_desktop_shell,node_desktop_server,node_cli,node_user toneBlue
class node_run_controller,node_run_budget,node_run_state,node_completion_gate toneAmber
class node_query_engine,node_default_runner,node_moa_runner,node_peri_runner,node_external_runner toneMint
class node_tool_registry,node_tool_executor,node_tool_definitions,node_approval_policy,node_browser_runtime,node_mcp_client toneRose
class node_desktop_db,node_preview_host,node_preview_adapters,node_model_discovery,node_config toneIndigo
```

## Components

### User Interfaces

- [Electron Shell](https://github.com/ian688/modus/blob/main/electron/main.js): `electron/main.js`
- [Desktop Server](https://github.com/ian688/modus/blob/main/src/modus/desktop/server.py): `src/modus/desktop/server.py`
- [CLI](https://github.com/ian688/modus/blob/main/src/modus/entrypoints/cli.py): `src/modus/entrypoints/cli.py`

### Run Orchestration

- [Run Controller](https://github.com/ian688/modus/blob/main/src/modus/runtime/controller.py): `src/modus/runtime/controller.py`
- [Run Budget](https://github.com/ian688/modus/blob/main/src/modus/runtime/budget.py): `src/modus/runtime/budget.py`
- [Run State](https://github.com/ian688/modus/blob/main/src/modus/runtime/state.py): `src/modus/runtime/state.py`
- [Completion Gate](https://github.com/ian688/modus/blob/main/src/modus/desktop/completion_gate.py): `src/modus/desktop/completion_gate.py`

### Agent Modes

- [Query Engine](https://github.com/ian688/modus/blob/main/src/modus/agent/query_engine.py): `src/modus/agent/query_engine.py`
- [Default Runner](https://github.com/ian688/modus/blob/main/src/modus/desktop/default_runner.py): `src/modus/desktop/default_runner.py`
- [MOA Runner](https://github.com/ian688/modus/blob/main/src/modus/desktop/moa_runner.py): `src/modus/desktop/moa_runner.py`
- [Peri Runner](https://github.com/ian688/modus/blob/main/src/modus/desktop/peri_runner.py): `src/modus/desktop/peri_runner.py`
- [External Runner](https://github.com/ian688/modus/blob/main/src/modus/desktop/external_runner.py): `src/modus/desktop/external_runner.py`

### Tools and Safety

- [Tool Registry](https://github.com/ian688/modus/blob/main/src/modus/tools/registry.py): `src/modus/tools/registry.py`
- [Tool Executor](https://github.com/ian688/modus/blob/main/src/modus/tools/executor.py): `src/modus/tools/executor.py`
- [Tool Definitions](https://github.com/ian688/modus/blob/main/src/modus/tools/base.py): `src/modus/tools/base.py`
- [Approval Policy](https://github.com/ian688/modus/blob/main/src/modus/policy/approval.py): `src/modus/policy/approval.py`
- [Browser Runtime](https://github.com/ian688/modus/blob/main/electron/browser-runtime.js): `electron/browser-runtime.js`
- [MCP Client](https://github.com/ian688/modus/blob/main/src/modus/mcp_client.py): `src/modus/mcp_client.py`

### Desktop Services

- [Run Database](https://github.com/ian688/modus/blob/main/src/modus/desktop/db.py): `src/modus/desktop/db.py`
- [Preview Host](https://github.com/ian688/modus/blob/main/electron/renderer/preview/preview-host.ts): `electron/renderer/preview/preview-host.ts`
- [Preview Adapters](https://github.com/ian688/modus/blob/main/electron/renderer/preview/adapters/browser-preview.ts): `electron/renderer/preview/adapters/browser-preview.ts`
- [Model Discovery](https://github.com/ian688/modus/blob/main/src/modus/desktop/model_discovery.py): `src/modus/desktop/model_discovery.py`
- [Configuration](https://github.com/ian688/modus/blob/main/src/modus/config.py): `src/modus/config.py`

### Other components

- **User**

## Connections

- User → Electron Shell: uses desktop (evidence: `README.md`)
- User → CLI: runs tasks (evidence: `README.md`)
- Electron Shell → Desktop Server: starts and checks (evidence: `electron/main.js`)
- Desktop Server → Default Runner: routes runs (evidence: `src/modus/desktop/server.py`)
- Desktop Server → MOA Runner: routes runs (evidence: `src/modus/desktop/server.py`)
- Desktop Server → Peri Runner: routes runs (evidence: `src/modus/desktop/server.py`)
- Desktop Server → External Runner: routes runs (evidence: `src/modus/desktop/server.py`)
- CLI → Query Engine: runs queries
- Default Runner → Run Controller: shares run controls
- Run Controller → Run State: guards lifecycle (evidence: `src/modus/runtime/controller.py`)
- Run Controller → Run Budget: shares run limits (evidence: `src/modus/runtime/controller.py`)
- Run Controller → Completion Gate: checks completion (evidence: `src/modus/runtime/controller.py`)
- Desktop Server → Run Database: persists run data (evidence: `src/modus/desktop/server.py`)
- Query Engine → Tool Registry: supplies tools (evidence: `src/modus/agent/query_engine.py`)
- Tool Registry → Tool Definitions: registers tools (evidence: `src/modus/tools/registry.py`)
- Tool Executor → Tool Definitions: executes handlers (evidence: `src/modus/tools/executor.py`)
- Tool Executor → Tool Registry: resolves tools (evidence: `src/modus/tools/executor.py`)
- Tool Executor → Run Budget: checks budget (evidence: `src/modus/tools/executor.py`)
- Tool Executor → Approval Policy: requests approval (evidence: `src/modus/tools/executor.py`)
- Desktop Server → Model Discovery: supports model setup (evidence: `src/modus/desktop/server.py`)
- Desktop Server → Configuration: loads settings (evidence: `src/modus/desktop/server.py`)
- Desktop Server → Preview Host: offers preview workspace
- Preview Host → Preview Adapters: mounts adapters
- Electron Shell → Browser Runtime: starts browser runtime (evidence: `electron/main.js`)
- Browser Runtime → Tool Executor: serves browser tools
- Tool Registry → MCP Client: registers MCP tools
- Desktop Server → Run Database: records approvals (evidence: `README.md`)
- Desktop Server → Run Database: records events (evidence: `README.md`)
