# wombatoperator/omarchy-voice architecture

> Architecture diagram of the GitHub repository wombatoperator/omarchy-voice, 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/wombatoperator/omarchy-voice
- Repository: https://github.com/wombatoperator/omarchy-voice

## Overview

omarchy-voice is a voice-controlled Omarchy desktop agent, with separate browser, durable-task, and camera-vision capabilities. The main workflow is user request → Realtime or Live model → policy-gated desktop tools → spoken or visual feedback. Durable tasks and camera inspection are distinct branches. README documents these capabilities, but excerpts sample only selected modules, so uncertain internal wiring is omitted.

Main entry points: [`src/omarchy_voice/cli.py`](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/cli.py) (CLI), [`src/omarchy_voice/tools.py`](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tools.py) (Tool executor), [`src/omarchy_voice/realtime.py`](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/realtime.py) (Realtime session), [`src/omarchy_voice/tasks.py`](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tasks.py) (Task manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice interaction"]
  node_cli["CLI<br/>[cli.py]"]
  node_daemon["Voice daemon<br/>[__main__.py]"]
  node_control["Control socket<br/>[session.py]"]
  node_realtime["Realtime session<br/>[realtime.py]"]
  node_live["Live backend<br/>[live.py]"]
  node_feedback["Audio feedback<br/>[feedback.py]"]
  node_planner["One-shot planner<br/>[planner.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_desktop["Desktop control"]
  node_executor["Tool executor<br/>[tools.py]"]
  node_policy["Action policy<br/>[security.py]"]
  node_capabilities["System capabilities<br/>[capabilities.py]"]
  node_discovery["System discovery<br/>[discovery.py]"]
  node_browser["Browser worker<br/>[browser.py]"]
  node_page["Page text<br/>[page_text.py]"]
end

subgraph group_tasks["Durable tasks"]
  node_taskmanager["Task manager<br/>[tasks.py]"]
  node_taskstore[("Task store<br/>[tasks.py]")]
  node_worker["Task worker<br/>[task_worker.py]"]
  node_workspace["Task artifacts<br/>[workspace_files.py]"]
end

subgraph group_vision["Camera vision"]
  node_visionapp["Vision app<br/>[vision_app.py]"]
  node_visionprovider["Vision provider<br/>[vision_provider.py]"]
end

node_user(("User"))
node_openai{{"OpenAI APIs"}}
node_desktopos{{"Omarchy desktop"}}
node_camera{{"Camera"}}

node_user -->|"issues commands"| node_cli
node_user -->|"speaks requests"| node_daemon
node_cli -->|"sends controls"| node_control
node_control -->|"controls session"| node_realtime
node_daemon -->|"runs"| node_realtime
node_realtime -->|"streams audio"| node_openai
node_openai -->|"returns responses"| node_realtime
node_realtime -->|"dispatches tools"| node_executor
node_realtime -->|"reports state"| node_feedback
node_user -->|"submits typed request"| node_cli
node_cli -->|"runs one-shot plan"| node_planner
node_planner -->|"requests plan"| node_openai
node_live -->|"connects backend"| node_openai
node_live -->|"dispatches tools"| node_executor
node_executor -->|"checks actions"| node_policy
node_executor -->|"executes desktop actions"| node_desktopos
node_executor -->|"reads manifest"| node_capabilities
node_capabilities -->|"queries system"| node_desktopos
node_discovery -->|"inspects installation"| node_desktopos
node_executor -->|"reads page text"| node_page
node_executor -.->|"delegates browser task"| node_browser
node_browser -->|"requests computer use"| node_openai
node_browser -->|"observes browser"| node_desktopos
node_cli -->|"manages tasks"| node_taskmanager
node_live -.->|"delegates tasks"| node_taskmanager
node_taskmanager -->|"persists task state"| node_taskstore
node_taskmanager -->|"starts worker"| node_worker
node_worker -->|"updates task state"| node_taskstore
node_worker -->|"writes artifacts"| node_workspace
node_cli -->|"starts inspection"| node_visionapp
node_visionapp -->|"captures frames"| node_camera
node_visionapp -->|"requests analysis"| node_visionprovider
node_visionprovider -.->|"sends selected frame"| node_openai
node_cli -->|"loads settings"| node_config
node_daemon -->|"loads settings"| node_config

click node_cli "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/cli.py"
click node_daemon "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/__main__.py"
click node_control "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/session.py"
click node_realtime "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/realtime.py"
click node_live "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/live.py"
click node_feedback "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/feedback.py"
click node_planner "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/planner.py"
click node_executor "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tools.py"
click node_policy "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/security.py"
click node_capabilities "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/capabilities.py"
click node_discovery "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/discovery.py"
click node_browser "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/browser.py"
click node_page "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/page_text.py"
click node_taskmanager "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tasks.py"
click node_taskstore "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tasks.py"
click node_worker "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/task_worker.py"
click node_workspace "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/workspace_files.py"
click node_visionapp "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/vision_app.py"
click node_visionprovider "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/vision_provider.py"
click node_config "https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/config.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_cli,node_daemon,node_control,node_realtime,node_live,node_feedback,node_planner,node_config,node_user toneBlue
class node_executor,node_policy,node_capabilities,node_discovery,node_browser,node_page toneAmber
class node_taskmanager,node_taskstore,node_worker,node_workspace,node_openai toneMint
class node_visionapp,node_visionprovider toneRose
class node_desktopos,node_camera toneIndigo
```

## Components

### Voice interaction

- [CLI](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/cli.py): `src/omarchy_voice/cli.py`
- [Voice daemon](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/__main__.py): `src/omarchy_voice/__main__.py`
- [Control socket](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/session.py): `src/omarchy_voice/session.py`
- [Realtime session](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/realtime.py): `src/omarchy_voice/realtime.py`
- [Live backend](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/live.py): `src/omarchy_voice/live.py`
- [Audio feedback](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/feedback.py): `src/omarchy_voice/feedback.py`
- [One-shot planner](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/planner.py): `src/omarchy_voice/planner.py`
- [Configuration](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/config.py): `src/omarchy_voice/config.py`

### Desktop control

- [Tool executor](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tools.py): `src/omarchy_voice/tools.py`
- [Action policy](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/security.py): `src/omarchy_voice/security.py`
- [System capabilities](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/capabilities.py): `src/omarchy_voice/capabilities.py`
- [System discovery](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/discovery.py): `src/omarchy_voice/discovery.py`
- [Browser worker](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/browser.py): `src/omarchy_voice/browser.py`
- [Page text](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/page_text.py): `src/omarchy_voice/page_text.py`

### Durable tasks

- [Task manager](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tasks.py): `src/omarchy_voice/tasks.py`
- [Task store](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/tasks.py): `src/omarchy_voice/tasks.py`
- [Task worker](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/task_worker.py): `src/omarchy_voice/task_worker.py`
- [Task artifacts](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/workspace_files.py): `src/omarchy_voice/workspace_files.py`

### Camera vision

- [Vision app](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/vision_app.py): `src/omarchy_voice/vision_app.py`
- [Vision provider](https://github.com/wombatoperator/omarchy-voice/blob/main/src/omarchy_voice/vision_provider.py): `src/omarchy_voice/vision_provider.py`

### Other components

- **User**
- **OpenAI APIs**
- **Omarchy desktop**
- **Camera**

## Connections

- User → CLI: issues commands
- User → Voice daemon: speaks requests
- CLI → Control socket: sends controls
- Control socket → Realtime session: controls session
- Voice daemon → Realtime session: runs
- Realtime session → OpenAI APIs: streams audio
- OpenAI APIs → Realtime session: returns responses
- Realtime session → Tool executor: dispatches tools
- Realtime session → Audio feedback: reports state
- User → CLI: submits typed request
- CLI → One-shot planner: runs one-shot plan
- One-shot planner → OpenAI APIs: requests plan
- Live backend → OpenAI APIs: connects backend
- Live backend → Tool executor: dispatches tools
- Tool executor → Action policy: checks actions
- Tool executor → Omarchy desktop: executes desktop actions
- Tool executor → System capabilities: reads manifest
- System capabilities → Omarchy desktop: queries system
- System discovery → Omarchy desktop: inspects installation
- Tool executor → Page text: reads page text
- Tool executor → Browser worker: delegates browser task
- Browser worker → OpenAI APIs: requests computer use
- Browser worker → Omarchy desktop: observes browser
- CLI → Task manager: manages tasks
- Live backend → Task manager: delegates tasks
- Task manager → Task store: persists task state
- Task manager → Task worker: starts worker
- Task worker → Task store: updates task state
- Task worker → Task artifacts: writes artifacts
- CLI → Vision app: starts inspection
- Vision app → Camera: captures frames
- Vision app → Vision provider: requests analysis
- Vision provider → OpenAI APIs: sends selected frame
- CLI → Configuration: loads settings
- Voice daemon → Configuration: loads settings