Happier Documentation

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

Key technical characteristics include:

• Local Execution: Runs on the user's own hardware (laptop, desktop, server, or Raspberry Pi) rather than expensive cloud servers.
• Security: Uses end-to-end encrypted connections between devices.
• Cost Model: Completely free and open source (users only pay their respective AI model providers for usage).
• Features: Supports parallel agent execution, push notifications for agent prompts or errors, and voice input for hands-free control.

The feature matrix provides an overview of user-facing capabilities across different clients (App, Web, CLI, Mobile, Desktop) and runtimes. Capabilities are categorized by their stability status:

• Stable: Intended for regular use.
• Experimental: Available but still being hardened.
• Capability-driven: Functionality depends on specific backend or provider support.

Key functional areas include session management (sharing, syncing, handoff), developer tools (Git/file manager, embedded terminal, SCM hosting), and advanced interaction modes (voice, pets, local memory search).

The Happier ecosystem consists of three main components:

• @happier-dev/cli: The command-line interface used to wrap Claude Code and Codex.
• @happier-dev/server: The backend server responsible for encrypted synchronization.
• @happier-dev/app: The mobile client used for remote control and monitoring.

The UI Testkit provides a canonical testing surface for apps/ui. It is organized into several specialized directories to handle different testing concerns:

• mocks/: Contains canonical module mock factories for repeated UI boundaries.
• fixtures/: Provides typed app-state and feature fixture builders.
• render/: Contains shared react-test-renderer render surfaces.
• hooks/: Includes helpers for hook rendering, deferred execution, and flushing effects.
• harness/: Provides repeated screen and feature harnesses.
• cleanup/: Contains shared cleanup registration used by the render and hook helpers.

The Happier Review Report is a structured document used to evaluate code changes, plans, or releases. It provides a standardized way to communicate the outcome of a review, identify blockers, and assess risk.

Key sections include:

• Outcome And Blockers: Summarizes the review result and any issues preventing progress.
• High-Confidence Findings: Details findings that are certain and actionable.
• Plan Completeness & QA Coverage: Assesses how thoroughly the proposed changes were planned and tested.
• Recommended Or Applied Fix Clusters: Groups related fixes that should be addressed.
• Unexamined Scope And Residual Risk: Identifies areas that were not reviewed and the potential risks they pose.
• Final Recommendation: Provides the final verdict on whether the item is ready for merge or release.

Agent Craft is a structured working method designed for handling hard, ambiguous, or high-stakes tasks. It provides a framework for reading requests, decomposing problems, allocating verification effort, and communicating results. The method is intended to prevent common failures like shipping solutions to the wrong problems, creating monolithic fixes that are hard to debug, or propagating false premises through reasoning chains.

Key procedures include:

• Classifying request modes (Question, Change Order, Exploration, Thinking Aloud).
• Decomposing problems into independently checkable, falsifiable claims.
• Allocating effort based on risk (Probability × Cost × Silence).
• Verifying claims through re-derivation rather than intuition.
• Labeling uncertainty by separating observed, derived, and assumed information.

Happier Server is a minimal, zero-knowledge backend designed to synchronize encrypted conversations for Claude Code clients. It acts as a secure relay: clients generate encryption keys locally and end-to-end encrypt (E2EE) messages before they leave the device. The server only stores and syncs encrypted blobs, meaning it cannot read the content of any messages.

Key characteristics:

• Zero Knowledge: The server has no ability to decrypt data.
• Real-time Sync: Uses WebSockets for multi-device synchronization.
• Cryptographic Auth: Uses public key signatures instead of stored passwords.

The pending queue allows you to store messages for a session without sending them to the agent immediately. This is useful when the agent is busy, offline, or not yet ready.

Key characteristics:

• Session-wide: Anyone with edit access to a shared session can see and manage these messages.
• Ordered: You can control the sequence in which messages are processed.
• Editable: Messages can be edited, removed, or reordered before they are executed.
• Stored with the session: Pending content uses the same storage mode as the session transcript (encrypted by default, or plaintext depending on your deployment).

Note: Pending messages do not trigger "unread" indicators; instead, they are indicated by a separate pending count badge.