openhuman/CLAUDE.md

OpenHuman

AI assistant for communities — React + Tauri v2 desktop app with a Rust core (JSON-RPC / CLI).

Narrative architecture: docs/ARCHITECTURE.md. Frontend: docs/src/README.md. Tauri shell: docs/src-tauri/README.md.

---

Repository layout

Path	Role
app/	Yarn workspace openhuman-app: Vite + React (app/src/), Tauri desktop host (app/src-tauri/), Vitest tests
src/ (root)	Rust lib openhuman_core + openhuman CLI binary — core_server, openhuman::* domains, MCP routing
Cargo.toml (root)	Core crate; cargo build --bin openhuman produces the sidecar staged by app's core:stage
docs/	Architecture and module guides

Commands assume the repo root; yarn dev delegates to the app workspace.

---

Runtime scope

• Shipped product: desktop — Windows, macOS, Linux.
• Tauri host (app/src-tauri): desktop-only (compile_error! for other targets). No Android/iOS branches.
• Core binary (openhuman): spawned as a sidecar; the UI talks to it over HTTP (core_rpc_relay + core_rpc client), not by duplicating domain logic.

Where logic lives

• Rust core: business logic, execution, domains, RPC, persistence, CLI. Authoritative.
• Tauri + React (app/): UX, screens, navigation, bridging to the core. Presents and orchestrates only.

---

Commands (from repo root)

yarn dev                  # Frontend + Tauri dev
yarn tauri dev            # Desktop with Tauri (loads env via scripts/load-dotenv.sh)
yarn build                # Production UI build
yarn typecheck            # Typecheck (app workspace)
yarn lint                 # ESLint
yarn format               # Prettier write
yarn format:check         # Prettier check
cd app && yarn core:stage # Stage openhuman binary next to Tauri resources

# Rust — core library + CLI
cargo check --manifest-path Cargo.toml
cargo build --manifest-path Cargo.toml --bin openhuman

# Rust — Tauri shell
cargo check --manifest-path app/src-tauri/Cargo.toml

Tests: Vitest in app/ (yarn test:unit, yarn test:coverage); Rust via cargo test. Quality: ESLint + Prettier + Husky in app.

---

Configuration

• .env.example — Rust core, Tauri shell, backend URL, logging, proxy, storage, AI binary overrides. Load via source scripts/load-dotenv.sh.
• app/.env.example — VITE_* (core RPC URL, backend URL, Sentry DSN, dev helpers). Copy to app/.env.local.

Frontend config is centralized in app/src/utils/config.ts. Read VITE_* there and re-export — never import.meta.env directly elsewhere.

Rust config uses a TOML Config struct (src/openhuman/config/schema/types.rs) with env overrides (src/openhuman/config/schema/load.rs).

---

Testing

Unit (Vitest)

• Co-locate as *.test.ts / *.test.tsx under app/src/**.
• Config: app/test/vitest.config.ts; setup: app/src/test/setup.ts.
• Run: yarn test:unit, yarn test:coverage.
• Prefer behavior over implementation. Use helpers in app/src/test/. No real network, no time flakes.

Shared mock backend

Used by both unit and Rust tests.

• Core: scripts/mock-api-core.mjs · server: scripts/mock-api-server.mjs · E2E wrapper: app/test/e2e/mock-server.ts.
• Admin: GET /__admin/health, POST /__admin/reset, POST /__admin/behavior, GET /__admin/requests.
• Run manually: yarn mock:api.

E2E (WDIO — dual platform)

Full guide: docs/E2E-TESTING.md.

• Linux (CI): tauri-driver (WebDriver :4444).
• macOS (local): Appium Mac2 (XCUITest :4723) on the .app bundle.
• Specs: app/test/e2e/specs/*.spec.ts. Helpers in app/test/e2e/helpers/. Config: app/test/wdio.conf.ts.

yarn test:e2e:build
bash app/scripts/e2e-run-spec.sh test/e2e/specs/smoke.spec.ts smoke
yarn test:e2e:all:flows
docker compose -f e2e/docker-compose.yml run --rm e2e   # Linux E2E on macOS

Use element-helpers.ts (clickNativeButton, waitForWebView, clickToggle) — never raw XCUIElementType*. Assert UI outcomes and mock effects.

Deterministic core-sidecar reset

app/scripts/e2e-run-spec.sh creates and cleans a temp OPENHUMAN_WORKSPACE by default. OPENHUMAN_WORKSPACE redirects core config + storage away from ~/.openhuman.

Rust tests with mock

yarn test:rust
bash scripts/test-rust-with-mock.sh --test json_rpc_e2e

---

Frontend (app/src/)

Provider chain (App.tsx): Redux → PersistGate → UserProvider → SocketProvider → AIProvider → SkillProvider → HashRouter → AppRoutes.

State (store/): Redux Toolkit slices — auth, user, socket, ai, skills, team, etc. Prefer Redux (persisted where configured) over ad-hoc localStorage.

Services (services/): singletons — apiClient, socketService, coreRpcClient (HTTP bridge to core), domain api/* clients.

MCP (lib/mcp/): JSON-RPC transport, validation, types over Socket.io. Tooling is driven by the backend + skills system.

Routing (AppRoutes.tsx): hash routes /, /onboarding, /mnemonic, /home, /intelligence, /skills, /conversations, /invites, /agents, /settings/*. No /login.

AI config: bundled prompts in src/openhuman/agent/prompts/ (also bundled via app/src-tauri/tauri.conf.json resources). Loaders in app/src/lib/ai/ use ?raw imports, optional remote fetch, and ai_get_config / ai_refresh_config in Tauri.

---

Tauri shell (app/src-tauri/)

Thin desktop host: window management, daemon health, core process lifecycle (core_process, CoreProcessHandle), JSON-RPC relay (core_rpc_relay, core_rpc).

Registered IPC (see docs/src-tauri/02-commands.md): greet, write_ai_config_file, ai_get_config, ai_refresh_config, core_rpc_relay, window commands, openhuman_* daemon helpers.

---

Rust core (src/)

• openhuman/ — Domain logic (memory, channels, config, cron, skills, webhooks, …). RPC controllers in per-domain rpc.rs; use RpcOutcome<T> per AGENTS.md.
• Module layout rule: new functionality goes in a dedicated subdirectory (openhuman/<domain>/mod.rs + siblings). Do not add new standalone *.rs files at src/openhuman/ root.
• Controller schema contract: shared types in src/core/mod.rs (ControllerSchema, FieldSchema, TypeSchema).
• Domain schema files: per-domain schemas.rs (e.g. src/openhuman/cron/schemas.rs), exported from domain mod.rs.
• Controller-only exposure: expose features to CLI and JSON-RPC via the controller registry. Do not add domain branches in src/core/cli.rs / src/core/jsonrpc.rs.
• Light mod.rs: keep domain mod.rs export-focused. Operational code in ops.rs, store.rs, types.rs, etc.
• core_server/ — Transport only: Axum/HTTP, JSON-RPC envelope, CLI parsing, dispatch. No heavy logic.

Controller migration checklist

• src/openhuman/<domain>/mod.rs: add mod schemas;, re-export all_controller_schemas as all_<domain>_controller_schemas and all_registered_controllers as all_<domain>_registered_controllers.
• src/openhuman/<domain>/schemas.rs defines schemas, all_controller_schemas, all_registered_controllers, and handle_* fns delegating to domain rpc.rs.
• Wire exports into src/core/all.rs. Remove migrated branches from src/rpc/dispatch.rs.

Event bus (src/core/event_bus/)

Typed pub/sub + in-process typed request/response. Both singletons — use module-level functions; never construct EventBus / NativeRegistry directly.

• Broadcast (publish_global / subscribe_global) — fire-and-forget. Many subscribers, no return.
• Native request/response (register_native_global / request_native_global) — one-to-one typed dispatch keyed by method string. Zero serialization — trait objects, mpsc::Sender, oneshot::Sender pass through unchanged. Internal-only; JSON-RPC-facing work goes through src/core/all.rs.

Core types (all in src/core/event_bus/):

Type	File	Purpose
DomainEvent	events.rs	#[non_exhaustive] enum of all cross-module events
EventBus	bus.rs	Singleton over tokio::sync::broadcast; ctor is pub(crate)
NativeRegistry / NativeRequestError	native_request.rs	Typed request/response registry by method name
EventHandler	subscriber.rs	Async trait with optional domains() filter
SubscriptionHandle	subscriber.rs	RAII — drops cancel the subscriber
TracingSubscriber	tracing.rs	Built-in debug logger

Singleton API: init_global(capacity), publish_global(event), subscribe_global(handler), register_native_global(method, handler), request_native_global(method, req), global() / native_registry().

Domains: agent, memory, channel, cron, skill, tool, webhook, system.

Each domain owns a bus.rs with its EventHandler impls — e.g. cron/bus.rs (CronDeliverySubscriber), webhooks/bus.rs (WebhookRequestSubscriber), channels/bus.rs (ChannelInboundSubscriber). Convention: <Purpose>Subscriber + name() returning "<domain>::<purpose>".

Adding events: add variants to DomainEvent, extend the domain() match, create <domain>/bus.rs, register subscribers at startup, publish via publish_global.

Adding a native handler: define request/response types in the domain (owned fields, Arcs, channels — not borrows; Send + 'static, not Serialize). Register at startup keyed by "<domain>.<verb>". Callers dispatch via request_native_global.

Tests: re-register the same method to override; or construct a fresh NativeRegistry::new() for isolation.

---

Design

Premium, calm visual language — ocean primary #4A83DD, sage / amber / coral semantics, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. See docs/DESIGN_GUIDELINES.md.

Shell vs app code

Tauri/Rust in the shell is a delivery vehicle (windowing, process lifecycle, IPC). Keep UI behavior and product logic in TypeScript/React (app/). Only grow Rust in the shell for hard platform/security reasons.

Git workflow

• Issues and PRs on upstream tinyhumansai/openhuman — not a fork — unless explicitly told otherwise.
• Issue templates: .github/ISSUE_TEMPLATE/feature.md, .github/ISSUE_TEMPLATE/bug.md. PR template: .github/PULL_REQUEST_TEMPLATE.md. AI-authored text should follow them verbatim.
• PRs target main.

---

Coding philosophy

• Unix-style modules: small, sharp-responsibility units composed through clear boundaries.
• Tests before the next layer: ship unit tests for new/changed behavior before stacking features. Untested code is incomplete.
• Docs with code: new/changed behavior ships with matching rustdoc / code comments; update AGENTS.md or architecture docs when rules or user-visible behavior change.

---

Debug logging (must follow)

• Default to verbose diagnostics on new/changed flows so issues are easy to trace end-to-end.
• Log entry/exit, branches, external calls, retries/timeouts, state transitions, errors.
• Use stable grep-friendly prefixes ([domain], [rpc], [ui-flow]) and correlation fields (request IDs, method names, entity IDs).
• Rust: log / tracing at debug / trace. app/: namespaced debug + dev-only detail.
• Never log secrets or full PII — redact.
• Changes lacking diagnosis logging are incomplete.

---

Feature design workflow

Specify → prove in Rust → prove over RPC → surface in the UI → test.

1. Specify against the current codebase — ground in existing domains, controller/registry patterns, JSON-RPC naming (openhuman.<namespace>_<function>). No parallel architectures.
2. Implement in Rust — domain logic under src/openhuman/<domain>/, schemas + handlers in the registry, unit tests until correct in isolation.
3. JSON-RPC E2E — extend tests/json_rpc_e2e.rs / scripts/test-rust-with-mock.sh so RPC methods match what the UI will call.
4. UI in Tauri app — React screens/state using core_rpc_relay / coreRpcClient. Keep rules in the core.
5. App unit tests — Vitest.
6. App E2E — desktop specs for user-visible flows.

Capability catalog: when a change adds/removes/renames a user-facing feature, update src/openhuman/about_app/ in the same work.

Planning rule: up front, define the E2E scenarios (core RPC + app) that cover the full intended scope — happy paths, failure modes, auth gates, regressions. Not testable end-to-end ⇒ incomplete spec or too-large cut.

---

Key patterns

• File size: prefer ≤ ~500 lines; split growing modules.
• Pre-merge (code changes): Prettier, ESLint, tsc --noEmit in app/; cargo fmt + cargo check for changed Rust.
• No dynamic imports in production app/src code — static import / import type only. No import(), React.lazy(() => import(...)), await import(...). For heavy optional paths, use a static import and guard the call site with try/catch or a runtime check. Exceptions: Vitest harness patterns in *.test.ts / __tests__ / test/setup.ts; ambient typeof import('…') in .d.ts; config files (e.g. tailwind.config.js JSDoc).
• Dual socket sync: when changing the realtime protocol, keep socketService / MCP transport aligned with core socket behavior (see docs/ARCHITECTURE.md dual-socket section).

---

Platform notes

• Vendored CEF-aware tauri-cli: runtime is CEF; only the vendored CLI at app/src-tauri/vendor/tauri-cef/crates/tauri-cli bundles Chromium into Contents/Frameworks/. Stock @tauri-apps/cli produces a broken bundle (panic in cef::library_loader::LibraryLoader::new). yarn dev:app and all cargo tauri scripts call yarn tauri:ensure which runs scripts/ensure-tauri-cli.sh. If overwritten, reinstall with cargo install --locked --path app/src-tauri/vendor/tauri-cef/crates/tauri-cli.
• macOS deep links: often require a built .app bundle, not just tauri dev.
• window.__TAURI__: not present at module load; guard Tauri usage.
• Core sidecar: must be staged so core_rpc can reach the openhuman binary (see scripts/stage-core-sidecar.mjs).