Relevant source files

The following files were used as context for generating this wiki page: - [CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/CLAUDE.md) - [knowledge.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/knowledge.md) - [apps/cli/CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/apps/cli/CLAUDE.md) - [apps/server/workers/README.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/apps/server/workers/README.md) - [packages/schema/protocol/CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/packages/schema/protocol/CLAUDE.md) - [apps/web/react/CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/apps/web/react/CLAUDE.md) - [apps/macos/CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/apps/macos/CLAUDE.md) - [apps/mobile/android/CLAUDE.md](https://github.com/Enflame-Media/Magic-Agent/blob/main/apps/mobile/android/CLAUDE.md)

# Introduction to Magic-Agent **Magic-Agent** (internally referred to as **Happy**) is a comprehensive cross-platform ecosystem designed as a mobile and web client for Claude Code and Codex. Its primary purpose is to enable remote control and real-time session sharing across various devices—including iOS, Android, macOS, and Web—while maintaining strict security through end-to-end encryption. The system functions by wrapping the Claude Code CLI and relaying its state through a secure backend to authorized client applications. Sources: [CLAUDE.md:10-15](), [knowledge.md:5-10](), [apps/server/workers/README.md:3-6]() The project is structured as a TypeScript/Swift monorepo, utilizing Yarn Workspaces to manage multiple applications and shared packages. It adheres to a "zero-knowledge" architecture where the central server acts as an encrypted relay, ensuring that user data remains unreadable to the infrastructure and is only decrypted on the user's local devices. Sources: [CLAUDE.md:12-16](), [apps/server/workers/README.md:52-55](), [knowledge.md:43-46]() ## System Architecture The Magic-Agent ecosystem follows a distributed architecture involving three primary tiers: the CLI (Source), the Server (Relay), and the Apps (Clients). ### High-Level Data Flow The following diagram illustrates the relationship between the terminal-based CLI, the backend relay, and the mobile/web user interfaces. ```mermaid flowchart TD CLI[apps/cli - Node.js] <--> Server[apps/server - Fastify/Workers] Server <--> App[apps/web/react - Expo] Server <--> MacOS[apps/macos - Swift] subgraph Local_Terminal CLI --> Claude[Claude Code Subprocess] end subgraph Mobile_Web_UI App --> View[Encrypted Session View] end subgraph Native_Desktop MacOS --> Native[Native SwiftUI View] end style CLI fill:#f9f,stroke:#333,stroke-width:2px style Server fill:#bbf,stroke:#333,stroke-width:2px style App fill:#bfb,stroke:#333,stroke-width:2px ``` Sources: [CLAUDE.md:200-215](), [knowledge.md:37-41]() ### Architecture Components | Component | Technology | Description | | :--- | :--- | :--- | | **happy-cli** | Node.js (ESM) | Wraps Claude Code, captures session state, and sends encrypted updates. | | **happy-server** | Fastify (Docker) / Hono (Workers) | Relays encrypted messages between devices using WebSockets. | | **happy-app** | React Native (Expo) | Cross-platform mobile/web client for viewing and controlling sessions. | | **happy-macos** | Swift / SwiftUI | Native macOS application with menu bar integration and shortcuts. | | **happy-android** | Kotlin / Jetpack Compose | Native Android application providing a first-class mobile experience. | Sources: [CLAUDE.md:20-55](), [apps/macos/CLAUDE.md:10-15](), [apps/mobile/android/CLAUDE.md:10-15]() ## Core Systems ### Security and Encryption Security is centered on a zero-knowledge relay model. All sensitive data, including session content, messages, and artifacts, is encrypted client-side using **AES-256-GCM** before transmission. The backend server facilitates authentication through cryptographic challenge-response pairs but never has access to the plaintext content or the encryption keys. Sources: [CLAUDE.md:200-205](), [apps/cli/CLAUDE.md:245-255](), [apps/mobile/android/CLAUDE.md:162-175]() ```mermaid sequenceDiagram participant CLI as "CLI (Source)" participant SRV as "Server (Relay)" participant MOB as "Mobile (Client)" CLI->>CLI: Encrypt state (AES-256-GCM) CLI->>SRV: Send Encrypted Update (WSS) SRV->>MOB: Relay Encrypted Update (WSS) Note over SRV: Server cannot decrypt MOB->>MOB: Decrypt state MOB->>MOB: Update UI ``` Sources: [CLAUDE.md:208-215](), [apps/server/workers/README.md:158-162]() ### Session Synchronization The CLI captures the state of the Claude Code subprocess and serializes it into updates. These updates are categorized as persistent (updates) or transient (ephemeral events). Persistent updates include session metadata and messages, while ephemeral events handle real-time indicators like typing status or costs. Sources: [packages/schema/protocol/CLAUDE.md:100-115](), [apps/cli/CLAUDE.md:155-165]() ### Authentication Flow Authentication is strictly key-based, involving no passwords: 1. The **CLI** generates an Ed25519 keypair and displays a QR code. 2. The **Mobile App** scans the QR code to approve the connection. 3. The **Server** facilitates a challenge-response authentication to issue tokens. 4. All subsequent data is linked to the authorized public key. Sources: [CLAUDE.md:200-205](), [apps/server/workers/README.md:58-65]() ## Shared Packages Magic-Agent utilizes shared packages located in the `packages/schema/` directory to ensure type safety and protocol consistency across the monorepo. | Package | Purpose | Primary Files | | :--- | :--- | :--- | | `@magic-agent/protocol` | Single source of truth for Zod schemas (API types, events). | [packages/schema/protocol/CLAUDE.md]() | | `@magic-agent/errors` | Unified error handling with standardized `AppError` codes. | [CLAUDE.md:110-115]() | | `@happy/lint-rules` | Custom linting for codebase-specific naming (e.g., "GitHub" casing). | [CLAUDE.md:125-135]() | Sources: [CLAUDE.md:100-140](), [knowledge.md:20-25]() ## Protocol Definition The communication protocol differentiates between persistent updates and ephemeral events, often using distinct naming conventions for IDs due to legacy requirements. ```mermaid classDiagram class ApiUpdate { <> t: string id/sid: string payload: object } class ApiEphemeral { <> type: string id: string data: object } ApiUpdate <|-- NewSession ApiUpdate <|-- MessageUpdate ApiEphemeral <|-- ActivityEvent ApiEphemeral <|-- UsageEvent ``` Sources: [packages/schema/protocol/CLAUDE.md:100-120](), [knowledge.md:50-55]() **Protocol Key Differences:** * **Persistent Updates:** Use the discriminator `t` (e.g., `new-session`, `message`). * **Ephemeral Events:** Use the discriminator `type` (e.g., `activity`, `typing`). * **ID Inconsistency:** Session IDs are referred to as `id` in session updates but `sid` in message/delete updates for backward compatibility. Sources: [knowledge.md:50-60](), [packages/schema/protocol/CLAUDE.md:115-125]() ## Development Summary The Magic-Agent project provides a robust framework for extending the capabilities of terminal-based AI agents to a mobile and remote context. By leveraging a zero-knowledge relay architecture and a shared protocol package, it ensures that developers can maintain a consistent experience across different platforms while guaranteeing user privacy through mandatory end-to-end encryption. Sources: [CLAUDE.md:10-25](), [apps/server/workers/README.md:3-10]()