# flyingviet/cantrip architecture

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

- Interactive diagram: https://gitdiagram.com/flyingviet/cantrip
- Repository: https://github.com/flyingviet/cantrip

## Overview

Cantrip is a macOS keyboard-first launcher and AI-agent host, with Windows support and native, desktop, and browser clients for shared sessions. The main workflow is a user request entering the launcher or a client, reaching a host session and selected agent backend, then returning as a streamed answer or task result. Major branches include Cantrip Home, memory and council, extensions, and remote control. README statements establish most cross-platform and host relationships; sampled gateway excerpts show its API and transport path. Other unsampled implementation links are omitted.

Main entry points: [`Sources/Cantrip/ChatSession.swift`](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/ChatSession.swift) (Chat Session), [`Sources/Cantrip`](https://github.com/flyingviet/cantrip/tree/main/Sources/Cantrip) (Remote Control API), [`Sources/Cantrip/SessionManager.swift`](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/SessionManager.swift) (Session Manager), [`Sources/Cantrip/LauncherView.swift`](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/LauncherView.swift) (Keyboard Launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Mac Host"]
  node_launcher["Keyboard Launcher<br/>[LauncherView.swift]"]
  node_sessions["Session Manager"]
  node_chat["Chat Session<br/>[ChatSession.swift]"]
  node_backends["Agent Backends"]
  node_remoteapi["Remote Control API"]
end

subgraph group_gateway["Gateway Client"]
  node_gatewayui["Gateway Workspace<br/>[App.tsx]"]
  node_gatewaystate["Remote Session State<br/>[remote.ts]"]
  node_gatewayapi["Gateway API Client<br/>[client.ts]"]
  node_gatewaymain["Gateway Main Process<br/>[main.ts]"]
  node_gatewaytransport["Gateway Transport<br/>[transport.ts]"]
end

subgraph group_mobile["Mobile Client"]
  node_ios["Cantrip Agent<br/>[ChatView.swift]"]
  node_watch["Watch Voice Client"]
end

subgraph group_windows["Windows App"]
  node_winlauncher["Windows Launcher<br/>[main.ts]"]
  node_winhome["Windows Home Client<br/>[service.ts]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_home["Cantrip Home<br/>[CantripHome.swift]"]
  node_memory[("Memory and Council<br/>[MemoryStore.swift]")]
  node_extensions["Extensions and MCP<br/>[MCPManager.swift]"]
  node_background["Background Engine"]
end

node_user(("User"))
node_browser(("Browser Remote"))

node_user -->|"invokes"| node_launcher
node_launcher -.->|"starts sessions"| node_sessions
node_sessions -->|"manages tabs"| node_chat
node_chat -->|"runs agent"| node_backends
node_sessions -.->|"serves sessions"| node_remoteapi
node_user -->|"uses"| node_gatewayui
node_gatewayui -->|"renders workspace"| node_gatewaystate
node_gatewaystate -->|"requests session data"| node_gatewayapi
node_gatewayapi -->|"sends API calls"| node_gatewaymain
node_gatewaymain -->|"routes requests"| node_gatewaytransport
node_gatewaytransport -->|"connects to host"| node_remoteapi
node_user -->|"uses"| node_ios
node_ios -->|"controls sessions"| node_remoteapi
node_user -->|"speaks requests"| node_watch
node_watch -->|"talks to Home"| node_home
node_user -->|"uses"| node_winlauncher
node_winlauncher -->|"runs supported agents"| node_backends
node_user -->|"views Home"| node_winhome
node_winhome -->|"reads paired host"| node_remoteapi
node_browser -->|"controls remotely"| node_remoteapi
node_home -->|"hands off work"| node_chat
node_chat -->|"uses context"| node_memory
node_chat -->|"invokes tools"| node_extensions
node_background -->|"runs tabs"| node_chat

click node_launcher "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/LauncherView.swift"
click node_sessions "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/SessionManager.swift"
click node_chat "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/ChatSession.swift"
click node_backends "https://github.com/flyingviet/cantrip/tree/main/Sources/Cantrip/Backends"
click node_remoteapi "https://github.com/flyingviet/cantrip/tree/main/Sources/Cantrip"
click node_home "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/CantripHome.swift"
click node_memory "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/MemoryStore.swift"
click node_extensions "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/MCPManager.swift"
click node_background "https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/BackgroundEngine.swift"
click node_gatewayui "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/ui/App.tsx"
click node_gatewaystate "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/state/remote.ts"
click node_gatewayapi "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/api/client.ts"
click node_gatewaymain "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/main/main.ts"
click node_gatewaytransport "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/main/transport.ts"
click node_ios "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripIOS/Sources/ChatView.swift"
click node_watch "https://github.com/flyingviet/cantrip/blob/main/Clients/CantripIOS/Watch/CantripWatchClient.swift"
click node_winlauncher "https://github.com/flyingviet/cantrip/blob/main/windows/src/main/main.ts"
click node_winhome "https://github.com/flyingviet/cantrip/blob/main/windows/src/main/home/service.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_launcher,node_sessions,node_chat,node_backends,node_remoteapi,node_user,node_browser toneBlue
class node_gatewayui,node_gatewaystate,node_gatewayapi,node_gatewaymain,node_gatewaytransport toneAmber
class node_ios,node_watch toneMint
class node_winlauncher,node_winhome toneRose
class node_home,node_memory,node_extensions,node_background toneIndigo
```

## Components

### Mac Host

- [Keyboard Launcher](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/LauncherView.swift): `Sources/Cantrip/LauncherView.swift`
- [Session Manager](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/SessionManager.swift): `Sources/Cantrip/SessionManager.swift`
- [Chat Session](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/ChatSession.swift): `Sources/Cantrip/ChatSession.swift`
- [Agent Backends](https://github.com/flyingviet/cantrip/tree/main/Sources/Cantrip/Backends): `Sources/Cantrip/Backends`
- [Remote Control API](https://github.com/flyingviet/cantrip/tree/main/Sources/Cantrip): `Sources/Cantrip`

### Gateway Client

- [Gateway Workspace](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/ui/App.tsx): `Clients/CantripGatewayMac/windows/src/gateway/ui/App.tsx`
- [Remote Session State](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/state/remote.ts): `Clients/CantripGatewayMac/windows/src/gateway/state/remote.ts`
- [Gateway API Client](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/gateway/api/client.ts): `Clients/CantripGatewayMac/windows/src/gateway/api/client.ts`
- [Gateway Main Process](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/main/main.ts): `Clients/CantripGatewayMac/windows/src/main/main.ts`
- [Gateway Transport](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripGatewayMac/windows/src/main/transport.ts): `Clients/CantripGatewayMac/windows/src/main/transport.ts`

### Mobile Client

- [Cantrip Agent](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripIOS/Sources/ChatView.swift): `Clients/CantripIOS/Sources/ChatView.swift`
- [Watch Voice Client](https://github.com/flyingviet/cantrip/blob/main/Clients/CantripIOS/Watch/CantripWatchClient.swift): `Clients/CantripIOS/Watch/CantripWatchClient.swift`

### Windows App

- [Windows Launcher](https://github.com/flyingviet/cantrip/blob/main/windows/src/main/main.ts): `windows/src/main/main.ts`
- [Windows Home Client](https://github.com/flyingviet/cantrip/blob/main/windows/src/main/home/service.ts): `windows/src/main/home/service.ts`

### Agent Capabilities

- [Cantrip Home](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/CantripHome.swift): `Sources/Cantrip/CantripHome.swift`
- [Memory and Council](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/MemoryStore.swift): `Sources/Cantrip/MemoryStore.swift`
- [Extensions and MCP](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/MCPManager.swift): `Sources/Cantrip/MCPManager.swift`
- [Background Engine](https://github.com/flyingviet/cantrip/blob/main/Sources/Cantrip/BackgroundEngine.swift): `Sources/Cantrip/BackgroundEngine.swift`

### Other components

- **User**
- **Browser Remote**

## Connections

- User → Keyboard Launcher: invokes (evidence: `README.md`)
- Keyboard Launcher → Session Manager: starts sessions
- Session Manager → Chat Session: manages tabs (evidence: `Sources/Cantrip/SessionManager.swift`)
- Chat Session → Agent Backends: runs agent (evidence: `README.md`)
- Session Manager → Remote Control API: serves sessions (evidence: `Sources/Cantrip/SessionManager.swift`)
- User → Gateway Workspace: uses (evidence: `README.md`)
- Gateway Workspace → Remote Session State: renders workspace (evidence: `Clients/CantripGatewayMac/windows/src/gateway/ui/App.tsx`)
- Remote Session State → Gateway API Client: requests session data (evidence: `Clients/CantripGatewayMac/windows/src/gateway/state/remote.ts`)
- Gateway API Client → Gateway Main Process: sends API calls (evidence: `Clients/CantripGatewayMac/windows/src/gateway/api/client.ts`)
- Gateway Main Process → Gateway Transport: routes requests (evidence: `Clients/CantripGatewayMac/windows/src/main/main.ts`)
- Gateway Transport → Remote Control API: connects to host (evidence: `README.md`)
- User → Cantrip Agent: uses (evidence: `README.md`)
- Cantrip Agent → Remote Control API: controls sessions (evidence: `README.md`)
- User → Watch Voice Client: speaks requests (evidence: `README.md`)
- Watch Voice Client → Cantrip Home: talks to Home (evidence: `README.md`)
- User → Windows Launcher: uses (evidence: `README.md`)
- Windows Launcher → Agent Backends: runs supported agents (evidence: `README.md`)
- User → Windows Home Client: views Home (evidence: `README.md`)
- Windows Home Client → Remote Control API: reads paired host (evidence: `README.md`)
- Browser Remote → Remote Control API: controls remotely (evidence: `README.md`)
- Cantrip Home → Chat Session: hands off work (evidence: `README.md`)
- Chat Session → Memory and Council: uses context (evidence: `README.md`)
- Chat Session → Extensions and MCP: invokes tools (evidence: `README.md`)
- Background Engine → Chat Session: runs tabs (evidence: `README.md`)