DOCSEARCHbyAlgolia
Submit Docs

Happy AI Client Wrapper

repository·main·Indexed 12 days ago

https://github.com/slopus/happy

A mobile and web client wrapper for Claude Code and Codex that provides end-to-end encrypted remote access to AI coding agents. It enables developers to monitor and control coding sessions from mobile devices via push notifications and remote mode switching.

Tokens
151.9K
Snippets
308
Records
608
Agent score
98%

What's inside Happy

  1. Overview of Happy Coder

    main

    Happy Coder is an open-source mobile application designed to let developers control AI coding agents (such as Claude Code, Codex, and Gemini-CLI) directly from a smartphone (iOS/Android) or a web browser.

    Key capabilities include:

    • Hardware Control: Runs on your own hardware (laptop, desktop, server, or Raspberry Pi) rather than expensive cloud servers.
    • Cost Efficiency: Completely free and open source; you only pay your AI model provider for usage (e.g., Claude Code, Text to Speech).
    • Real-time Monitoring: Receive push notifications when agents require input or encounter errors.
    • Security: Features an end-to-end encrypted connection between your devices.
    • Parallelism: Ability to run and switch between multiple coding agents simultaneously.
    • Hands-free Control: Supports voice input for mobile interaction.

  2. Overview of Happy Server

    main

    Happy Server is a minimal, zero-knowledge backend designed for secure synchronization of Claude Code clients. It acts as a secure relay for encrypted conversation blobs, enabling multi-device synchronization via WebSockets without the server ever having access to the decrypted content.

    Key characteristics:

    • Zero Knowledge: The server only stores encrypted blobs.
    • Cryptographic Auth: Uses public key signatures instead of passwords.
    • Real-time Sync: Uses WebSockets for seamless multi-device updates.
    • Privacy-focused: No analytics, tracking, or data mining.

  3. Overview of the Lab Rat Todo Project

    main

    The Lab Rat Todo Project is a minimal, frontend-only todo application designed specifically to serve as a test fixture for evaluating coding agents (such as Happy, OpenCode, Claude Code, etc.). It is intentionally small and contains intentional bugs and missing features to trigger various agent protocol primitives like permissions, subagents, and sandbox boundaries.

    Key Characteristics:

    • No build step: Runs directly in the browser.
    • No dependencies: Uses vanilla web technologies.
    • Persistence: Uses localStorage to store todo items.
    • Entry point: Open index.html to run the app.

  4. Overview of the Codex backend protocol reference

    main

    Codex serves as a high-fidelity backend protocol reference for implementing server-side session protocols. It is characterized by a typed app-server contract and a structured data model consisting of thread, turn, and item entities.

    Key architectural features include:

    • Approval Workflow: Approvals are treated as formal server requests rather than ad hoc message events.
    • Sandbox Policy: Features a rich, granular sandbox policy.
    • Session Management: Provides first-class support for resume, fork, and live replay operations.

    Developers looking to implement a server-side session protocol in Happy should use Codex as their primary reference for runtime semantics and approval models.

  5. Overview of Happy Project Components

    main

    The Happy ecosystem consists of several specialized packages:

    • Happy App: The Web UI and mobile client (built with Expo).
    • Happy CLI: The command-line interface used to wrap Claude Code and Codex.
    • Happy Agent: A CLI for remote agent control, used to create, send, and monitor sessions.
    • Happy Server: The backend server responsible for encrypted synchronization.

  6. Overview of the happy-agent CLI tool

    main

    The happy-agent CLI tool (located in packages/happy-agent) is a standalone client designed exclusively for the remote control of Happy Coder agents.

    Key differences from happy-cli:

    • happy-cli is used for both running and controlling agents.
    • happy-agent is a dedicated control client used for:
      • Listing machines.
      • Spawning sessions on a machine.
      • Creating sessions.
      • Sending messages.
      • Reading history.
      • Monitoring state.
      • Stopping sessions.

    happy-agent is a separate implementation from happy-cli with its own authentication flow and credential storage.

  7. Overview of @slopus/happy-wire

    main

    The @slopus/happy-wire package is the canonical wire specification for Happy clients and services. It centralizes shared wire contracts using TypeScript types and Zod schemas to ensure consistency across the CLI, app, server, and agent, preventing schema drift. It defines:

    • Encrypted message/update payloads
    • Session protocol envelopes and event streams
    • Helpers for creating valid session envelopes

    It is intentionally small and focused exclusively on protocol-level data.

  8. Key files and modules in Superset

    main

    The Superset codebase is composed of several key functional areas including host-service management, Electric SQL proxying, event bus communication, and workspace management. Developers looking to extend or integrate with Superset should focus on these specific modules:

    • Host Service: Manages service spawning, manifests, and adoption (host-service-manager.ts), including Electron integration (host-service/index.ts).
    • Data & Sync: Uses an Electric SQL proxy worker (electric.ts) and manages local SQLite schemas (local-db/src/schema/schema.ts) alongside cloud Postgres schemas (packages/db/src/schema/).
    • Communication: Implements a WebSocket event bus (event-bus.ts) and a client-side event bus (packages/workspace-client/src/lib/eventBus.ts).
    • Workspace & CLI: Handles workspace/worktree management (workspace.ts) and provides the CLI command structure (packages/cli/src/).
    • Agents: Uses agent command builders (agent-command.ts) and defines builtin terminal agent types (builtin-terminal-agents.ts).
    • UI & Layout: Employs a binary-tree pane layout engine (packages/panes/src/store.ts).

  9. Key features of Happy Coder

    main

    Happy Coder provides a secure bridge between your desktop Claude Code sessions and your mobile device.

    Core Capabilities:

    • Session Continuity: Seamlessly switch between desktop and mobile environments.
    • Push Notifications: Receive alerts for permission requests and task completions.
    • Offline Access: View conversation history even when your terminal is offline.
    • Security: Features end-to-end encryption (using TweetNaCl, the same encryption as Signal) and a zero-knowledge architecture where encryption keys never leave your device.
    • Real-time Sync: Real-time streaming of Claude's responses and session synchronization.

  10. Understand the @slopus/happy-wire package identity

    main

    The @slopus/happy-wire package is a publishable library that centralizes shared wire-level message and session-protocol schemas and types. It ensures that all clients (CLI, App, Agent) and services (Server) agree on the same wire contract, preventing protocol drift.

    Key Details:

    • npm name: @slopus/happy-wire
    • Workspace path: packages/happy-wire
    • Dependency version: Consumers should use ^0.1.0.
    • Scope: It is strictly for wire contracts (types, Zod schemas, and small helpers). Business logic should not be included here.

  11. Understand the Happy Backend Architecture

    main

    The Happy backend (implemented in packages/happy-server) is a Node.js-based system using Fastify for HTTP APIs and Socket.IO for real-time synchronization. It follows a multi-layered architecture:

    • API Layer: Handles HTTP requests via Fastify with Zod validation and Bearer token authentication.
    • Realtime Layer: Uses Socket.IO with an EventRouter to manage scoped connections (user-scoped, session-scoped, and machine-scoped).
    • Storage Layer: Uses Postgres (via Prisma) for persistent data, S3-compatible storage (like MinIO) for blobs, and Redis for caching/bus operations.
    • Security Model: Employs a dual encryption strategy. Client-side data (messages, KV values, artifacts) is stored as opaque encrypted blobs that the server cannot read. Server-side data (service tokens like GitHub or OpenAI) is encrypted using a KeyTree derived from the HANDY_MASTER_SECRET environment variable.

  12. Overview of Happy Project Structure

    main

    Happy is a monorepo consisting of four primary packages:

    • happy-app: The React Native + Expo mobile and web client.
    • happy-cli: A Node.js CLI that wraps Claude Code and Codex.
    • happy-agent: Provides remote agent control.
    • happy-server: The backend responsible for encrypted sync.