Session Management & Remote Control
Relevant source files
The following files were used as context for generating this wiki page:
Session Management & Remote Control is a core pillar of the Happy ecosystem, enabling users to interact with Claude Code and Codex sessions across multiple devices. The system facilitates real-time synchronization of agent states, command execution, and session persistence through a secure, zero-knowledge architecture. All sensitive session data, including message history and agent thoughts, is end-to-end encrypted before leaving the client device, ensuring the server acts only as an encrypted relay.
The system supports a variety of clients including a Node.js CLI wrapper, React Native mobile/web applications, and native macOS/Android clients. This multi-platform approach allows a user to start a session on a terminal and maintain control or visibility via a mobile device, effectively providing a remote UI for terminal-based AI agents.
Sources: CLAUDE.md, apps/server/workers/README.md, apps/cli/CLAUDE.md
System Architecture
The architecture utilizes a hub-and-spoke model where the Happy Server (Docker or Workers) serves as the central communication relay. The system is designed around specific connection scopes to maintain security and routing integrity.
Connection Scopes
To manage data flow effectively, the system defines three primary WebSocket client types:
- user-scoped: Typically used by mobile apps to receive all events related to a specific user account.
- session-scoped: Used by session viewers to track updates for a specific individual Claude session.
- machine-scoped: Used by the CLI daemon to manage machine-level commands and session spawning.
Sources: apps/server/workers/README.md, apps/cli/src/api/apiSession.ts:41-45
Data Flow Overview
The following diagram illustrates the high-level interaction between the CLI (wrapping Claude Code), the Server relay, and the Remote Client (Mobile UI).
The server facilitates bidirectional message streaming and Remote Procedure Calls (RPC) without being able to decrypt the payloads.
Sources: CLAUDE.md, apps/cli/CLAUDE.md, apps/server/workers/README.md
Session Lifecycle & Protocol
Sessions follow a structured lifecycle from creation to archiving or deletion. The protocol uses versioned schemas to ensure compatibility across different client versions.
Session Persistence & Resumption
The system allows for "Session Forking" and "Revival":
- Revival: Automatically resumes stopped sessions if an RPC request fails with
SESSION_NOT_ACTIVE. - Resumption: Using the
--resumeflag in the CLI creates a new session file while preserving the unified history of the previous session. - Supersession: When a session is resumed, the old session is marked as
supersededBythe new session ID, allowing the UI to redirect users to the active context.
Sources: apps/cli/CLAUDE.md, apps/web/react/sources/app/(app)/session/[id]/info.tsx:230-240
Protocol Schemas
The @magic-agent/protocol package provides Zod schemas for session updates. All session-related updates have been standardized to use sid as the session identifier.
| Update Type | Description | Key Fields |
|---|---|---|
new-session | Emitted when a Claude session is initialized. | sid, seq, metadata, agentState, active |
update-session | Sent when metadata or agent state changes. | sid, agentState (optional), metadata (optional) |
delete-session | Soft delete or permanent removal of a session. | sid |
Sources: packages/schema/protocol/coverage/src/updates/session.ts.html:37-100
API Session Client Logic
The ApiSessionClient class in the CLI manages the WebSocket connection for individual sessions. It handles reconnection logic, user message queues, and RPC registration.
Sources: apps/cli/src/api/apiSession.ts:13-50
Remote Control & RPC Handlers
Remote control is achieved through Remote Procedure Calls (RPC) that allow the mobile application to trigger actions on the machine running the CLI.
Available RPC Actions
Clients can perform various management tasks remotely:
- Session Killing: Immediately terminates the active process.
- Context Clearing: Starts a fresh conversation history.
- Context Compaction: Summarizes the conversation history to reduce token usage and context window consumption.
- Machine Spawning: Starts a completely new session in a specified directory on an online machine.
Sources: apps/web/react/sources/app/(app)/session/[id]/info.tsx:115-165, apps/web/vue/src/views/SessionInfoView.vue:135-160
Security Constraints
Remote control involves a "defense-in-depth" approach:
- Command Allowlist: Only pre-approved commands (e.g.,
git status,npm test,ls) can be executed via the bash RPC handler. - Shell Metacharacter Blocking: Prevents command chaining and injection by blocking characters like
;,\|, and&. - Audit Logging: All command attempts, whether allowed or blocked, are logged for monitoring.
Sources: apps/cli/CLAUDE.md
User Interface & Metadata
The user interface provides deep visibility into the session state through decrypted metadata and real-time indicators.
Session Metadata Breakdown
When a client decrypts session metadata, it typically accesses the following structures:
| Field | Description |
|---|---|
host | The hostname of the machine running the session. |
path | The working directory of the project. |
os | The operating system (macOS, Linux, etc.). |
flavor | The AI provider type (Claude, Codex, Gemini). |
version | The CLI version used to start the session. |
hostPid | The Process ID of the host CLI process. |
Sources: apps/web/react/sources/app/(app)/session/[id]/info.tsx:295-345, apps/web/vue/src/views/SessionInfoView.vue:30-45
Real-Time Indicators
The UI uses animated components to reflect the live status of the agent:
- Status Dot: A pulsing indicator showing if the session is online or connected.
- Thinking Indicator: Shows when the AI agent is actively processing a request (
session.thinking). - Sequence Number: Tracks the total number of updates to ensure the client is synchronized with the latest state.
Sources: apps/web/react/sources/app/(app)/session/[id]/info.tsx:35-65, 360-375
Conclusion
Session Management in the Happy project is characterized by its strict adherence to end-to-end encryption and its robust WebSocket-based synchronization protocol. By separating concerns between the CLI (agent execution), the Server (encrypted relay), and the Remote Clients (UI), the system provides a secure and seamless way to manage complex AI-driven coding tasks across different hardware environments. The implementation of RPC handlers and command allowlists further ensures that remote control does not come at the cost of local machine security.