openhuman/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Summary

Cross-platform crypto community communication platform built with **Tauri v2** (React 19 + Rust). Targets desktop (Windows, macOS) and mobile (Android, iOS). Features deep Telegram integration via MTProto, real-time Socket.io communication, V8-based skill execution engine, and an MCP (Model Context Protocol) tool system for AI-driven Telegram interactions.

## App Theme & Design System

**Design Philosophy**: Premium, sophisticated crypto platform with calm, trustworthy aesthetic.

### Color Palette

- **Primary**: Ocean blue (`#4A83DD`) optimized for dark backgrounds
- **Sage**: Success green (`#4DC46F`) for growth indicators
- **Amber**: Warning (`#E8A838`) for attention states
- **Coral**: Error (`#F56565`) soft professional red
- **Canvas**: Background layers (`#FAFAF9` to `#D4D4D1`) with subtle warmth
- **Market Colors**: Bullish green, bearish red, Bitcoin orange, Ethereum purple

### Typography

- **Primary**: Inter (premium font stack)
- **Display**: Cabinet Grotesk for headings
- **Mono**: JetBrains Mono for code
- **Scale**: Sophisticated sizing with negative letter spacing for elegance

### Component System

- **Shadows**: Glow effects, subtle to float depth levels
- **Animations**: Fade-in, slide-in, scale-in with cubic-bezier easing
- **Border Radius**: Smooth system from `xs` (0.25rem) to `5xl` (2rem)
- **Spacing**: Extended scale including custom values (4.5, 13, 15, etc.)

### Current UI State

- Uses HashRouter (not BrowserRouter) as seen in `App.tsx:1`
- 153 TypeScript files total in src/
- Sophisticated Tailwind config with custom color system and animations

## Commands

```bash
# Frontend dev server only (port 1420)
yarn dev

# Desktop dev with hot-reload (starts Vite + Tauri)
yarn tauri dev

# Desktop dev with enhanced debugging (RUST_BACKTRACE and RUST_LOG enabled)
yarn dev:app

# Production build (TypeScript compile + Vite build + Tauri bundle)
yarn tauri build

# Debug build with .app bundle (required for deep link testing on macOS)
# On macOS, alphahuman:// only works when running the .app, not `tauri dev`
yarn tauri build --debug --bundles app
yarn macos:dev

# Android
yarn tauri android dev
yarn tauri android build

# iOS
yarn tauri ios dev
yarn tauri ios build

# Skills development
yarn skills:build   # Build skills in development mode
yarn skills:watch   # Watch skills for changes

# Rust checks
cargo check --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml
```

No test framework is currently configured. **ESLint and Prettier are configured** with Husky pre-commit/pre-push hooks for code quality enforcement.

## Architecture

### Provider Chain (App.tsx)

The app wraps in this order: `Redux Provider` → `PersistGate` → `SocketProvider` → `TelegramProvider` → `HashRouter` → `AppRoutes`. **Note**: Now uses HashRouter instead of BrowserRouter. This ordering matters because Socket.io and Telegram providers depend on Redux auth state.

### State Management (Redux Toolkit + Persist)

State lives in `src/store/` using Redux Toolkit slices:

- **authSlice** — JWT token, onboarding completion flag (persisted)
- **userSlice** — user profile
- **socketSlice** — connection status, socket ID
- **telegramSlice** — connection/auth status, chats, messages, threads (selectively persisted; loading/error states excluded)
- **aiSlice** — AI system state, memory management, session tracking
- **skillsSlice** — skills catalog, setup status, management state, V8 runtime integration
- **teamSlice** — team management, member invites, permissions

Redux Persist stores auth and telegram state (storage backend is configurable; default uses localStorage). The telegram slice has a complex nested structure in `src/store/telegram/` with separate files for types, reducers, extraReducers, and thunks.

### LocalStorage

- **Do not use `localStorage` (or `sessionStorage`) for app state or feature logic.** Use Redux (and Redux Persist where needed) instead.
- **Remove any existing `localStorage` usage** when touching related code. User-scoped data (auth, onboarding, Telegram session, socket state) lives in Redux, keyed by user id where applicable. Telegram session is in `telegram.byUser[userId].sessionString`, not localStorage.
- **Exceptions**: Redux-persist may use a localStorage-backed storage adapter by default; that is the persistence layer, not app logic. Any other remaining usage (e.g. deep-link `deepLinkHandled` flag) should be migrated to Redux or similar when that code is modified.
- **General rule**: Avoid adding new `localStorage` or `sessionStorage` usage; prefer Redux and remove existing usage when you work on affected areas.

### Service Layer (Singletons)

- **mtprotoService** (`src/services/mtprotoService.ts`) — Telegram MTProto client via `telegram` npm package. Session stored in Redux (`telegram.byUser[userId].sessionString`), not localStorage. Auto-retries FLOOD_WAIT up to 60s.
- **socketService** (`src/services/socketService.ts`) — Socket.io client. Auth token passed in socket `auth` object (not query string). Transports: polling first, then WebSocket. Enhanced with Rust-native Socket.io client for persistent connections.
- **apiClient** (`src/services/apiClient.ts`) — HTTP client for REST backend.

### MCP System (`src/lib/mcp/`)

Model Context Protocol implementation for AI tool execution over Socket.io:

- `transport.ts` — Socket.io JSON-RPC 2.0 transport with 30s timeout
- `telegram/server.ts` — TelegramMCPServer manages 99 tool definitions
- `telegram/tools/` — Individual tool files (one per Telegram API operation)
- Tools use `big-integer` library for Telegram's large integer IDs

### Routing (`src/AppRoutes.tsx`)

```
/           → Welcome (public)
/login      → Login (public)
/onboarding → Onboarding (protected, requires auth, not yet onboarded)
/home       → Home (protected, requires auth + onboarded)
*           → DefaultRedirect (routes based on auth state)
```

`PublicRoute` redirects authenticated users away. `ProtectedRoute` enforces auth and optionally onboarding status.

### Deep Link Auth Flow

Web-to-desktop handoff using `alphahuman://` URL scheme:

1. User authenticates in browser
2. Browser redirects to `alphahuman://auth?token=<loginToken>`
3. Tauri catches the deep link, Rust `exchange_token` command calls backend via `reqwest` (bypasses CORS)
4. Backend returns `sessionToken` + user object
5. App stores session in Redux, navigates to onboarding/home

Key file: `src/utils/desktopDeepLinkListener.ts` (lazy-loaded in `main.tsx`). Uses a `deepLinkHandled` flag to prevent infinite reload loops. Deep links do NOT work in `tauri dev` on macOS — must use built `.app` bundle.

### Rust Backend (`src-tauri/src/lib.rs`)

Enhanced Rust backend with comprehensive skill execution and runtime management:

**Core Commands:**

- `greet` — demo command
- `exchange_token` — CORS-free HTTP POST to backend for token exchange (desktop only)

**Runtime Management:**

- `discover_skills` — V8 skill discovery and manifest parsing
- `enable_skill` / `disable_skill` — skill lifecycle management
- `get_skill_preferences` / `set_skill_preferences` — skill configuration
- `connect_to_socket` — Rust-native Socket.io connection
- `get_socket_status` — connection status monitoring

**Android Support:**

- `RuntimeService` — background service for skill execution
- Notification permissions and foreground service management
- Android logging integration with logcat

Deep link plugin registered at setup. `register_all()` called only on Windows/Linux (panics on macOS).

### V8 Runtime System (`src-tauri/src/runtime/`)

Advanced JavaScript execution engine for skills using V8 (via deno_core):

**Core Components:**

- `v8_engine.rs` — V8 JavaScript runtime initialization and management
- `v8_skill_instance.rs` — Individual skill execution contexts and lifecycle
- `skill_registry.rs` — Skill discovery, registration, and state management
- `manifest.rs` — Skill manifest parsing with platform compatibility checks
- `socket_manager.rs` — Persistent Socket.io connections with reconnection logic
- `cron_scheduler.rs` — Scheduled task execution for time-based skills
- `preferences.rs` — Skill configuration and settings persistence

**Bridge System (`src-tauri/src/runtime/bridge/`):**

- `skills_bridge.rs` — Skill-to-skill communication and state sharing
- `tauri_bridge.rs` — Frontend-backend IPC and environment access
- `net.rs` — HTTP/fetch operations for skills
- `db.rs` — Database operations and storage management
- `store.rs` — Key-value storage for skill data
- `log_bridge.rs` — Structured logging from skills
- `cron_bridge.rs` — Cron job scheduling and management

**Quickjs Integration (`src-tauri/src/services/quickjs/`):**

- `service.rs` — High-level TDLib client management with V8 integration
- `bootstrap.js` — V8 JavaScript bootstrap environment
- `ops/mod.rs` — Native operations for WebSocket, timers, and async handling
- `storage.rs` — Persistent storage for TDLib sessions and data

**Platform Support:**

- Desktop platforms: Full V8 runtime with all features
- Mobile platforms: Error handling with feature availability checks
- Platform-specific skill filtering based on manifest declarations

## Environment Variables

Set in `.env` (Vite exposes `VITE_*` prefixed vars):

| Variable                     | Purpose                                            |
| ---------------------------- | -------------------------------------------------- |
| `VITE_BACKEND_URL`           | Backend API URL (default: `http://localhost:5005`) |
| `VITE_TELEGRAM_API_ID`       | Telegram MTProto API ID                            |
| `VITE_TELEGRAM_API_HASH`     | Telegram MTProto API hash                          |
| `VITE_TELEGRAM_BOT_USERNAME` | Telegram bot username                              |
| `VITE_TELEGRAM_BOT_ID`       | Telegram bot numeric ID                            |
| `VITE_SENTRY_DSN`            | Sentry DSN for error reporting (optional)          |
| `VITE_DEBUG`                 | Debug mode flag                                    |

Production defaults are in `src/utils/config.ts`.

## Recent Changes

Key updates from recent commits (cd9ebcd to current):

### Major Runtime Transition

- **V8 Runtime Migration** (`99c20ea`, `0f6a092`): Complete transition from QuickJS to V8
  - Replaced QuickJS with V8 (via deno_core) for improved JavaScript execution and WASM support
  - Enhanced skill management with V8 runtime including improved performance and compatibility
  - New V8 skill instance handling with advanced execution contexts
  - Updated dependencies and Cargo.toml to reflect V8 integration
  - Platform compatibility checks and enhanced manifest handling

### Android Platform Support

- **Full Android Integration** (`ce06cfc`, `a2578b9`): Production-ready mobile platform support
  - Complete Android project generation with MainActivity and RuntimeService
  - Background service for persistent skill execution on Android
  - Notification permission handling and foreground service management
  - Android logging integration with logcat for better debugging
  - Deep link support configuration in AndroidManifest.xml

### Enhanced Socket & Runtime Management

- **Rust-Native Socket.io Client** (`68d397e`): Persistent connection infrastructure
  - Native Rust Socket.io implementation for improved reliability
  - Enhanced socket connection handling with reconnection logic
  - Dynamic backend URL configuration support
  - Improved error handling and connection status monitoring

### Skills System Improvements

- **Advanced Skill Management** (`e841c86`, `719e6e5`): Enhanced skill lifecycle and configuration
  - Skill setup pipeline with contextual Enable/Setup/Configure/Retry buttons
  - Platform filtering for skills with manifest-based compatibility checks
  - Enhanced skill status derivation and connection indicators
  - Environment variable exposure to skills (whitelisted values)
  - Improved skill discovery and manifest processing with logging

### Major Additions

- **ESLint & Prettier Integration** (`5896966`): Complete code quality toolchain
  - ES module syntax for ESLint configuration with enhanced TypeScript support
  - Husky pre-commit/pre-push hooks for automatic formatting and linting
  - Type-only imports standardization across codebase
  - Consolidated import statements and improved code organization
  - GitHub workflows updated with Prettier and ESLint checks
- **Advanced Skills System** (`10ec1b3`): Comprehensive skill management platform
  - Dynamic skills loading from local directory via Rust integration
  - SkillSetupModal with conditional rendering (wizard vs management panel)
  - Background GitHub sync for skills catalog updates
  - Skills table with setup status indicators and management controls
  - Enhanced skill metadata with setup hooks and descriptions
- **Team Management Features** (`10ec1b3`): Multi-user collaboration system
  - TeamPanel, TeamMembersPanel, and TeamInvitesPanel components
  - Redux state management for teams, members, and invites
  - Team API integration with CRUD operations
  - Settings modal routing for team management paths
  - Role-based permissions and invitation system
- **AI System Enhancements**: Advanced memory and session management
  - Hybrid search with encryption for AI memory
  - Constitution-based AI behavior with GitHub integration
  - Entity graph migration to Neo4j backend
  - Session capture and transcript management
  - Memory chunking and context formatting
- **Enhanced CI/CD Pipeline** (`b1d7bce`): Production-ready deployment
  - XGH_TOKEN authentication for alphahumanxyz/alphahuman releases
  - Python sidecar setup and caching for cross-platform builds
  - Tauri configuration updates (com.alphahuman.app identifier)
  - GitHub Pages deployment with optimized workflows
  - Version tagging and environment variable management
- **Device Detection & Download System** (`9d74721`, `b5bccd2`): Enhanced multi-architecture download support
  - Optimized asset parsing using Maps for unique architecture links per platform
  - Enhanced DownloadScreen.tsx with architecture-specific download options
  - Improved device detection for Windows, macOS, Linux, and Android platforms
  - Added preference logic for more specific filenames in asset parsing
  - Support for multiple architectures (x64, aarch64) with intelligent sorting
- **Version Bump**: Project updated to v0.20.0 (`891517c`)

### Design System Updates

- **Settings Modal UI**: Clean 520px white modal contrasting with glass morphism theme
- **Animations**: 200ms entry animations, 250ms panel transitions, chevron hover effects
- **Lottie Animations**: Integrated into onboarding flow (`334673e`)
- **Connection Components**: Added Telegram and Gmail connection indicators
- **Routing**: Switched to HashRouter for better desktop app compatibility
- **Theme**: Implemented sophisticated color system with premium crypto aesthetic

### Component Structure

- **200+ TypeScript files** across `src/` directory with comprehensive tooling
- **AI System Architecture** (`src/lib/ai/`): Advanced artificial intelligence platform
  - Memory management with encryption, chunking, and hybrid search
  - Constitution-based behavior with GitHub integration
  - Entity graph with Neo4j backend integration
  - Session capture, transcript management, and tool compression
  - Provider system with OpenAI integration and custom providers
- **Skills Management System**: Dynamic skill platform with Rust integration
  - SkillsGrid.tsx - Skills catalog with setup status and management
  - SkillSetupModal.tsx - Conditional wizard/management panel rendering
  - SkillProvider.tsx - GitHub sync and local directory integration
  - Skills submodule integration with background updates
- **Team Collaboration Features**: Multi-user workspace management
  - TeamPanel.tsx - Team overview with member management
  - TeamMembersPanel.tsx - Member roles and permissions
  - TeamInvitesPanel.tsx - Invitation system with role assignment
  - Team API integration with Redux state management
- **Settings Modal System**: Comprehensive configuration interface
  - SettingsModal.tsx - Main container with URL routing
  - SettingsLayout.tsx - Modal wrapper with createPortal
  - Enhanced panels: Billing, Team, Connections, Privacy, Profile
  - Hooks: useSettingsNavigation.ts, useSettingsAnimation.ts
- **Download System**: Enhanced multi-platform distribution
  - DownloadScreen.tsx - Platform detection with architecture support
  - deviceDetection.ts - Comprehensive device/architecture utilities
  - GitHub API integration for real-time release assets
- **Code Quality Infrastructure**: ESLint, Prettier, and Husky integration
  - Pre-commit/pre-push hooks with TypeScript compilation checks
  - Standardized type-only imports and consolidated statements
  - GitHub workflow integration with automated quality checks

## Git Workflow

- **Push target**: All pushes go to the **user's private repo** (your fork). Do not push directly to the org repository.
- **PR target**: All pull requests are opened **from your fork** against the **org's private repo**, targeting the **`develop`** branch (not `main`).
- **No direct pushes to org**: The org repo does not allow direct pushes. All changes reach the org repo via PRs from your fork.

## Key Patterns

- **Code Quality**: ESLint and Prettier enforce code standards with Husky hooks. Use type-only imports (`import type`) and consolidate imports from same modules.
- **No dynamic imports**: All imports must be static `import` statements at the top of the file. Do not use `await import()` or `import().then()` inside functions or code blocks. Use try/catch around Tauri API calls for non-Tauri environments instead.
- **No localStorage**: Avoid `localStorage` and `sessionStorage`; use Redux (and persist) for app state. Remove any direct usage when working on affected code.
- **AI System Integration**: Use `src/lib/ai/` for memory management, constitution loading, entity queries, and session capture. AI providers abstracted through interface pattern.
- **V8 Skills Runtime**: Skills execute in V8 JavaScript engine on desktop platforms. Use `SkillProvider` for GitHub sync, `SkillsGrid` for management interface, and Rust runtime commands for lifecycle management. Platform filtering ensures skills only run on supported platforms.
- **Team Collaboration**: Team features in `src/components/settings/panels/Team*`. Use Redux `teamSlice` for state management and `teamApi` for backend operations.
- **Device Detection**: Use `deviceDetection.ts` utilities for platform/architecture detection. Support multiple architectures per platform (x64, aarch64) with intelligent preference logic.
- **GitHub Integration**: Fetch release assets via GitHub API (`fetchLatestRelease()`) and parse by architecture (`parseReleaseAssetsByArchitecture()`). Use Maps for efficient unique architecture tracking.
- **Download System**: Platform-specific file type support (.exe/.msi for Windows, .dmg for macOS, .AppImage/.deb/.rpm for Linux, .apk for Android) with fallback links.
- **Modal System**: Settings modal uses `createPortal` pattern with URL-based routing. Clean white design (not glass morphism) for system settings. Navigate with `/settings` paths for different panels.
- **Component Reuse**: Connection management reuses `connectOptions` array and components from onboarding flow. Maintains consistent UX patterns across features.
- **Redux Integration**: Multiple slices (auth, user, telegram, ai, skills, team) with Redux Persist. Use typed hooks and selectors. State functions accept optional `userId` param.
- **Node polyfills**: Vite config (`vite.config.ts`) polyfills `buffer`, `process`, `util`, `os`, `crypto`, `stream` for the `telegram` package which requires Node APIs.
- **Telegram IDs**: Use `big-integer` library, not native JS numbers (Telegram IDs exceed `Number.MAX_SAFE_INTEGER`).
- **MCP tool files**: Each tool in `src/lib/mcp/telegram/tools/` exports a handler conforming to `TelegramMCPToolHandler` interface. Tool names are typed in `src/lib/mcp/telegram/types.ts`.
- **Tauri IPC**: Frontend calls Rust via `invoke()` from `@tauri-apps/api/core`. Rust commands are registered in `generate_handler![]` macro. Enhanced with runtime management commands for V8 skill execution and Socket.io integration.
- **CORS workaround**: External HTTP requests from the WebView hit CORS. Use Rust `reqwest` via Tauri commands instead of browser `fetch()`.
- **Hash Routing**: Uses HashRouter for desktop app compatibility and deep link handling.
- **Integration Libraries**: Each integration (Telegram, future Gmail, etc.) lives under `src/lib/<integration>/` with its own `state/`, `services/`, `api/` subdirectories. Domain-specific services belong in the integration folder, not in `src/services/` (which holds only cross-cutting services like socketService, apiClient).
- **Unit Tests**: All unit tests live in `__tests__/` folders co-located with the code they test. Use Jest with TypeScript support.
- **Runtime Platform Differences**: V8 runtime is desktop-only. Mobile platforms use feature detection and graceful degradation. Skills with platform restrictions are filtered during discovery.
- **Socket Management**: Rust-native Socket.io client provides persistent connections with automatic reconnection. Use `connect_to_socket` command instead of frontend-only socket connections for reliability.
- **Dual Socket Codebase**: Socket event handling exists in **both** the TypeScript frontend (`src/services/socketService.ts`, `src/utils/tauriSocket.ts`) and the Rust backend (`src-tauri/src/runtime/socket_manager.rs`). **Any new socket event or protocol change must be implemented in both codebases.** The web frontend handles events directly via Socket.io; the Rust backend handles them over raw WebSocket with Engine.IO/Socket.IO framing. Example: `tool:sync` is emitted from both `src/lib/skills/sync.ts` (web mode) and `socket_manager.rs` (Rust mode, on connect + skill lifecycle changes).

## Platform Gotchas

- **macOS deep links**: Require `.app` bundle (not `tauri dev`). Clear WebKit caches when debugging stale content: `rm -rf ~/Library/WebKit/com.alphahuman.app ~/Library/Caches/com.alphahuman.app`
- **Cargo caching**: May serve stale frontend assets on incremental builds. Run `cargo clean --manifest-path src-tauri/Cargo.toml` if the app shows outdated UI.
- **`window.__TAURI__`**: Not available at module load time. Use static imports and try/catch around Tauri API calls (not around imports).
- **Android background services**: RuntimeService requires notification permissions (API 33+) and foreground service type specification (API 34+). Use Android logging (`android_logger`) for debug output in logcat.
- **V8 runtime limitations**: V8 engine is desktop-only. Android skills should use lightweight alternatives or server-side execution patterns.
- **Socket connections**: Persistent Socket.io connections via Rust backend work better than WebView-based connections on mobile platforms.