How rainnoon/oc-claw works
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: pipeline.ts Activity pipeline · petStore.ts Pet store · SpritePet.tsx Pet rendering · src Tauri shell
Components 17
Desktop app
Core Tauri product: React frontend plus Rust backend, pet runtime, and local persistence.
- Tauri shell · App entry and runtime boundary for the desktop product.
frontend/src - React UI · Main interactive surface for pet display, settings, and detail views.
frontend/src/App.tsx - Rust backend · System integration layer for windowing, platform behavior, tunneling, and API communication.
frontend/src-tauri/src - Activity pipeline · Shared model that turns agent and hook inputs into unified activity state.
frontend/src/lib/pipeline.ts - Agent sources · Adapters for OpenClaw sessions and external agent hooks such as Claude Code, Codex, and Cursor.
frontend/src/lib/agents.ts - App store · Persistent desktop state, preferences, and local settings storage.
frontend/src/lib/store.ts - Pet store · Pet selection, configuration, and character-specific runtime state.
frontend/src/lib/petStore.ts - Insight panels · Session history, logs, and usage metrics shown in the expanded interface.
frontend/src/components/AgentDetailView.tsx - Pet rendering · Animated mascot rendering and compact/notch-size presentation surfaces.
frontend/src/components/SpritePet.tsx - Pet controls · Context menu, picker, onboarding, and character management actions.
frontend/src/components/PetContextMenu.tsx - Creation tools · 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 · Data-driven character definitions and bundled media for multiple pets.
frontend/public/assets/builtin - Prompt assets · Prompt and pipeline files used to steer pet behavior and states.
frontend/public/prompt - Media tools · 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 · Separate package that relays Cursor editor events into the shared activity model.
extensions/cursor/extension.js - Marketing site · Localized public website with landing pages, downloads, and release metadata.
website/src/pages - Update feed · Public update discovery artifact used by the website and distribution flow.
website/public/update/latest.json
Connections 17
- 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.