# sarajo/circe architecture

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

- Interactive diagram: https://gitdiagram.com/sarajo/circe
- Repository: https://github.com/sarajo/circe

## Overview

Circe adopts a local Hermes fleet, guides the user through choosing agents and identities, then opens themed desktop tiles for ongoing conversations. The main process coordinates onboarding, Hermes profile changes, and tile lifecycles; renderer windows communicate through preload bridges. Tiles support conversation tabs and handoffs, context monitoring, image prompts, and tool approvals. The README documents avatar generation, orchestrator-skill installation, and fleet watching; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/main/tiles.ts`](https://github.com/sarajo/circe/blob/main/src/main/tiles.ts) (Tile lifecycle), [`src/main/hermes/real.ts`](https://github.com/sarajo/circe/blob/main/src/main/hermes/real.ts) (Hermes runtime), [`src/main/wizard.ts`](https://github.com/sarajo/circe/blob/main/src/main/wizard.ts) (Onboarding flow), [`src/main/index.ts`](https://github.com/sarajo/circe/blob/main/src/main/index.ts) (App coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onboard["Onboarding and identity"]
  node_fleet["Fleet discovery<br/>[fleet.ts]"]
  node_wizard["Onboarding flow<br/>[wizard.ts]"]
  node_wizardui["Wizard screens<br/>[main.ts]"]
  node_wizardbridge["Wizard bridge<br/>[wizard.ts]"]
  node_identity["Identity derivation<br/>[derive.ts]"]
  node_fandom["Fandom lookup<br/>[fandom.ts]"]
  node_avatar["Portrait generation<br/>[generatedAvatar.ts]"]
  node_skill["Coordinator skill<br/>[skill.ts]"]
end

subgraph group_runtime["Desktop runtime"]
  node_main["App coordinator<br/>[index.ts]"]
  node_windows["Window manager<br/>[windows.ts]"]
end

subgraph group_tile["Agent tiles"]
  node_tilemanager["Tile lifecycle<br/>[tiles.ts]"]
  node_tileui["Tile interface<br/>[main.ts]"]
  node_tilebridge["Tile bridge<br/>[tile.ts]"]
  node_session["Session restore<br/>[restore.ts]"]
  node_tabstate["Tab persistence<br/>[tileState.ts]"]
  node_acp["Agent protocol<br/>[acp.ts]"]
  node_tiledata[("Tile preferences<br/>[tileState.ts]")]
end

subgraph group_hermes["Hermes integration"]
  node_hermes["Hermes runtime<br/>[real.ts]"]
  node_runtimepaths["Hermes paths<br/>[runtime.ts]"]
end

node_user(("User"))
node_hermescli["Hermes CLI"]
node_provider["Model provider"]

node_user -->|"chooses setup"| node_wizardui
node_wizardui -->|"sends actions"| node_wizardbridge
node_wizardbridge -->|"dispatches IPC"| node_wizard
node_main -->|"creates windows"| node_windows
node_main -->|"starts onboarding"| node_wizard
node_main -->|"lists profiles"| node_fleet
node_fleet -->|"queries profiles"| node_hermes
node_wizard -->|"checks and updates"| node_hermes
node_wizard -->|"derives identities"| node_identity
node_identity -.->|"looks up references"| node_fandom
node_wizard -->|"requests portraits"| node_avatar
node_avatar -->|"generates images"| node_hermes
node_wizard -->|"installs skill"| node_skill
node_skill -->|"writes profile files"| node_hermes
node_hermes -->|"resolves home paths"| node_runtimepaths
node_hermes -->|"runs commands"| node_hermescli
node_hermescli -->|"uses configured model"| node_provider
node_main -->|"opens fleet tiles"| node_tilemanager
node_tilemanager -->|"creates tile windows"| node_windows
node_tilemanager -->|"loads profile data"| node_hermes
node_tilemanager -->|"restores conversations"| node_session
node_tilemanager -->|"reads and writes tabs"| node_tabstate
node_tabstate -->|"persists state"| node_tiledata
node_tilemanager -->|"manages agent sessions"| node_acp
node_acp -->|"connects to runtime"| node_hermes
node_tileui -->|"sends prompts"| node_tilebridge
node_tilebridge -->|"dispatches tile actions"| node_tilemanager
node_tilemanager -->|"sends updates"| node_tilebridge
node_tilebridge -->|"delivers events"| node_tileui
node_user -->|"chats and approves"| node_tileui
node_tileui -->|"renders agent updates"| node_acp

click node_main "https://github.com/sarajo/circe/blob/main/src/main/index.ts"
click node_windows "https://github.com/sarajo/circe/blob/main/src/main/windows.ts"
click node_fleet "https://github.com/sarajo/circe/blob/main/src/main/fleet.ts"
click node_wizard "https://github.com/sarajo/circe/blob/main/src/main/wizard.ts"
click node_wizardui "https://github.com/sarajo/circe/blob/main/src/renderer/wizard/main.ts"
click node_wizardbridge "https://github.com/sarajo/circe/blob/main/src/preload/wizard.ts"
click node_identity "https://github.com/sarajo/circe/blob/main/src/main/derive.ts"
click node_fandom "https://github.com/sarajo/circe/blob/main/src/main/fandom.ts"
click node_avatar "https://github.com/sarajo/circe/blob/main/src/main/generatedAvatar.ts"
click node_skill "https://github.com/sarajo/circe/blob/main/src/main/orchestrator/skill.ts"
click node_tilemanager "https://github.com/sarajo/circe/blob/main/src/main/tiles.ts"
click node_tileui "https://github.com/sarajo/circe/blob/main/src/renderer/tile/main.ts"
click node_tilebridge "https://github.com/sarajo/circe/blob/main/src/preload/tile.ts"
click node_session "https://github.com/sarajo/circe/blob/main/src/main/restore.ts"
click node_tabstate "https://github.com/sarajo/circe/blob/main/src/main/tileState.ts"
click node_acp "https://github.com/sarajo/circe/blob/main/src/main/acp.ts"
click node_hermes "https://github.com/sarajo/circe/blob/main/src/main/hermes/real.ts"
click node_runtimepaths "https://github.com/sarajo/circe/blob/main/src/main/hermes/runtime.ts"
click node_tiledata "https://github.com/sarajo/circe/blob/main/src/main/tileState.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_fleet,node_wizard,node_wizardui,node_wizardbridge,node_identity,node_fandom,node_avatar,node_skill,node_user toneBlue
class node_main,node_windows toneAmber
class node_tilemanager,node_tileui,node_tilebridge,node_session,node_tabstate,node_acp,node_tiledata toneMint
class node_hermes,node_runtimepaths toneRose
class node_hermescli,node_provider toneIndigo
```

## Components

### Onboarding and identity

- [Fleet discovery](https://github.com/sarajo/circe/blob/main/src/main/fleet.ts): `src/main/fleet.ts`
- [Onboarding flow](https://github.com/sarajo/circe/blob/main/src/main/wizard.ts): `src/main/wizard.ts`
- [Wizard screens](https://github.com/sarajo/circe/blob/main/src/renderer/wizard/main.ts): `src/renderer/wizard/main.ts`
- [Wizard bridge](https://github.com/sarajo/circe/blob/main/src/preload/wizard.ts): `src/preload/wizard.ts`
- [Identity derivation](https://github.com/sarajo/circe/blob/main/src/main/derive.ts): `src/main/derive.ts`
- [Fandom lookup](https://github.com/sarajo/circe/blob/main/src/main/fandom.ts): `src/main/fandom.ts`
- [Portrait generation](https://github.com/sarajo/circe/blob/main/src/main/generatedAvatar.ts): `src/main/generatedAvatar.ts`
- [Coordinator skill](https://github.com/sarajo/circe/blob/main/src/main/orchestrator/skill.ts): `src/main/orchestrator/skill.ts`

### Desktop runtime

- [App coordinator](https://github.com/sarajo/circe/blob/main/src/main/index.ts): `src/main/index.ts`
- [Window manager](https://github.com/sarajo/circe/blob/main/src/main/windows.ts): `src/main/windows.ts`

### Agent tiles

- [Tile lifecycle](https://github.com/sarajo/circe/blob/main/src/main/tiles.ts): `src/main/tiles.ts`
- [Tile interface](https://github.com/sarajo/circe/blob/main/src/renderer/tile/main.ts): `src/renderer/tile/main.ts`
- [Tile bridge](https://github.com/sarajo/circe/blob/main/src/preload/tile.ts): `src/preload/tile.ts`
- [Session restore](https://github.com/sarajo/circe/blob/main/src/main/restore.ts): `src/main/restore.ts`
- [Tab persistence](https://github.com/sarajo/circe/blob/main/src/main/tileState.ts): `src/main/tileState.ts`
- [Agent protocol](https://github.com/sarajo/circe/blob/main/src/main/acp.ts): `src/main/acp.ts`
- [Tile preferences](https://github.com/sarajo/circe/blob/main/src/main/tileState.ts): `src/main/tileState.ts`

### Hermes integration

- [Hermes runtime](https://github.com/sarajo/circe/blob/main/src/main/hermes/real.ts): `src/main/hermes/real.ts`
- [Hermes paths](https://github.com/sarajo/circe/blob/main/src/main/hermes/runtime.ts): `src/main/hermes/runtime.ts`

### Other components

- **User**
- **Hermes CLI**
- **Model provider**

## Connections

- User → Wizard screens: chooses setup
- Wizard screens → Wizard bridge: sends actions
- Wizard bridge → Onboarding flow: dispatches IPC
- App coordinator → Window manager: creates windows
- App coordinator → Onboarding flow: starts onboarding
- App coordinator → Fleet discovery: lists profiles
- Fleet discovery → Hermes runtime: queries profiles
- Onboarding flow → Hermes runtime: checks and updates
- Onboarding flow → Identity derivation: derives identities
- Identity derivation → Fandom lookup: looks up references
- Onboarding flow → Portrait generation: requests portraits
- Portrait generation → Hermes runtime: generates images
- Onboarding flow → Coordinator skill: installs skill
- Coordinator skill → Hermes runtime: writes profile files
- Hermes runtime → Hermes paths: resolves home paths
- Hermes runtime → Hermes CLI: runs commands
- Hermes CLI → Model provider: uses configured model
- App coordinator → Tile lifecycle: opens fleet tiles
- Tile lifecycle → Window manager: creates tile windows
- Tile lifecycle → Hermes runtime: loads profile data
- Tile lifecycle → Session restore: restores conversations
- Tile lifecycle → Tab persistence: reads and writes tabs
- Tab persistence → Tile preferences: persists state
- Tile lifecycle → Agent protocol: manages agent sessions
- Agent protocol → Hermes runtime: connects to runtime
- Tile interface → Tile bridge: sends prompts
- Tile bridge → Tile lifecycle: dispatches tile actions
- Tile lifecycle → Tile bridge: sends updates
- Tile bridge → Tile interface: delivers events
- User → Tile interface: chats and approves
- Tile interface → Agent protocol: renders agent updates