# swordtraveller/codey architecture

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

- Interactive diagram: https://gitdiagram.com/swordtraveller/codey
- Repository: https://github.com/swordtraveller/codey

## Overview

Codey is an Electron desktop agent for conversation, project work, and coding. The main workflow runs from the renderer through the preload IPC bridge to the main-process development handler, which manages conversation history and context, invokes the agent and its tools, and persists results. Major documented branches include model selection, image input and web search, layered context management with Rhai customization and debugging, and encrypted conversation handover through an optional bridge service. The sampled excerpts establish key calls and IPC routes; several subsystem links are omitted where implementation wiring was not shown.

Main entry points: [`src/main/index.ts`](https://github.com/swordtraveller/codey/blob/main/src/main/index.ts) (Electron main), [`src/main/agent.ts`](https://github.com/swordtraveller/codey/blob/main/src/main/agent.ts) (Agent), [`src/renderer/src/App.tsx`](https://github.com/swordtraveller/codey/blob/main/src/renderer/src/App.tsx) (Conversation UI), [`src/preload/index.ts`](https://github.com/swordtraveller/codey/blob/main/src/preload/index.ts) (IPC preload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_app["Conversation UI<br/>[App.tsx]"]
  node_debug["Context debugger"]
  node_renderer["Renderer entry<br/>[main.tsx]"]
  node_preload["IPC preload<br/>[index.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_main["Electron main<br/>[index.ts]"]
  node_agent["Agent<br/>[agent.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
  node_sandbox["Code sandbox<br/>[sandbox.ts]"]
  node_workspace[("Project workspace<br/>[workspace.ts]")]
  node_conversations[("Conversation store")]
  node_modelconfig["Model settings<br/>[model-config.ts]"]
  node_image[("Image storage<br/>[image-store.ts]")]
end

subgraph group_context["Context management"]
  node_context["Context manager<br/>[context.ts]"]
  node_contextconfig["Context settings<br/>[context-config.ts]"]
  node_rhai["Rhai strategy<br/>[rhai-strategy.ts]"]
  node_rhairunner["Rhai runner<br/>[main.rs]"]
  node_contextdebug["Context debug API<br/>[index.ts]"]
end

subgraph group_handover["Conversation handover"]
  node_bridgeui["Handover client<br/>[main.ts]"]
  node_bridgeapi["Bridge API<br/>[server.mjs]"]
  node_bridgestore[("Bridge state<br/>[server.mjs]")]
  node_bridge["Handover sync<br/>[bridge.ts]"]
end

node_user(("User"))
node_modelservice["Model provider"]
node_remote(("Remote device"))

node_user -->|"uses"| node_app
node_renderer -->|"renders"| node_app
node_app -->|"IPC requests"| node_preload
node_debug -->|"debug IPC"| node_preload
node_preload -->|"forwards IPC"| node_main
node_main -->|"runs development"| node_agent
node_main -->|"loads and saves"| node_workspace
node_main -->|"reads history"| node_conversations
node_main -->|"resolves model"| node_modelconfig
node_main -->|"resolves strategy"| node_contextconfig
node_main -->|"prepares context"| node_context
node_context -->|"applies custom strategy"| node_rhai
node_rhai -.->|"executes script"| node_rhairunner
node_agent -->|"requests completion"| node_modelservice
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"runs code"| node_sandbox
node_agent -.->|"uses attachments"| node_image
node_main -->|"serves debug actions"| node_contextdebug
node_debug -->|"requests overview and edits"| node_contextdebug
node_main -->|"syncs projects"| node_bridge
node_bridge -->|"sends handover data"| node_bridgeapi
node_bridgeui -->|"requests and fetches"| node_bridgeapi
node_bridgeapi -->|"persists channel state"| node_bridgestore
node_remote -->|"pairs and views"| node_bridgeui

click node_app "https://github.com/swordtraveller/codey/blob/main/src/renderer/src/App.tsx"
click node_debug "https://github.com/swordtraveller/codey/blob/main/src/renderer/src/ContextDebugApp.tsx"
click node_renderer "https://github.com/swordtraveller/codey/blob/main/src/renderer/src/main.tsx"
click node_preload "https://github.com/swordtraveller/codey/blob/main/src/preload/index.ts"
click node_main "https://github.com/swordtraveller/codey/blob/main/src/main/index.ts"
click node_agent "https://github.com/swordtraveller/codey/blob/main/src/main/agent.ts"
click node_tools "https://github.com/swordtraveller/codey/blob/main/src/main/tools.ts"
click node_sandbox "https://github.com/swordtraveller/codey/blob/main/src/main/sandbox.ts"
click node_workspace "https://github.com/swordtraveller/codey/blob/main/src/main/workspace.ts"
click node_conversations "https://github.com/swordtraveller/codey/blob/main/src/main/conversation-store.ts"
click node_modelconfig "https://github.com/swordtraveller/codey/blob/main/src/main/model-config.ts"
click node_context "https://github.com/swordtraveller/codey/blob/main/src/main/context.ts"
click node_contextconfig "https://github.com/swordtraveller/codey/blob/main/src/main/context-config.ts"
click node_rhai "https://github.com/swordtraveller/codey/blob/main/src/main/rhai-strategy.ts"
click node_rhairunner "https://github.com/swordtraveller/codey/blob/main/native/rhai-runner/src/main.rs"
click node_contextdebug "https://github.com/swordtraveller/codey/blob/main/src/main/index.ts"
click node_image "https://github.com/swordtraveller/codey/blob/main/src/main/image-store.ts"
click node_bridgeui "https://github.com/swordtraveller/codey/blob/main/handover/src/main.ts"
click node_bridgeapi "https://github.com/swordtraveller/codey/blob/main/bridge/server.mjs"
click node_bridgestore "https://github.com/swordtraveller/codey/blob/main/bridge/server.mjs"
click node_bridge "https://github.com/swordtraveller/codey/blob/main/src/main/bridge.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_app,node_debug,node_renderer,node_preload,node_user toneBlue
class node_main,node_agent,node_tools,node_sandbox,node_workspace,node_conversations,node_modelconfig,node_image toneAmber
class node_context,node_contextconfig,node_rhai,node_rhairunner,node_contextdebug toneMint
class node_bridgeui,node_bridgeapi,node_bridgestore,node_bridge toneRose
class node_modelservice,node_remote toneIndigo
```

## Components

### Desktop interface

- [Conversation UI](https://github.com/swordtraveller/codey/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Context debugger](https://github.com/swordtraveller/codey/blob/main/src/renderer/src/ContextDebugApp.tsx): `src/renderer/src/ContextDebugApp.tsx`
- [Renderer entry](https://github.com/swordtraveller/codey/blob/main/src/renderer/src/main.tsx): `src/renderer/src/main.tsx`
- [IPC preload](https://github.com/swordtraveller/codey/blob/main/src/preload/index.ts): `src/preload/index.ts`

### Agent runtime

- [Electron main](https://github.com/swordtraveller/codey/blob/main/src/main/index.ts): `src/main/index.ts`
- [Agent](https://github.com/swordtraveller/codey/blob/main/src/main/agent.ts): `src/main/agent.ts`
- [Agent tools](https://github.com/swordtraveller/codey/blob/main/src/main/tools.ts): `src/main/tools.ts`
- [Code sandbox](https://github.com/swordtraveller/codey/blob/main/src/main/sandbox.ts): `src/main/sandbox.ts`
- [Project workspace](https://github.com/swordtraveller/codey/blob/main/src/main/workspace.ts): `src/main/workspace.ts`
- [Conversation store](https://github.com/swordtraveller/codey/blob/main/src/main/conversation-store.ts): `src/main/conversation-store.ts`
- [Model settings](https://github.com/swordtraveller/codey/blob/main/src/main/model-config.ts): `src/main/model-config.ts`
- [Image storage](https://github.com/swordtraveller/codey/blob/main/src/main/image-store.ts): `src/main/image-store.ts`

### Context management

- [Context manager](https://github.com/swordtraveller/codey/blob/main/src/main/context.ts): `src/main/context.ts`
- [Context settings](https://github.com/swordtraveller/codey/blob/main/src/main/context-config.ts): `src/main/context-config.ts`
- [Rhai strategy](https://github.com/swordtraveller/codey/blob/main/src/main/rhai-strategy.ts): `src/main/rhai-strategy.ts`
- [Rhai runner](https://github.com/swordtraveller/codey/blob/main/native/rhai-runner/src/main.rs): `native/rhai-runner/src/main.rs`
- [Context debug API](https://github.com/swordtraveller/codey/blob/main/src/main/index.ts): `src/main/index.ts`

### Conversation handover

- [Handover client](https://github.com/swordtraveller/codey/blob/main/handover/src/main.ts): `handover/src/main.ts`
- [Bridge API](https://github.com/swordtraveller/codey/blob/main/bridge/server.mjs): `bridge/server.mjs`
- [Bridge state](https://github.com/swordtraveller/codey/blob/main/bridge/server.mjs): `bridge/server.mjs`
- [Handover sync](https://github.com/swordtraveller/codey/blob/main/src/main/bridge.ts): `src/main/bridge.ts`

### Other components

- **User**
- **Model provider**
- **Remote device**

## Connections

- User → Conversation UI: uses
- Renderer entry → Conversation UI: renders
- Conversation UI → IPC preload: IPC requests
- Context debugger → IPC preload: debug IPC
- IPC preload → Electron main: forwards IPC
- Electron main → Agent: runs development
- Electron main → Project workspace: loads and saves
- Electron main → Conversation store: reads history
- Electron main → Model settings: resolves model
- Electron main → Context settings: resolves strategy
- Electron main → Context manager: prepares context
- Context manager → Rhai strategy: applies custom strategy
- Rhai strategy → Rhai runner: executes script
- Agent → Model provider: requests completion
- Agent → Agent tools: dispatches tools
- Agent tools → Code sandbox: runs code
- Agent → Image storage: uses attachments
- Electron main → Context debug API: serves debug actions
- Context debugger → Context debug API: requests overview and edits
- Electron main → Handover sync: syncs projects
- Handover sync → Bridge API: sends handover data
- Handover client → Bridge API: requests and fetches
- Bridge API → Bridge state: persists channel state
- Remote device → Handover client: pairs and views