# changw98ic/cayw architecture

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

- Interactive diagram: https://gitdiagram.com/changw98ic/cayw
- Repository: https://github.com/changw98ic/cayw

## Overview

CAYW is a Rust agent runtime in which a model organizes tool calls through Luau CodeMode, while the runtime applies permissions, approvals, cancellation and budgets. The principal flow runs from a user-facing client through a session and model interaction to controlled tools and local execution; sessions and execution records support later recovery. The graph also preserves documented interface, plugin, vision and web-access capabilities. Relationships rely on README statements and the supplied source index; unsampled implementation details are not asserted.

Main entry points: [`crates/cayw-runtime/src/session.rs`](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/session.rs) (Session runtime), [`crates/cayw-host/src/lib.rs`](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-host/src/lib.rs) (Controlled host), [`crates/cayw-runtime/src/main.rs`](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/main.rs) (Client entry), [`crates/cayw-agent/src/agent.rs`](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-agent/src/agent.rs) (Agent execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_client["Client entry<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[main.rs]"]
  node_webui["Web UI<br/>[main.rs]"]
end

subgraph group_orchestration["Agent Runtime"]
  node_session["Session runtime<br/>[session.rs]"]
  node_agent["Agent execution<br/>[agent.rs]"]
  node_codemode["Luau CodeMode<br/>[runtime.rs]"]
  node_governance["Execution controls<br/>[permissions.rs]"]
  node_context["Context assembly<br/>[assembly.rs]"]
  node_queue["Work queue<br/>[queue.rs]"]
end

subgraph group_capabilities["Tools and Capabilities"]
  node_provider["Model providers<br/>[transport.rs]"]
  node_host["Controlled host<br/>[lib.rs]"]
  node_workspace["Workspace tools<br/>[filesystem.rs]"]
  node_process["Local processes<br/>[process.rs]"]
  node_webaccess["Web access<br/>[service.rs]"]
  node_vision["Vision service<br/>[service.rs]"]
  node_cells["Code cells<br/>[manager.rs]"]
end

subgraph group_state["Sessions and State"]
  node_records[("Execution records<br/>[persist.rs]")]
  node_store[("Session store<br/>[store.rs]")]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin lifecycle<br/>[cli_plugins.rs]"]
  node_pluginregistry["Plugin registry<br/>[registry.rs]"]
end

node_user(("User"))
node_model(("Model service"))

node_user -->|"starts or connects"| node_client
node_user -->|"uses"| node_tui
node_user -.->|"optionally uses"| node_webui
node_tui -->|"connects through"| node_client
node_webui -->|"connects through"| node_client
node_client -->|"routes requests"| node_session
node_session -->|"runs tasks"| node_agent
node_agent -->|"exchanges messages"| node_model
node_agent -->|"orchestrates tools"| node_codemode
node_codemode -->|"checks each call"| node_governance
node_governance -->|"permits controlled calls"| node_host
node_host -.->|"offers workspace tools"| node_workspace
node_host -.->|"manages execution"| node_process
node_host -.->|"offers web tools"| node_webaccess
node_host -.->|"offers vision tools"| node_vision
node_codemode -->|"executes cell runs"| node_cells
node_session -.->|"assembles context"| node_context
node_session -.->|"enqueues work"| node_queue
node_session -.->|"persists session state"| node_store
node_session -->|"records execution"| node_records
node_client -->|"manages plugins"| node_plugins
node_plugins -->|"loads plugins"| node_pluginregistry
node_agent -.->|"uses model transport"| node_provider

click node_client "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/main.rs"
click node_tui "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-tui/src/main.rs"
click node_webui "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-webui/src/main.rs"
click node_session "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/session.rs"
click node_agent "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-agent/src/agent.rs"
click node_codemode "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-codemode/src/runtime.rs"
click node_governance "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/permissions.rs"
click node_provider "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-providers/src/transport.rs"
click node_host "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-host/src/lib.rs"
click node_workspace "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-workspace/src/filesystem.rs"
click node_process "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-device/src/process.rs"
click node_webaccess "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-web-access/src/service.rs"
click node_vision "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-vision/src/service.rs"
click node_cells "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-cells/src/manager.rs"
click node_context "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-context/src/assembly.rs"
click node_queue "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-queue/src/queue.rs"
click node_records "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-artifacts/src/persist.rs"
click node_store "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-core/src/store.rs"
click node_plugins "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/cli_plugins.rs"
click node_pluginregistry "https://github.com/changw98ic/cayw/blob/dev/crates/cayw-plugins/src/registry.rs"

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_client,node_tui,node_webui,node_user toneBlue
class node_session,node_agent,node_codemode,node_governance,node_context,node_queue toneAmber
class node_provider,node_host,node_workspace,node_process,node_webaccess,node_vision,node_cells toneMint
class node_records,node_store toneRose
class node_plugins,node_pluginregistry,node_model toneIndigo
```

## Components

### User Interfaces

- [Client entry](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/main.rs): `crates/cayw-runtime/src/main.rs`
- [Terminal UI](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-tui/src/main.rs): `crates/cayw-tui/src/main.rs`
- [Web UI](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-webui/src/main.rs): `crates/cayw-webui/src/main.rs`

### Agent Runtime

- [Session runtime](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/session.rs): `crates/cayw-runtime/src/session.rs`
- [Agent execution](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-agent/src/agent.rs): `crates/cayw-agent/src/agent.rs`
- [Luau CodeMode](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-codemode/src/runtime.rs): `crates/cayw-codemode/src/runtime.rs`
- [Execution controls](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/permissions.rs): `crates/cayw-runtime/src/permissions.rs`
- [Context assembly](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-context/src/assembly.rs): `crates/cayw-context/src/assembly.rs`
- [Work queue](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-queue/src/queue.rs): `crates/cayw-queue/src/queue.rs`

### Tools and Capabilities

- [Model providers](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-providers/src/transport.rs): `crates/cayw-providers/src/transport.rs`
- [Controlled host](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-host/src/lib.rs): `crates/cayw-host/src/lib.rs`
- [Workspace tools](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-workspace/src/filesystem.rs): `crates/cayw-workspace/src/filesystem.rs`
- [Local processes](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-device/src/process.rs): `crates/cayw-device/src/process.rs`
- [Web access](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-web-access/src/service.rs): `crates/cayw-web-access/src/service.rs`
- [Vision service](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-vision/src/service.rs): `crates/cayw-vision/src/service.rs`
- [Code cells](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-cells/src/manager.rs): `crates/cayw-cells/src/manager.rs`

### Sessions and State

- [Execution records](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-artifacts/src/persist.rs): `crates/cayw-artifacts/src/persist.rs`
- [Session store](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-core/src/store.rs): `crates/cayw-core/src/store.rs`

### Extensions

- [Plugin lifecycle](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-runtime/src/cli_plugins.rs): `crates/cayw-runtime/src/cli_plugins.rs`
- [Plugin registry](https://github.com/changw98ic/cayw/blob/dev/crates/cayw-plugins/src/registry.rs): `crates/cayw-plugins/src/registry.rs`

### Other components

- **User**
- **Model service**

## Connections

- User → Client entry: starts or connects (evidence: `README.md`)
- User → Terminal UI: uses (evidence: `README.md`)
- User → Web UI: optionally uses (evidence: `README.md`)
- Terminal UI → Client entry: connects through (evidence: `README.md`)
- Web UI → Client entry: connects through (evidence: `README.md`)
- Client entry → Session runtime: routes requests (evidence: `README.md`)
- Session runtime → Agent execution: runs tasks (evidence: `README.md`)
- Agent execution → Model service: exchanges messages (evidence: `README.md`)
- Agent execution → Luau CodeMode: orchestrates tools (evidence: `README.md`)
- Luau CodeMode → Execution controls: checks each call (evidence: `README.md`)
- Execution controls → Controlled host: permits controlled calls (evidence: `README.md`)
- Controlled host → Workspace tools: offers workspace tools
- Controlled host → Local processes: manages execution
- Controlled host → Web access: offers web tools
- Controlled host → Vision service: offers vision tools
- Luau CodeMode → Code cells: executes cell runs (evidence: `crates/cayw-cells/src/manager.rs`)
- Session runtime → Context assembly: assembles context
- Session runtime → Work queue: enqueues work
- Session runtime → Session store: persists session state
- Session runtime → Execution records: records execution (evidence: `README.md`)
- Client entry → Plugin lifecycle: manages plugins (evidence: `crates/cayw-runtime/src/main.rs`)
- Plugin lifecycle → Plugin registry: loads plugins (evidence: `crates/cayw-runtime/src/cli_plugins.rs`)
- Agent execution → Model providers: uses model transport
