Codex & Gemini Support
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Codex and Gemini support within the Happy ecosystem enables users to run interactive AI agent sessions via a Command Line Interface (CLI) while maintaining real-time remote control through mobile or web applications. This support is architected around a wrapper system that captures session states, encrypts data end-to-end, and synchronizes persistent state changes and ephemeral events across the Happy infrastructure.
The purpose of these modules is to provide a "remote control" layer for powerful AI agents. While the agents (Claude, Codex, or Gemini) execute logic and tool calls on a host machine, the Happy CLI facilitates end-to-end encrypted communication between the local terminal and the Happy server, allowing users to monitor progress, grant permissions, and view artifacts remotely.
Sources: apps/cli/CLAUDE.md, apps/cli/src/codex/runCodex.ts:70-75, apps/cli/src/gemini/runGemini.ts:40-45
Core Architecture and Lifecycle
The architecture for both Codex and Gemini follows a consistent lifecycle pattern: machine registration, session creation, and the initialization of specialized processors for reasoning and diff tracking. Both agents utilize an Ink-based UI for local display and a MessageQueue2 system to handle incoming prompts while respecting mode boundaries.
Session Initialization Flow
The initialization process ensures the host machine is recognized and a unique, tagged session is established. This session acts as the anchor for all subsequent WebSocket communication.
Components Summary
| Component | Description |
|---|---|
| Agent Backend | The core execution engine (CodexMcpClient or GeminiBackend) that interfaces with the AI model. |
| Sync Client | Manages WebSocket communication and optimistic state updates for the session. |
| Reasoning Processor | Processes "thinking" chunks from the agent to extract titled reasoning sections or tool calls. |
| Diff Processor | Tracks file edit events and generates unified diffs for remote display. |
| Permission Handler | Intercepts tool calls requiring user approval and routes them to the mobile app. |
| Message Queue | A MessageQueue2 instance that buffers user prompts and manages mode/model switches. |
Sources: apps/cli/src/codex/runCodex.ts:250-400, apps/cli/src/gemini/runGemini.ts:240-270
Implementation Details
Codex Integration
The Codex integration utilizes a CodexMcpClient to manage interactive sessions. It supports advanced features like session resumption via transcript files and specialized tool calls for file patching.
- Mode Handling: Supports
default,read-only,safe-yolo, andyolopermission modes. - Session Resumption: Searches for
.jsonlsession files in~/.codex/sessionsto resume context when the mode changes or a session is aborted. - Keep-Alive: Implements a jittered keep-alive mechanism (2000ms base + 0-500ms jitter) to prevent thundering herds on reconnection.
Sources: apps/cli/src/codex/runCodex.ts:18-35, apps/cli/src/codex/runCodex.ts:230-240, apps/cli/src/codex/runCodex.ts:415-440
Gemini Integration
The Gemini implementation (runGemini) is designed to support dynamic model switching (e.g., between gemini-2.5-pro and flash) by recreating the agent backend whenever the requested model hash changes in the message queue.
Tool and Reasoning Processing
Both agents communicate tool interactions through a standardized set of tool definitions. These tools are categorized as "mutable" if they have the potential to modify the filesystem.
- Mutable Tools: Includes
Bash,Edit,Write,MultiEdit, andCodexPatch. - Investigation Tools: Tools like
codebase_investigatorgenerate large result payloads that are logged and processed for objectives. - Reasoning Blocks: Titled reasoning (e.g.,
**Title**) is intercepted by processors and converted into tool calls or system messages for the UI.
Sources: apps/web/react/sources/components/tools/knownTools.tsx:391-410, apps/cli/src/gemini/runGemini.ts:310-330
Configuration and Command Registry
The CLI commands for these agents are defined in a centralized registry that enforces strict naming conventions and documentation standards.
| Command | Subcommands | Primary Options |
|---|---|---|
codex | N/A | --started-by <daemon/terminal> |
gemini | model set, model get | --started-by <daemon/terminal> |
Sources: apps/cli/src/commands/registry.ts:147-175
Exit Behavior and Reliability
Both agents use a defined set of exit codes and implement robust abort/kill logic to ensure that orphan processes are not left running (e.g., stopCaffeinate and happyServer.stop).
- Abort: Stops the current inference/task but keeps the session and event loop alive for new prompts.
- Kill: Terminates the entire process, flushes session state, and closes the WebSocket connection.
- Status 2 (Unhealthy): Returned if the daemon is degraded or the session state is stale.
Sources: apps/cli/src/codex/runCodex.ts:315-350, apps/cli/src/commands/registry.ts:245-252
Conclusion
Codex and Gemini support provides a bridge between high-performance local AI agent execution and the convenience of remote monitoring. By utilizing specialized processors for reasoning and diffs, combined with a secure end-to-end encrypted sync protocol, the system ensures that developers can safely manage complex coding tasks from any device. The architecture prioritizes session persistence and granular permission control, allowing for seamless transitions between terminal-based and mobile-based workflows.
Sources: apps/cli/CLAUDE.md, apps/cli/src/codex/runCodex.ts:680-700