# pal-ai-lab/coopanion architecture

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

- Interactive diagram: https://gitdiagram.com/pal-ai-lab/coopanion
- Repository: https://github.com/pal-ai-lab/coopanion

## Overview

Coopanion is a cross-platform desktop companion: the user chats with Coo by typing or voice, and can optionally grant it screen-reading and computer-control abilities. Electron starts the Core process and hosts the settings console; Core coordinates the pet, model connections, memory, reminders, and extensions. The graph retains the README’s major product branches, including speech, computer use, figure packs, and Worlds. Several runtime modules were not sampled, so their internal call paths are omitted; documented relationships are marked with README evidence.

Main entry points: [`core/companion.ts`](https://github.com/pal-ai-lab/coopanion/blob/main/core/companion.ts) (Core service), [`packages/cortico-world-desktop-pet/src/chat.ts`](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/chat.ts) (Chat experience), [`console/index.ts`](https://github.com/pal-ai-lab/coopanion/blob/main/console/index.ts) (Settings console), [`packages/cortico-world-desktop-pet/src/asr/system-recognizer.ts`](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/asr/system-recognizer.ts) (Speech recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop runtime"]
  node_electron["Electron app<br/>[main.cjs]"]
  node_core["Core service<br/>[companion.ts]"]
end

subgraph group_console["Settings console"]
  node_settings["Settings console<br/>[index.ts]"]
  node_console_api["Console API client<br/>[api.ts]"]
  node_console_pages["Advanced pages<br/>[host.ts]"]
end

subgraph group_companion["Companion experience"]
  node_pet_world["Desktop pet<br/>[world.ts]"]
  node_pet_webui["Pet WebUI<br/>[client.ts]"]
  node_memory["Persona and memory<br/>[guide.ts]"]
  node_reminders["Reminders<br/>[alarms.ts]"]
end

subgraph group_models["Model and voice"]
  node_provider["Model providers<br/>[index.ts]"]
  node_chat["Chat experience<br/>[chat.ts]"]
  node_speech["Speech recognition"]
  node_speech_output["Speech output<br/>[index.ts]"]
end

subgraph group_extensions["Extensions and control"]
  node_computer_use["Computer use<br/>[cua.ts]"]
  node_engine["OS input engine<br/>[engine-child.ts]"]
  node_figure_packs["Figure packs<br/>[pack-import.ts]"]
  node_world_extensions["World extensions<br/>[gallery.ts]"]
end

node_user(("User"))
node_external_model{{"Model service"}}
node_transcription{{"Transcription service"}}

node_user -->|"starts app"| node_electron
node_electron -->|"starts Core"| node_core
node_user -->|"opens settings"| node_settings
node_settings -->|"makes requests"| node_console_api
node_console_api -->|"calls WebUI API"| node_core
node_settings -->|"mounts pages"| node_console_pages
node_user -->|"types or speaks"| node_chat
node_chat -->|"requests responses"| node_provider
node_provider -->|"uses model API"| node_external_model
node_user -->|"holds talk key"| node_speech
node_speech -->|"provides transcript"| node_chat
node_speech -.->|"optionally transcribes"| node_transcription
node_chat -->|"speaks replies"| node_speech_output
node_core -->|"manages memory"| node_memory
node_core -->|"sets alarms"| node_reminders
node_core -->|"runs desktop pet"| node_pet_world
node_user -->|"configures pet"| node_pet_webui
node_user -->|"permits computer use"| node_computer_use
node_computer_use -->|"dispatches OS actions"| node_engine
node_user -->|"imports figure packs"| node_figure_packs
node_user -->|"browses extensions"| node_world_extensions

click node_electron "https://github.com/pal-ai-lab/coopanion/blob/main/app/main.cjs"
click node_core "https://github.com/pal-ai-lab/coopanion/blob/main/core/companion.ts"
click node_settings "https://github.com/pal-ai-lab/coopanion/blob/main/console/index.ts"
click node_console_api "https://github.com/pal-ai-lab/coopanion/blob/main/console/base/api.ts"
click node_console_pages "https://github.com/pal-ai-lab/coopanion/blob/main/console/advanced/console-pages/host.ts"
click node_pet_world "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/world.ts"
click node_pet_webui "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/webui/client.ts"
click node_memory "https://github.com/pal-ai-lab/coopanion/blob/main/core/guide.ts"
click node_reminders "https://github.com/pal-ai-lab/coopanion/blob/main/core/alarms.ts"
click node_provider "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-provider-coo/src/index.ts"
click node_chat "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/chat.ts"
click node_speech "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/asr/system-recognizer.ts"
click node_speech_output "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/speech/index.ts"
click node_computer_use "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/cua/cua.ts"
click node_engine "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/cua/engine-child.ts"
click node_figure_packs "https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/pack-import.ts"
click node_world_extensions "https://github.com/pal-ai-lab/coopanion/blob/main/console/advanced/features/extensions/gallery.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_electron,node_core,node_user toneBlue
class node_settings,node_console_api,node_console_pages toneAmber
class node_pet_world,node_pet_webui,node_memory,node_reminders toneMint
class node_provider,node_chat,node_speech,node_speech_output toneRose
class node_computer_use,node_engine,node_figure_packs,node_world_extensions,node_external_model,node_transcription toneIndigo
```

## Components

### Desktop runtime

- [Electron app](https://github.com/pal-ai-lab/coopanion/blob/main/app/main.cjs): `app/main.cjs`
- [Core service](https://github.com/pal-ai-lab/coopanion/blob/main/core/companion.ts): `core/companion.ts`

### Settings console

- [Settings console](https://github.com/pal-ai-lab/coopanion/blob/main/console/index.ts): `console/index.ts`
- [Console API client](https://github.com/pal-ai-lab/coopanion/blob/main/console/base/api.ts): `console/base/api.ts`
- [Advanced pages](https://github.com/pal-ai-lab/coopanion/blob/main/console/advanced/console-pages/host.ts): `console/advanced/console-pages/host.ts`

### Companion experience

- [Desktop pet](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/world.ts): `packages/cortico-world-desktop-pet/src/world.ts`
- [Pet WebUI](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/webui/client.ts): `packages/cortico-world-desktop-pet/src/webui/client.ts`
- [Persona and memory](https://github.com/pal-ai-lab/coopanion/blob/main/core/guide.ts): `core/guide.ts`
- [Reminders](https://github.com/pal-ai-lab/coopanion/blob/main/core/alarms.ts): `core/alarms.ts`

### Model and voice

- [Model providers](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-provider-coo/src/index.ts): `packages/cortico-provider-coo/src/index.ts`
- [Chat experience](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/chat.ts): `packages/cortico-world-desktop-pet/src/chat.ts`
- [Speech recognition](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/asr/system-recognizer.ts): `packages/cortico-world-desktop-pet/src/asr/system-recognizer.ts`
- [Speech output](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/speech/index.ts): `packages/cortico-world-desktop-pet/src/speech/index.ts`

### Extensions and control

- [Computer use](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/cua/cua.ts): `packages/cortico-world-desktop-pet/src/cua/cua.ts`
- [OS input engine](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/cua/engine-child.ts): `packages/cortico-world-desktop-pet/src/cua/engine-child.ts`
- [Figure packs](https://github.com/pal-ai-lab/coopanion/blob/main/packages/cortico-world-desktop-pet/src/pack-import.ts): `packages/cortico-world-desktop-pet/src/pack-import.ts`
- [World extensions](https://github.com/pal-ai-lab/coopanion/blob/main/console/advanced/features/extensions/gallery.ts): `console/advanced/features/extensions/gallery.ts`

### Other components

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

## Connections

- User → Electron app: starts app
- Electron app → Core service: starts Core (evidence: `app/main.cjs`)
- User → Settings console: opens settings
- Settings console → Console API client: makes requests (evidence: `console/index.ts`)
- Console API client → Core service: calls WebUI API
- Settings console → Advanced pages: mounts pages (evidence: `console/index.ts`)
- User → Chat experience: types or speaks
- Chat experience → Model providers: requests responses
- Model providers → Model service: uses model API
- User → Speech recognition: holds talk key
- Speech recognition → Chat experience: provides transcript
- Speech recognition → Transcription service: optionally transcribes
- Chat experience → Speech output: speaks replies
- Core service → Persona and memory: manages memory
- Core service → Reminders: sets alarms
- Core service → Desktop pet: runs desktop pet
- User → Pet WebUI: configures pet
- User → Computer use: permits computer use
- Computer use → OS input engine: dispatches OS actions (evidence: `packages/cortico-world-desktop-pet/src/cua/engine-child.ts`)
- User → Figure packs: imports figure packs
- User → World extensions: browses extensions