# playa-cyrene/cyrene-agent architecture

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

- Interactive diagram: https://gitdiagram.com/playa-cyrene/cyrene-agent
- Repository: https://github.com/playa-cyrene/cyrene-agent

## Overview

Cyrene-Agent is a Windows Live2D desktop companion whose central workflow is user chat through the renderer and main-process agent runtime to an LLM and, in Work/Code/Learn, optional tools; replies and run state return to the UI. The repository also documents long-term memory, voice, external chat channels, plugins, learning, proactive delivery, and desktop character interaction. Edges are limited to relationships described in the README or visible in the provided excerpts; several feature implementations were not sampled, so their internal wiring is not asserted.

Main entry points: [`src/main/orchestrator/harness/cyrene-harness.ts`](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/harness/cyrene-harness.ts) (CyreneHarness), [`src/renderer/react/features/chat/pages/run/AgentRunController.ts`](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/pages/run/AgentRunController.ts) (Chat UI), [`src/preload/index.ts`](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/preload/index.ts) (Renderer bridge), [`src/renderer/live2d/manager.ts`](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/live2d/manager.ts) (Live2D character)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_chat_ui["Chat UI"]
  node_chat_views["Chat views"]
  node_chat_types["Chat state types<br/>[chat-types.ts]"]
  node_preload["Renderer bridge<br/>[index.ts]"]
  node_ipc_contract["IPC contracts<br/>[ipc-channels.ts]"]
  node_live2d["Live2D character<br/>[manager.ts]"]
  node_live2d_interaction["Character interaction<br/>[interaction.ts]"]
  node_renderer_base["Renderer base<br/>[renderer-base.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agui["Agent UI bridge<br/>[agui-bridge.ts]"]
  node_run_controller["Run controller"]
  node_harness["CyreneHarness<br/>[cyrene-harness.ts]"]
  node_rounds["Run presentation<br/>[agent-rounds.ts]"]
  node_presentation["Run status"]
  node_transcript[("Conversation transcript")]
  node_vendors["Model vendors<br/>[index.ts]"]
  node_structured_profiles["Output profiles<br/>[profiles.ts]"]
  node_structured_runner["Structured output<br/>[runner.ts]"]
  node_context_usage["Context usage<br/>[context-usage.ts]"]
  node_token_usage[("Token accounting")]
end

subgraph group_capabilities["Knowledge and tools"]
  node_memory["DMAE memory<br/>[memory-manager.ts]"]
  node_rag["RAG retrieval<br/>[retriever.ts]"]
  node_skills_tools["Agent tools"]
  node_learning["Learn workspace"]
end

subgraph group_integrations["Channels and extensions"]
  node_channels["Chat channels<br/>[dispatcher.ts]"]
  node_plugins["Plugin runtime<br/>[manager.ts]"]
  node_plugin_contract["Plugin SDK contract"]
  node_proactive["Proactive delivery"]
end

subgraph group_services["Voice and services"]
  node_voice["Speech services<br/>[tts-dispatcher.ts]"]
  node_asr["Speech recognition<br/>[asr-dispatcher.ts]"]
  node_screenshot["Screenshot helper<br/>[app.rs]"]
  node_stickers["Sticker matching"]
  node_music["Music player<br/>[music-service.ts]"]
end

node_user(("User"))

node_user -->|"sends message"| node_chat_ui
node_chat_ui -->|"uses bridge"| node_preload
node_preload -->|"invokes channels"| node_ipc_contract
node_chat_ui -->|"controls run"| node_run_controller
node_run_controller -.->|"starts run"| node_agui
node_agui -.->|"dispatches run"| node_harness
node_harness -->|"requests model"| node_vendors
node_harness -->|"dispatches tools"| node_skills_tools
node_harness -->|"checkpoints run"| node_transcript
node_run_controller -->|"renders rounds"| node_rounds
node_run_controller -->|"resolves status"| node_presentation
node_chat_ui -.->|"presents messages"| node_chat_views
node_chat_views -->|"uses message shapes"| node_chat_types
node_preload -.->|"exposes character APIs"| node_live2d
node_live2d -->|"uses hit areas"| node_live2d_interaction
node_live2d -.->|"uses shared base"| node_renderer_base
node_structured_runner -->|"uses profiles"| node_structured_profiles
node_vendors -.->|"supports structured output"| node_structured_runner
node_harness -->|"emits snapshots"| node_context_usage
node_harness -.->|"accounts usage"| node_token_usage
node_harness -->|"uses long-term memory"| node_memory
node_harness -.->|"retrieves knowledge"| node_rag
node_skills_tools -->|"supports Learn mode"| node_learning
node_channels -->|"shares agent capability"| node_harness
node_plugins -->|"implements plugin API"| node_plugin_contract
node_proactive -->|"delivers to channels"| node_channels
node_voice -->|"speaks replies"| node_user
node_user -->|"provides speech"| node_asr
node_screenshot -.->|"provides captures"| node_chat_ui
node_stickers -->|"enriches replies"| node_chat_ui
node_music -->|"provides music tools"| node_skills_tools

click node_chat_ui "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/pages/run/AgentRunController.ts"
click node_chat_views "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/ChatMessageList.tsx"
click node_chat_types "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/chat-types.ts"
click node_preload "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/preload/index.ts"
click node_ipc_contract "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/ipc-channels.ts"
click node_live2d "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/live2d/manager.ts"
click node_live2d_interaction "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/live2d/interaction.ts"
click node_renderer_base "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/renderer-base.ts"
click node_agui "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/agui-bridge.ts"
click node_run_controller "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/pages/run/AgentRunController.ts"
click node_harness "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/harness/cyrene-harness.ts"
click node_rounds "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/agent-rounds.ts"
click node_presentation "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/run-presentation.ts"
click node_transcript "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/conversation-transcript-coordinator.ts"
click node_vendors "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/vendors/index.ts"
click node_structured_profiles "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/structured-output/profiles.ts"
click node_structured_runner "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/structured-output/runner.ts"
click node_context_usage "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/context-usage.ts"
click node_token_usage "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/token-usage-store.ts"
click node_memory "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/memory/memory-manager.ts"
click node_rag "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/rag/retriever.ts"
click node_skills_tools "https://github.com/playa-cyrene/cyrene-agent/tree/master/src/main/orchestrator/tools"
click node_learning "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/learn/obsidian/obsidian-workspace-service.ts"
click node_channels "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/channels/dispatcher.ts"
click node_plugins "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/plugins/manager.ts"
click node_plugin_contract "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/plugin-management.ts"
click node_proactive "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/proactive/proactive-service.ts"
click node_voice "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/tts/tts-dispatcher.ts"
click node_asr "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/asr/asr-dispatcher.ts"
click node_screenshot "https://github.com/playa-cyrene/cyrene-agent/blob/master/native/cyrene-screenshot/src/app.rs"
click node_stickers "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/sticker-descriptions.ts"
click node_music "https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/music/music-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_chat_ui,node_chat_views,node_chat_types,node_preload,node_ipc_contract,node_live2d,node_live2d_interaction,node_renderer_base,node_user toneBlue
class node_agui,node_run_controller,node_harness,node_rounds,node_presentation,node_transcript,node_vendors,node_structured_profiles,node_structured_runner,node_context_usage,node_token_usage toneAmber
class node_memory,node_rag,node_skills_tools,node_learning toneMint
class node_channels,node_plugins,node_plugin_contract,node_proactive toneRose
class node_voice,node_asr,node_screenshot,node_stickers,node_music toneIndigo
```

## Components

### Desktop experience

- [Chat UI](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/pages/run/AgentRunController.ts): `src/renderer/react/features/chat/pages/run/AgentRunController.ts`
- [Chat views](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/ChatMessageList.tsx): `src/renderer/react/features/chat/components/ChatMessageList.tsx`
- [Chat state types](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/chat-types.ts): `src/shared/chat-types.ts`
- [Renderer bridge](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/preload/index.ts): `src/preload/index.ts`
- [IPC contracts](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/ipc-channels.ts): `src/shared/ipc-channels.ts`
- [Live2D character](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/live2d/manager.ts): `src/renderer/live2d/manager.ts`
- [Character interaction](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/live2d/interaction.ts): `src/renderer/live2d/interaction.ts`
- [Renderer base](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/renderer-base.ts): `src/shared/renderer-base.ts`

### Agent runtime

- [Agent UI bridge](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/agui-bridge.ts): `src/main/agui-bridge.ts`
- [Run controller](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/pages/run/AgentRunController.ts): `src/renderer/react/features/chat/pages/run/AgentRunController.ts`
- [CyreneHarness](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/harness/cyrene-harness.ts): `src/main/orchestrator/harness/cyrene-harness.ts`
- [Run presentation](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/agent-rounds.ts): `src/renderer/react/features/chat/components/agent-rounds.ts`
- [Run status](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/renderer/react/features/chat/components/run-presentation.ts): `src/renderer/react/features/chat/components/run-presentation.ts`
- [Conversation transcript](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/conversation-transcript-coordinator.ts): `src/main/orchestrator/conversation-transcript-coordinator.ts`
- [Model vendors](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/vendors/index.ts): `src/main/orchestrator/vendors/index.ts`
- [Output profiles](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/structured-output/profiles.ts): `src/main/orchestrator/structured-output/profiles.ts`
- [Structured output](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/orchestrator/structured-output/runner.ts): `src/main/orchestrator/structured-output/runner.ts`
- [Context usage](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/context-usage.ts): `src/shared/context-usage.ts`
- [Token accounting](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/token-usage-store.ts): `src/main/token-usage-store.ts`

### Knowledge and tools

- [DMAE memory](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/memory/memory-manager.ts): `src/main/memory/memory-manager.ts`
- [RAG retrieval](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/rag/retriever.ts): `src/main/rag/retriever.ts`
- [Agent tools](https://github.com/playa-cyrene/cyrene-agent/tree/master/src/main/orchestrator/tools): `src/main/orchestrator/tools`
- [Learn workspace](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/learn/obsidian/obsidian-workspace-service.ts): `src/main/learn/obsidian/obsidian-workspace-service.ts`

### Channels and extensions

- [Chat channels](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/channels/dispatcher.ts): `src/main/channels/dispatcher.ts`
- [Plugin runtime](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/plugins/manager.ts): `src/plugins/manager.ts`
- [Plugin SDK contract](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/shared/plugin-management.ts): `src/shared/plugin-management.ts`
- [Proactive delivery](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/proactive/proactive-service.ts): `src/main/proactive/proactive-service.ts`

### Voice and services

- [Speech services](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/tts/tts-dispatcher.ts): `src/main/tts/tts-dispatcher.ts`
- [Speech recognition](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/asr/asr-dispatcher.ts): `src/main/asr/asr-dispatcher.ts`
- [Screenshot helper](https://github.com/playa-cyrene/cyrene-agent/blob/master/native/cyrene-screenshot/src/app.rs): `native/cyrene-screenshot/src/app.rs`
- [Sticker matching](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/sticker-descriptions.ts): `src/main/sticker-descriptions.ts`
- [Music player](https://github.com/playa-cyrene/cyrene-agent/blob/master/src/main/music/music-service.ts): `src/main/music/music-service.ts`

### Other components

- **User**

## Connections

- User → Chat UI: sends message (evidence: `README.md`)
- Chat UI → Renderer bridge: uses bridge (evidence: `src/renderer/react/features/chat/pages/run/AgentRunController.ts`)
- Renderer bridge → IPC contracts: invokes channels (evidence: `src/preload/index.ts`)
- Chat UI → Run controller: controls run (evidence: `src/renderer/react/features/chat/pages/run/AgentRunController.ts`)
- Run controller → Agent UI bridge: starts run
- Agent UI bridge → CyreneHarness: dispatches run
- CyreneHarness → Model vendors: requests model (evidence: `README.md`)
- CyreneHarness → Agent tools: dispatches tools (evidence: `README.md`)
- CyreneHarness → Conversation transcript: checkpoints run (evidence: `README.md`)
- Run controller → Run presentation: renders rounds (evidence: `src/renderer/react/features/chat/pages/run/AgentRunController.ts`)
- Run controller → Run status: resolves status (evidence: `src/renderer/react/features/chat/pages/run/AgentRunController.ts`)
- Chat UI → Chat views: presents messages (evidence: `src/renderer/react/features/chat/pages/run/AgentRunController.ts`)
- Chat views → Chat state types: uses message shapes (evidence: `src/renderer/react/features/chat/components/TaskSessionInspector.tsx`)
- Renderer bridge → Live2D character: exposes character APIs
- Live2D character → Character interaction: uses hit areas (evidence: `src/renderer/live2d/manager.ts`)
- Live2D character → Renderer base: uses shared base
- Structured output → Output profiles: uses profiles (evidence: `src/main/cita/remote-semantic-engine.ts`)
- Model vendors → Structured output: supports structured output
- CyreneHarness → Context usage: emits snapshots (evidence: `README.md`)
- CyreneHarness → Token accounting: accounts usage
- CyreneHarness → DMAE memory: uses long-term memory (evidence: `README.md`)
- CyreneHarness → RAG retrieval: retrieves knowledge
- Agent tools → Learn workspace: supports Learn mode (evidence: `README.md`)
- Chat channels → CyreneHarness: shares agent capability (evidence: `README.md`)
- Plugin runtime → Plugin SDK contract: implements plugin API (evidence: `src/plugins/manager.ts`)
- Proactive delivery → Chat channels: delivers to channels (evidence: `README.md`)
- Speech services → User: speaks replies (evidence: `README.md`)
- User → Speech recognition: provides speech (evidence: `README.md`)
- Screenshot helper → Chat UI: provides captures
- Sticker matching → Chat UI: enriches replies (evidence: `README.md`)
- Music player → Agent tools: provides music tools (evidence: `README.md`)