# enricofranke/omarchy-computer-use architecture

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

- Interactive diagram: https://gitdiagram.com/enricofranke/omarchy-computer-use
- Repository: https://github.com/enricofranke/omarchy-computer-use

## Overview

Omarchy Computer Use gives an MCP-capable agent a separate, nested Hyprland desktop, while letting the user preview and take control without surrendering their own input. The principal workflow is agent tool requests → permission checks → desktop actions → screenshots or window results. Users can also manage roles and settings, watch the desktop, and share the clipboard during takeover. The graph includes documented capabilities whose wiring is not fully visible in the sampled excerpts; uncertain implementation links are omitted.

Main entry points: [`agentdesk/computer.py`](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/computer.py) (Computer actions), [`agentdesk/desk.py`](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/desk.py) (Desktop lifecycle), [`agentdesk/mcp.py`](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/mcp.py) (MCP server), [`agentdesk/hypr.py`](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/hypr.py) (Hyprland control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Agent access"]
  node_entry["CLI entry"]
  node_mcp["MCP server<br/>[mcp.py]"]
end

subgraph group_desktop["Sandbox desktop"]
  node_computer["Computer actions<br/>[computer.py]"]
  node_desk["Desktop lifecycle<br/>[desk.py]"]
  node_wayland["Virtual pointer<br/>[wayland.py]"]
  node_hypr["Hyprland control<br/>[hypr.py]"]
  node_cursor["Agent cursor<br/>[cursor.py]"]
  node_runtime_state["Runtime state<br/>[desk.py]"]
end

subgraph group_control["User control"]
  node_watch["Live preview<br/>[watch.py]"]
  node_herdr["Herdr preview bridge<br/>[herdr.py]"]
  node_widget["Bar controls<br/>[BarWidget.qml]"]
  node_clipboard["Clipboard sharing<br/>[clipboard.py]"]
end

subgraph group_policy["Settings and roles"]
  node_policy["Role permissions<br/>[roles.py]"]
  node_admin["Settings and role CLI<br/>[admin.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_agent(("MCP agent"))
node_user(("Desktop user"))
node_host["Host Hyprland"]
node_sandbox["Nested Hyprland"]
node_screen_tools["Screen and input tools"]

node_agent -->|"requests tools"| node_mcp
node_entry -->|"starts server"| node_mcp
node_mcp -->|"checks permissions"| node_policy
node_mcp -->|"dispatches actions"| node_computer
node_computer -->|"controls lifecycle"| node_desk
node_computer -->|"sends pointer events"| node_wayland
node_computer -->|"types and captures"| node_sandbox
node_desk -->|"controls compositor"| node_hypr
node_hypr -->|"issues commands"| node_host
node_hypr -->|"issues commands"| node_sandbox
node_desk -->|"reads and writes"| node_runtime_state
node_desk -->|"sets cursor theme"| node_cursor
node_sandbox -->|"uses"| node_screen_tools
node_computer -->|"loads settings"| node_config
node_computer -->|"opens preview"| node_herdr
node_herdr -->|"starts viewer"| node_watch
node_user -->|"runs controls"| node_entry
node_user -->|"toggles desktop"| node_widget
node_widget -->|"invokes commands"| node_entry
node_user -->|"views and takes over"| node_watch
node_watch -->|"controls visibility"| node_desk
node_desk -->|"starts or stops sharing"| node_clipboard
node_clipboard -->|"copies clipboard"| node_screen_tools
node_user -->|"manages settings"| node_admin
node_admin -->|"reads and edits"| node_config
node_admin -->|"configures roles"| node_policy
node_policy -->|"resolves role settings"| node_config
node_host -->|"hosts nested window"| node_sandbox

click node_entry "https://github.com/enricofranke/omarchy-computer-use/blob/main/bin/agentdesk"
click node_mcp "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/mcp.py"
click node_computer "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/computer.py"
click node_desk "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/desk.py"
click node_wayland "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/wayland.py"
click node_hypr "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/hypr.py"
click node_cursor "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/cursor.py"
click node_watch "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/watch.py"
click node_herdr "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/herdr.py"
click node_widget "https://github.com/enricofranke/omarchy-computer-use/blob/main/omarchy/BarWidget.qml"
click node_clipboard "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/clipboard.py"
click node_policy "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/roles.py"
click node_admin "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/admin.py"
click node_config "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/config.py"
click node_runtime_state "https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/desk.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_entry,node_mcp,node_user,node_screen_tools toneBlue
class node_computer,node_desk,node_wayland,node_hypr,node_cursor,node_runtime_state toneAmber
class node_watch,node_herdr,node_widget,node_clipboard toneMint
class node_policy,node_admin,node_config toneRose
class node_agent,node_host,node_sandbox toneIndigo
```

## Components

### Agent access

- [CLI entry](https://github.com/enricofranke/omarchy-computer-use/blob/main/bin/agentdesk): `bin/agentdesk`
- [MCP server](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/mcp.py): `agentdesk/mcp.py`

### Sandbox desktop

- [Computer actions](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/computer.py): `agentdesk/computer.py`
- [Desktop lifecycle](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/desk.py): `agentdesk/desk.py`
- [Virtual pointer](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/wayland.py): `agentdesk/wayland.py`
- [Hyprland control](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/hypr.py): `agentdesk/hypr.py`
- [Agent cursor](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/cursor.py): `agentdesk/cursor.py`
- [Runtime state](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/desk.py): `agentdesk/desk.py`

### User control

- [Live preview](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/watch.py): `agentdesk/watch.py`
- [Herdr preview bridge](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/herdr.py): `agentdesk/herdr.py`
- [Bar controls](https://github.com/enricofranke/omarchy-computer-use/blob/main/omarchy/BarWidget.qml): `omarchy/BarWidget.qml`
- [Clipboard sharing](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/clipboard.py): `agentdesk/clipboard.py`

### Settings and roles

- [Role permissions](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/roles.py): `agentdesk/roles.py`
- [Settings and role CLI](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/admin.py): `agentdesk/admin.py`
- [Configuration](https://github.com/enricofranke/omarchy-computer-use/blob/main/agentdesk/config.py): `agentdesk/config.py`

### Other components

- **MCP agent**
- **Desktop user**
- **Host Hyprland**
- **Nested Hyprland**
- **Screen and input tools**

## Connections

- MCP agent → MCP server: requests tools
- CLI entry → MCP server: starts server
- MCP server → Role permissions: checks permissions
- MCP server → Computer actions: dispatches actions
- Computer actions → Desktop lifecycle: controls lifecycle
- Computer actions → Virtual pointer: sends pointer events
- Computer actions → Nested Hyprland: types and captures
- Desktop lifecycle → Hyprland control: controls compositor
- Hyprland control → Host Hyprland: issues commands
- Hyprland control → Nested Hyprland: issues commands
- Desktop lifecycle → Runtime state: reads and writes
- Desktop lifecycle → Agent cursor: sets cursor theme
- Nested Hyprland → Screen and input tools: uses
- Computer actions → Configuration: loads settings
- Computer actions → Herdr preview bridge: opens preview
- Herdr preview bridge → Live preview: starts viewer
- Desktop user → CLI entry: runs controls
- Desktop user → Bar controls: toggles desktop
- Bar controls → CLI entry: invokes commands
- Desktop user → Live preview: views and takes over
- Live preview → Desktop lifecycle: controls visibility
- Desktop lifecycle → Clipboard sharing: starts or stops sharing
- Clipboard sharing → Screen and input tools: copies clipboard
- Desktop user → Settings and role CLI: manages settings
- Settings and role CLI → Configuration: reads and edits
- Settings and role CLI → Role permissions: configures roles
- Role permissions → Configuration: resolves role settings
- Host Hyprland → Nested Hyprland: hosts nested window