# turixai/turix-cua architecture

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

- Interactive diagram: https://gitdiagram.com/turixai/turix-cua
- Repository: https://github.com/turixai/turix-cua

## Overview

TuriX is a desktop computer-use agent: a user gives it a task, planning and model reasoning produce structured actions, and the controller executes them against the desktop. The tree also supports planning-time search, skill guidance, and persistent records used for memory or requested file reads. The README documents broader CLI, work/code, and MCP workflows, but this checkout’s sampled implementation centers on the macOS agent/controller; those broader capabilities are not mapped as separate runtime components because their wiring is not evidenced here.

Main entry points: [`src/agent/service.py`](https://github.com/turixai/turix-cua/blob/main/src/agent/service.py) (Agent runtime), [`src/agent/planner_service.py`](https://github.com/turixai/turix-cua/blob/main/src/agent/planner_service.py) (Task planner), [`src/controller/service.py`](https://github.com/turixai/turix-cua/blob/main/src/controller/service.py) (Action controller), [`src/utils/brain_search.py`](https://github.com/turixai/turix-cua/blob/main/src/utils/brain_search.py) (Read-and-reason flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reasoning["Planning and reasoning"]
  node_agent["Agent runtime<br/>[service.py]"]
  node_planner["Task planner<br/>[planner_service.py]"]
  node_messages["Message manager<br/>[service.py]"]
  node_schemas["Output schemas<br/>[structured_llm.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
end

subgraph group_execution["Desktop execution"]
  node_controller["Action controller<br/>[service.py]"]
  node_registry["Action registry<br/>[service.py]"]
  node_tree["UI tree builder<br/>[tree.py]"]
  node_elements["UI elements<br/>[element.py]"]
  node_macactions["Mac input actions<br/>[actions.py]"]
end

subgraph group_context["Context and memory"]
  node_brainsearch["Read-and-reason flow<br/>[brain_search.py]"]
  node_records[("Record store<br/>[record_store.py]")]
  node_skills["Skill guides<br/>[skills.py]"]
end

subgraph group_integrations["External systems"]
  node_model{{"Configured language model"}}
  node_desktop["macOS desktop"]
  node_search{{"Web search"}}
end

node_user(("Task requester"))

node_user -->|"submits task"| node_agent
node_agent -->|"plans task"| node_planner
node_planner -->|"requests planning"| node_model
node_planner -.->|"searches web"| node_search
node_planner -->|"selects guides"| node_skills
node_planner -->|"returns plan"| node_agent
node_agent -->|"builds context"| node_messages
node_messages -->|"uses prompts"| node_prompts
node_agent -->|"requests actions"| node_model
node_model -->|"structured output"| node_schemas
node_agent -->|"dispatches actions"| node_controller
node_controller -->|"executes action"| node_registry
node_controller -->|"builds UI tree"| node_tree
node_tree -->|"creates nodes"| node_elements
node_controller -->|"performs input"| node_macactions
node_macactions -->|"sends events"| node_desktop
node_desktop -->|"exposes UI state"| node_tree
node_agent -->|"handles read request"| node_brainsearch
node_brainsearch -->|"reads records"| node_records
node_brainsearch -->|"updates context"| node_messages
node_agent -->|"stores memory"| node_records

click node_agent "https://github.com/turixai/turix-cua/blob/main/src/agent/service.py"
click node_planner "https://github.com/turixai/turix-cua/blob/main/src/agent/planner_service.py"
click node_messages "https://github.com/turixai/turix-cua/blob/main/src/agent/message_manager/service.py"
click node_schemas "https://github.com/turixai/turix-cua/blob/main/src/agent/structured_llm.py"
click node_prompts "https://github.com/turixai/turix-cua/blob/main/src/agent/prompts.py"
click node_controller "https://github.com/turixai/turix-cua/blob/main/src/controller/service.py"
click node_registry "https://github.com/turixai/turix-cua/blob/main/src/controller/registry/service.py"
click node_tree "https://github.com/turixai/turix-cua/blob/main/src/mac/tree.py"
click node_elements "https://github.com/turixai/turix-cua/blob/main/src/mac/element.py"
click node_macactions "https://github.com/turixai/turix-cua/blob/main/src/mac/actions.py"
click node_brainsearch "https://github.com/turixai/turix-cua/blob/main/src/utils/brain_search.py"
click node_records "https://github.com/turixai/turix-cua/blob/main/src/utils/record_store.py"
click node_skills "https://github.com/turixai/turix-cua/blob/main/src/utils/skills.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_agent,node_planner,node_messages,node_schemas,node_prompts toneBlue
class node_controller,node_registry,node_tree,node_elements,node_macactions toneAmber
class node_brainsearch,node_records,node_skills toneMint
class node_model,node_desktop,node_search,node_user toneRose
```

## Components

### Planning and reasoning

- [Agent runtime](https://github.com/turixai/turix-cua/blob/main/src/agent/service.py): `src/agent/service.py`
- [Task planner](https://github.com/turixai/turix-cua/blob/main/src/agent/planner_service.py): `src/agent/planner_service.py`
- [Message manager](https://github.com/turixai/turix-cua/blob/main/src/agent/message_manager/service.py): `src/agent/message_manager/service.py`
- [Output schemas](https://github.com/turixai/turix-cua/blob/main/src/agent/structured_llm.py): `src/agent/structured_llm.py`
- [Agent prompts](https://github.com/turixai/turix-cua/blob/main/src/agent/prompts.py): `src/agent/prompts.py`

### Desktop execution

- [Action controller](https://github.com/turixai/turix-cua/blob/main/src/controller/service.py): `src/controller/service.py`
- [Action registry](https://github.com/turixai/turix-cua/blob/main/src/controller/registry/service.py): `src/controller/registry/service.py`
- [UI tree builder](https://github.com/turixai/turix-cua/blob/main/src/mac/tree.py): `src/mac/tree.py`
- [UI elements](https://github.com/turixai/turix-cua/blob/main/src/mac/element.py): `src/mac/element.py`
- [Mac input actions](https://github.com/turixai/turix-cua/blob/main/src/mac/actions.py): `src/mac/actions.py`

### Context and memory

- [Read-and-reason flow](https://github.com/turixai/turix-cua/blob/main/src/utils/brain_search.py): `src/utils/brain_search.py`
- [Record store](https://github.com/turixai/turix-cua/blob/main/src/utils/record_store.py): `src/utils/record_store.py`
- [Skill guides](https://github.com/turixai/turix-cua/blob/main/src/utils/skills.py): `src/utils/skills.py`

### External systems

- **Configured language model**
- **macOS desktop**
- **Web search**

### Other components

- **Task requester**

## Connections

- Task requester → Agent runtime: submits task
- Agent runtime → Task planner: plans task
- Task planner → Configured language model: requests planning
- Task planner → Web search: searches web
- Task planner → Skill guides: selects guides
- Task planner → Agent runtime: returns plan
- Agent runtime → Message manager: builds context
- Message manager → Agent prompts: uses prompts
- Agent runtime → Configured language model: requests actions
- Configured language model → Output schemas: structured output
- Agent runtime → Action controller: dispatches actions
- Action controller → Action registry: executes action
- Action controller → UI tree builder: builds UI tree
- UI tree builder → UI elements: creates nodes
- Action controller → Mac input actions: performs input
- Mac input actions → macOS desktop: sends events
- macOS desktop → UI tree builder: exposes UI state
- Agent runtime → Read-and-reason flow: handles read request
- Read-and-reason flow → Record store: reads records
- Read-and-reason flow → Message manager: updates context
- Agent runtime → Record store: stores memory