# traycerai/traycer architecture

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

- Interactive diagram: https://gitdiagram.com/traycerai/traycer
- Repository: https://github.com/traycerai/traycer

## Overview

Traycer is an AI-agent orchestration workspace: users connect existing coding agents, work with shared context, and coordinate agents and teammates. The desktop and mobile clients present the workspace; desktop code also manages a local Host and its CLI, while shared host-selection and transport modules support host connectivity. The README documents major capabilities, but the excerpts do not expose the full GUI-to-Host execution path, so those relationships are shown only where documented and otherwise omitted.

Main entry points: [`clients/gui-app/src/lib/auth/auth-service.ts`](https://github.com/traycerai/traycer/blob/main/clients/gui-app/src/lib/auth/auth-service.ts) (Workspace UI), [`clients/desktop/src/renderer-shell/main.tsx`](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/renderer-shell/main.tsx) (Desktop renderer), [`clients/desktop/src/electron-main/main-process.ts`](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/main-process.ts) (Electron main), [`clients/desktop/src/electron-main/host/host-controller.ts`](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/host/host-controller.ts) (Host controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace clients"]
  node_gui["Workspace UI<br/>[auth-service.ts]"]
  node_mobile["Mobile client<br/>[main.tsx]"]
  node_desktopui["Desktop renderer<br/>[main.tsx]"]
end

subgraph group_desktop["Desktop runtime"]
  node_shell["Electron main<br/>[main-process.ts]"]
  node_ipc["IPC bridge"]
  node_browser["Embedded browser"]
  node_storage[("Browser state")]
end

subgraph group_host["Host management"]
  node_hostcontroller["Host controller<br/>[host-controller.ts]"]
  node_cli["Traycer CLI<br/>[traycer-cli.ts]"]
  node_registry["Agent registry<br/>[client.ts]"]
  node_doctor["Host diagnostics<br/>[engine.ts]"]
end

subgraph group_shared["Shared services"]
  node_selection["Host selection"]
  node_reconnect["Reconnect engine"]
  node_browsertransport["Browser sessions"]
end

subgraph group_collab["Orchestration"]
  node_agent(("Coding agents"))
  node_teammates(("Team members"))
  node_cloudtasks["Cloud tasks"]
end

node_user(("Developer"))

node_user -->|"uses workspace"| node_gui
node_user -->|"uses desktop"| node_desktopui
node_user -.->|"uses mobile"| node_mobile
node_gui -->|"connects agents"| node_agent
node_gui -->|"collaborates with"| node_teammates
node_teammates -->|"assigns tickets"| node_cloudtasks
node_gui -.->|"views task work"| node_cloudtasks
node_desktopui -.->|"uses desktop runtime"| node_shell
node_shell -.->|"registers bridge"| node_ipc
node_shell -.->|"manages Host"| node_hostcontroller
node_hostcontroller -->|"runs CLI"| node_cli
node_hostcontroller -.->|"checks releases"| node_registry
node_doctor -.->|"checks versions"| node_registry
node_desktopui -.->|"uses browser"| node_browser
node_browser -.->|"captures state"| node_storage
node_gui -.->|"selects Host"| node_selection
node_gui -.->|"reopens connection"| node_reconnect
node_gui -.->|"streams sessions"| node_browsertransport

click node_gui "https://github.com/traycerai/traycer/blob/main/clients/gui-app/src/lib/auth/auth-service.ts"
click node_mobile "https://github.com/traycerai/traycer/blob/main/clients/mobile/src/web/main.tsx"
click node_desktopui "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/renderer-shell/main.tsx"
click node_shell "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/main-process.ts"
click node_ipc "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/ipc/runner-ipc-bridge.ts"
click node_browser "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/browser-view/browser-view-manager.ts"
click node_storage "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/browser-view/storage/browser-storage-state.ts"
click node_hostcontroller "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/host/host-controller.ts"
click node_cli "https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/cli/traycer-cli.ts"
click node_registry "https://github.com/traycerai/traycer/blob/main/clients/traycer-cli/src/registry/client.ts"
click node_doctor "https://github.com/traycerai/traycer/blob/main/clients/traycer-cli/src/doctor/engine.ts"
click node_selection "https://github.com/traycerai/traycer/blob/main/clients/shared/host-selection/selection-authority-engine.ts"
click node_reconnect "https://github.com/traycerai/traycer/blob/main/clients/shared/host-client/host-connection-reconnect-engine.ts"
click node_browsertransport "https://github.com/traycerai/traycer/blob/main/clients/shared/host-transport/browser-sessions-stream-client.ts"
click node_cloudtasks "https://github.com/traycerai/traycer/blob/main/clients/gui-app/src/hooks/epics/use-cloud-epic-tasks-query.ts"

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_gui,node_mobile,node_desktopui toneBlue
class node_shell,node_ipc,node_browser,node_storage toneAmber
class node_hostcontroller,node_cli,node_registry,node_doctor toneMint
class node_selection,node_reconnect,node_browsertransport toneRose
class node_agent,node_teammates,node_cloudtasks,node_user toneIndigo
```

## Components

### Workspace clients

- [Workspace UI](https://github.com/traycerai/traycer/blob/main/clients/gui-app/src/lib/auth/auth-service.ts): `clients/gui-app/src/lib/auth/auth-service.ts`
- [Mobile client](https://github.com/traycerai/traycer/blob/main/clients/mobile/src/web/main.tsx): `clients/mobile/src/web/main.tsx`
- [Desktop renderer](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/renderer-shell/main.tsx): `clients/desktop/src/renderer-shell/main.tsx`

### Desktop runtime

- [Electron main](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/main-process.ts): `clients/desktop/src/electron-main/main-process.ts`
- [IPC bridge](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/ipc/runner-ipc-bridge.ts): `clients/desktop/src/electron-main/ipc/runner-ipc-bridge.ts`
- [Embedded browser](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/browser-view/browser-view-manager.ts): `clients/desktop/src/electron-main/browser-view/browser-view-manager.ts`
- [Browser state](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/browser-view/storage/browser-storage-state.ts): `clients/desktop/src/electron-main/browser-view/storage/browser-storage-state.ts`

### Host management

- [Host controller](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/host/host-controller.ts): `clients/desktop/src/electron-main/host/host-controller.ts`
- [Traycer CLI](https://github.com/traycerai/traycer/blob/main/clients/desktop/src/electron-main/cli/traycer-cli.ts): `clients/desktop/src/electron-main/cli/traycer-cli.ts`
- [Agent registry](https://github.com/traycerai/traycer/blob/main/clients/traycer-cli/src/registry/client.ts): `clients/traycer-cli/src/registry/client.ts`
- [Host diagnostics](https://github.com/traycerai/traycer/blob/main/clients/traycer-cli/src/doctor/engine.ts): `clients/traycer-cli/src/doctor/engine.ts`

### Shared services

- [Host selection](https://github.com/traycerai/traycer/blob/main/clients/shared/host-selection/selection-authority-engine.ts): `clients/shared/host-selection/selection-authority-engine.ts`
- [Reconnect engine](https://github.com/traycerai/traycer/blob/main/clients/shared/host-client/host-connection-reconnect-engine.ts): `clients/shared/host-client/host-connection-reconnect-engine.ts`
- [Browser sessions](https://github.com/traycerai/traycer/blob/main/clients/shared/host-transport/browser-sessions-stream-client.ts): `clients/shared/host-transport/browser-sessions-stream-client.ts`

### Orchestration

- **Coding agents**
- **Team members**
- [Cloud tasks](https://github.com/traycerai/traycer/blob/main/clients/gui-app/src/hooks/epics/use-cloud-epic-tasks-query.ts): `clients/gui-app/src/hooks/epics/use-cloud-epic-tasks-query.ts`

### Other components

- **Developer**

## Connections

- Developer → Workspace UI: uses workspace
- Developer → Desktop renderer: uses desktop
- Developer → Mobile client: uses mobile
- Workspace UI → Coding agents: connects agents
- Workspace UI → Team members: collaborates with
- Team members → Cloud tasks: assigns tickets
- Workspace UI → Cloud tasks: views task work
- Desktop renderer → Electron main: uses desktop runtime
- Electron main → IPC bridge: registers bridge
- Electron main → Host controller: manages Host
- Host controller → Traycer CLI: runs CLI (evidence: `clients/desktop/src/electron-main/host/host-controller.ts`)
- Host controller → Agent registry: checks releases
- Host diagnostics → Agent registry: checks versions
- Desktop renderer → Embedded browser: uses browser
- Embedded browser → Browser state: captures state
- Workspace UI → Host selection: selects Host
- Workspace UI → Reconnect engine: reopens connection
- Workspace UI → Browser sessions: streams sessions
