Introduction to Magic-Agent
Relevant source files
The following files were used as context for generating this wiki page:
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.
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
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:
- The CLI generates an Ed25519 keypair and displays a QR code.
- The Mobile App scans the QR code to approve the connection.
- The Server facilitates a challenge-response authentication to issue tokens.
- 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.
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
idin session updates butsidin 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