# rainnoon/oc-claw architecture

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

- Interactive diagram: https://gitdiagram.com/rainnoon/oc-claw
- Repository: https://github.com/rainnoon/oc-claw

## Overview

1. **Repository shape**
   - This is a monorepo with three distinct product surfaces:
     - `frontend/`: the Tauri desktop app
     - `website/`: the marketing/documentation site
     - `extensions/cursor/`: a Cursor-specific extension hook
   - The desktop app is the core product; the other pieces support acquisition and editor integration.

2. **Desktop app runtime boundary**
   - The app is a **Tauri v2 shell**: a **React + TypeScript** UI in `frontend/src` backed by a **Rust** native layer in `frontend/src-tauri`.
   - The frontend owns rendering, state, and user interaction.
   - The Rust side owns system-level concerns: window positioning/management, native platform integration, SSH tunneling, and API communication.

3. **Core product model: “activity drives pet state”**
   - OC-Claw’s central loop is: external agent activity → normalized activity state → pet animation/sound/UI updates.
   - The README’s flow is reflected in the code split:
     - polling OpenClaw session files
     - listening to Claude Code, Codex, and Cursor hooks
     - converting all inputs into a shared activity model
     - driving the desktop pet and detail panel from that model

4. **Agent ingestion layer**
   - `frontend/src/lib/agents.ts`, `pipeline.ts`, and `types.ts` suggest a unified ingestion/normalization layer for multiple agents.
   - OpenClaw appears to be discovered via local session files and health polling.
   - Claude Code / Codex / Cursor are treated as hook-based event sources, likely parsed into the same internal activity pipeline.
   - This boundary is important: each external tool has its own source format, but the UI consumes one common state model.

5. **State and persistence**
   - `frontend/src/lib/store.ts` and `petStore.ts` indicate client-side persistence for app state and pet configuration.
   - `codexPet.ts` suggests special handling for Codex-related character mapping or assets.
   - The app likely persists user preferences, selected pet assignments, and UI settings locally rather than relying on a server.

6. **Pet rendering and interaction**
   - Visual rendering is concentrated in components like `SpritePet.tsx`, `MiniPetMascot.tsx`, and `DemoMascot.tsx`.
   - Interaction surfaces include `PetContextMenu.tsx`, `PetPicker.tsx`, and the `Mini.tsx`/`App.tsx` entry points.
   - The desktop pet is not just decorative: it reacts to activity, can sleep/idle, and appears in different modes such as notch/taskbar-sized views versus expanded views.

7. **Character/content system**
   - The app ships a large built-in content library under `frontend/public/assets/builtin`.
   - Built-in pets include per-character `pet.json` definitions plus media assets such as motion files, audio, and manifest files.
   - This implies a data-driven character system where animation behavior and presentation are defined by asset bundles rather than hardcoded per character.

8. **Customization and creation tools**
   - `CreateCharacterModal.tsx`, `SettingsTab.tsx`, `GifMakerTab.tsx`, and `UpdateModal.tsx` show that the desktop app supports authoring and managing content, not just viewing it.
   - The background assets and crop-related features in the README align with `public/assets/backgrounds` and utility code like `gifExport.ts` and `spriteUtils.ts`.
   - The product therefore has a clear separation between:
     - runtime activity visualization
     - user customization of characters, backgrounds, and media output

9. **User-facing data and analytics**
   - `AgentDetailView.tsx` and `ClaudeStatsView.tsx` indicate a detail panel for session history, chat logs, and usage metrics.
   - The README mentions daily calls/tokens charts and live conversations, so the app is both a mascot and an activity dashboard.
   - This means the UI has at least two major panes: a compact animated surface and an expanded diagnostics/insight surface.

10. **Platform integration and remote access**
   - The Rust backend is explicitly responsible for SSH tunneling and API communication, which matters because OC-Claw is not only local-machine aware.
   - The app can connect to remote OpenClaw instances running on servers, so the architecture includes a local UI talking to local and remote agent sources through native transport layers.

11. **Cursor extension boundary**
   - `extensions/cursor/` is a separate integration package with its own `extension.js` and `package.json`.
   - Its role is likely to emit or relay editor events from Cursor into the desktop app’s activity pipeline.
   - Architecturally, this is an adapter layer between the editor and the shared agent-state model.

12. **Website boundary**
   - `website/` is an Astro-based static site, separate from the desktop app runtime.
   - It provides multilingual landing pages, download/update metadata, images, and public-facing product content.
   - `website/public/update/latest.json` suggests it also participates in release/update discovery, but it is not part of the core activity loop.

13. **Localization and distribution**
   - Both the desktop app and website have multilingual content (`en`, `es`, `fr`, `ja`, `ko`, `zh`), so localization is a first-class concern.
   - Installation scripts (`install.sh`, `install.ps1`) indicate cross-platform distribution support, matching the macOS/Windows target described in the README.

14. **Key architectural takeaway**
   - The cleanest diagram is: multiple external agent sources feed a shared activity pipeline; the Tauri backend handles platform/system integration; the React frontend renders the pet, analytics, and customization UI; assets define most character behavior; and the website/extension are separate integration surfaces around the core desktop product.

Main entry points: [`frontend/src/lib/pipeline.ts`](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/pipeline.ts) (Activity pipeline), [`frontend/src/lib/petStore.ts`](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/petStore.ts) (Pet store), [`frontend/src/components/SpritePet.tsx`](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/SpritePet.tsx) (Pet rendering), [`frontend/src`](https://github.com/rainnoon/oc-claw/tree/main/frontend/src) (Tauri shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_desktop_shell["Tauri shell<br/>desktop runtime"]
  node_react_ui["React UI<br/>frontend app<br/>[App.tsx]"]
  node_native_backend["Rust backend<br/>native core"]
  node_activity_pipeline{{"Activity pipeline<br/>event normalization<br/>[pipeline.ts]"}}
  node_agent_sources["Agent sources<br/>ingestion layer<br/>[agents.ts]"]
  node_app_state[("App store<br/>client state<br/>[store.ts]")]
  node_pet_state[("Pet store<br/>pet state<br/>[petStore.ts]")]
  node_detail_views["Insight panels<br/>dashboard views"]
  node_pet_rendering["Pet rendering<br/>mascot views<br/>[SpritePet.tsx]"]
  node_pet_controls["Pet controls<br/>interaction UI<br/>[PetContextMenu.tsx]"]
  node_creation_tools["Creation tools<br/>authoring ui"]
end

subgraph group_content["Content system"]
  node_character_assets[("Built-in pets<br/>content bundle")]
  node_prompt_assets["Prompt assets<br/>behavior assets"]
  node_media_tools["Media tools<br/>render utilities<br/>[gifExport.ts]"]
end

subgraph group_surfaces["Support surfaces"]
  node_cursor_extension["Cursor hook<br/>editor extension<br/>[extension.js]"]
  node_website_site["Marketing site<br/>astro site"]
  node_website_updates["Update feed<br/>release metadata<br/>[latest.json]"]
end

node_desktop_shell -->|"hosts"| node_react_ui
node_desktop_shell -->|"pairs with"| node_native_backend
node_react_ui -->|"consumes"| node_activity_pipeline
node_agent_sources -->|"feeds"| node_activity_pipeline
node_native_backend -->|"bridges"| node_activity_pipeline
node_activity_pipeline -->|"drives"| node_pet_rendering
node_activity_pipeline -->|"updates"| node_detail_views
node_activity_pipeline -->|"persists"| node_app_state
node_app_state -->|"contains"| node_pet_state
node_pet_state -->|"configures"| node_pet_rendering
node_pet_controls -->|"edits"| node_pet_state
node_creation_tools -->|"manages"| node_character_assets
node_character_assets -->|"supplies"| node_pet_rendering
node_prompt_assets -->|"guides"| node_activity_pipeline
node_media_tools -->|"supports"| node_creation_tools
node_cursor_extension -->|"adapts"| node_agent_sources
node_website_site -->|"publishes"| node_website_updates

click node_desktop_shell "https://github.com/rainnoon/oc-claw/tree/main/frontend/src"
click node_react_ui "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/App.tsx"
click node_native_backend "https://github.com/rainnoon/oc-claw/tree/main/frontend/src-tauri/src"
click node_activity_pipeline "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/pipeline.ts"
click node_agent_sources "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/agents.ts"
click node_app_state "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/store.ts"
click node_pet_state "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/petStore.ts"
click node_detail_views "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/AgentDetailView.tsx"
click node_pet_rendering "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/SpritePet.tsx"
click node_pet_controls "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/PetContextMenu.tsx"
click node_creation_tools "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/CreateCharacterModal.tsx"
click node_character_assets "https://github.com/rainnoon/oc-claw/tree/main/frontend/public/assets/builtin"
click node_prompt_assets "https://github.com/rainnoon/oc-claw/tree/main/frontend/public/prompt"
click node_media_tools "https://github.com/rainnoon/oc-claw/blob/main/frontend/src/utils/gifExport.ts"
click node_cursor_extension "https://github.com/rainnoon/oc-claw/blob/main/extensions/cursor/extension.js"
click node_website_site "https://github.com/rainnoon/oc-claw/tree/main/website/src/pages"
click node_website_updates "https://github.com/rainnoon/oc-claw/blob/main/website/public/update/latest.json"

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_desktop_shell,node_react_ui,node_native_backend,node_activity_pipeline,node_agent_sources,node_app_state,node_pet_state,node_detail_views,node_pet_rendering,node_pet_controls,node_creation_tools toneBlue
class node_character_assets,node_prompt_assets,node_media_tools toneAmber
class node_cursor_extension,node_website_site,node_website_updates toneMint
```

## Components

### Desktop app

Core Tauri product: React frontend plus Rust backend, pet runtime, and local persistence.

- [Tauri shell](https://github.com/rainnoon/oc-claw/tree/main/frontend/src): desktop runtime · App entry and runtime boundary for the desktop product. · `frontend/src`
- [React UI](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/App.tsx): frontend app · Main interactive surface for pet display, settings, and detail views. · `frontend/src/App.tsx`
- [Rust backend](https://github.com/rainnoon/oc-claw/tree/main/frontend/src-tauri/src): native core · System integration layer for windowing, platform behavior, tunneling, and API communication. · `frontend/src-tauri/src`
- [Activity pipeline](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/pipeline.ts): event normalization · Shared model that turns agent and hook inputs into unified activity state. · `frontend/src/lib/pipeline.ts`
- [Agent sources](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/agents.ts): ingestion layer · Adapters for OpenClaw sessions and external agent hooks such as Claude Code, Codex, and Cursor. · `frontend/src/lib/agents.ts`
- [App store](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/store.ts): client state · Persistent desktop state, preferences, and local settings storage. · `frontend/src/lib/store.ts`
- [Pet store](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/lib/petStore.ts): pet state · Pet selection, configuration, and character-specific runtime state. · `frontend/src/lib/petStore.ts`
- [Insight panels](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/AgentDetailView.tsx): dashboard views · Session history, logs, and usage metrics shown in the expanded interface. · `frontend/src/components/AgentDetailView.tsx`
- [Pet rendering](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/SpritePet.tsx): mascot views · Animated mascot rendering and compact/notch-size presentation surfaces. · `frontend/src/components/SpritePet.tsx`
- [Pet controls](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/PetContextMenu.tsx): interaction UI · Context menu, picker, onboarding, and character management actions. · `frontend/src/components/PetContextMenu.tsx`
- [Creation tools](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/components/CreateCharacterModal.tsx): authoring ui · Character creation, settings, GIF export, and media customization features. · `frontend/src/components/CreateCharacterModal.tsx`

### Content system

Built-in pets, assets, prompts, audio, and rendering/export helpers that drive character behavior.

- [Built-in pets](https://github.com/rainnoon/oc-claw/tree/main/frontend/public/assets/builtin): content bundle · Data-driven character definitions and bundled media for multiple pets. · `frontend/public/assets/builtin`
- [Prompt assets](https://github.com/rainnoon/oc-claw/tree/main/frontend/public/prompt): behavior assets · Prompt and pipeline files used to steer pet behavior and states. · `frontend/public/prompt`
- [Media tools](https://github.com/rainnoon/oc-claw/blob/main/frontend/src/utils/gifExport.ts): render utilities · Helpers for sprite conversion, GIF export, and related media processing. · `frontend/src/utils/gifExport.ts`

### Support surfaces

Editor integration and public website that sit around the core desktop app.

- [Cursor hook](https://github.com/rainnoon/oc-claw/blob/main/extensions/cursor/extension.js): editor extension · Separate package that relays Cursor editor events into the shared activity model. · `extensions/cursor/extension.js`
- [Marketing site](https://github.com/rainnoon/oc-claw/tree/main/website/src/pages): astro site · Localized public website with landing pages, downloads, and release metadata. · `website/src/pages`
- [Update feed](https://github.com/rainnoon/oc-claw/blob/main/website/public/update/latest.json): release metadata · Public update discovery artifact used by the website and distribution flow. · `website/public/update/latest.json`

## Connections

- Tauri shell → React UI: hosts · The Tauri shell mounts the React frontend.
- Tauri shell → Rust backend: pairs with · The shell is backed by the Rust native layer.
- React UI → Activity pipeline: consumes · UI state and displays are driven from normalized activity.
- Agent sources → Activity pipeline: feeds · External agent hooks and session sources enter the shared pipeline.
- Rust backend → Activity pipeline: bridges · Native transport and remote access support the data flow into the app.
- Activity pipeline → Pet rendering: drives · Unified activity updates animation and mode changes.
- Activity pipeline → Insight panels: updates · The same activity model powers analytics and history panels.
- Activity pipeline → App store: persists · Session-derived and user-facing state is stored locally.
- App store → Pet store: contains · General settings and pet configuration are maintained together.
- Pet store → Pet rendering: configures · Selected characters and settings determine how the mascot renders.
- Pet controls → Pet store: edits · Picker and context actions change pet configuration.
- Creation tools → Built-in pets: manages · Character authoring and customization operate on bundled assets.
- Built-in pets → Pet rendering: supplies · Pet JSON and media bundles provide animation and presentation data.
- Prompt assets → Activity pipeline: guides · Prompt and pipeline resources shape behavior normalization.
- Media tools → Creation tools: supports · Export and sprite helpers back content creation workflows.
- Cursor hook → Agent sources: adapts · The Cursor package is an input adapter into the shared ingestion layer.
- Marketing site → Update feed: publishes · The website surface includes release/update metadata.
