Claude Code Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Integration serves as the core orchestration layer for the Happy CLI, wrapping the Anthropic Claude Code tool to enable multi-mode AI agent interactions. Its primary purpose is to provide a seamless transition between local interactive terminal sessions and remote-controlled sessions via mobile or web clients, all while maintaining end-to-end encryption.
At a high level, the system detects globally installed Claude Code and integrates with it through two primary mechanisms: a PTY-based interactive wrapper for local use and a dynamic SDK import for remote automation. This allows users to start a session at their desk and continue it on the go without losing context or security.
Sources: apps/cli/CLAUDE.md:105-115, CLAUDE.md:215-230
Dual-Mode Operation
The integration operates in two distinct modes: Local (Interactive) and Remote (SDK-driven). The switching logic is managed by a central control loop that handles session persistence and state synchronization.
Local Mode (Interactive)
Local mode wraps the standard Claude Code CLI process. It uses a PTY (Pseudo-Terminal) to capture output and a file watcher to snoop on session files, allowing real-time streaming of local progress to remote observers.
Remote Mode (SDK)
Remote mode utilizes the Claude SDK to programmatically control the agent. In this mode, the CLI receives instructions from the Happy Server (relayed from a mobile app), executes them via the SDK, and streams the results back through an encrypted WebSocket.
Sources: apps/cli/src/claude/loop.ts, apps/cli/CLAUDE.md:117-125
The flow shows how the CLI bifurcates between process spawning for interactive use and SDK interaction for remote control. Sources: apps/cli/src/claude/claudeLocal.ts, apps/cli/src/claude/claudeRemote.ts
Claude SDK Integration
The CLI integrates with @anthropic-ai/claude-code using dynamic imports to handle globally installed versions. This integration allows the CLI to execute queries programmatically while maintaining the exact same environment and project context as the official tool.
Key SDK Components
| Component | Responsibility |
|---|---|
runClaudeRemote | Main entry point for SDK-based session execution. |
dynamicImport | Safely loads the globally installed @anthropic-ai/claude-code package. |
executeQuery | Programmatic function to send prompts to the agent and receive structured output. |
InterruptController | Manages cancellation signals for long-running SDK operations. |
Sources: apps/cli/src/claude/claudeRemote.ts:10-45, apps/cli/src/claude/sdk/index.ts
Message Data Flow (Remote)
When running via the SDK, the data flow follows a strictly encrypted path between the remote client and the local machine.
This diagram illustrates the zero-knowledge relay architecture where the server never sees the plaintext prompt or response. Sources: apps/cli/CLAUDE.md:215-230, apps/cli/src/claude/claudeRemote.ts
Local Process Management
For interactive sessions, the system manages the lifecycle of the claude process. This involves searching for the executable in standard locations (npm, Homebrew, or native installers).
Detection Order
- npm global: Found via
npm root -g. - Homebrew: Checks
/opt/homebrew/bin/claudeor/usr/local/bin/claude. - Native installer: Checks
~/.claude/local/claude.
Sources: apps/cli/CLAUDE.md:195-205
Session Forking and Resumption
The integration handles Claude's --resume behavior by monitoring the creation of new .jsonl session files. When a session is resumed:
- A new session ID is generated by Claude.
- The new session file contains the complete history of the previous session.
- The CLI must update its internal state to track the new ID for subsequent WebSocket updates.
Sources: apps/cli/CLAUDE.md:280-310, apps/cli/src/claude/claudeLocal.ts
Security and Permissions
The integration includes a Model Context Protocol (MCP) layer to intercept and handle permission requests.
MCP Permission Server
When Claude requires a sensitive action (e.g., executing a bash command or reading a file), it makes a tool call via MCP. The Happy CLI intercepts these:
- The request is sent to the remote mobile app.
- The user approves or denies the request on their phone.
- The response is relayed back to the MCP server to allow or block the execution.
Sources: apps/cli/CLAUDE.md:120-130, apps/cli/src/claude/loop.ts
Command Allowlist
To provide defense-in-depth, the CLI enforces a strict allowlist for bash commands executed via remote procedure calls, regardless of AI permission. This prevents execution of dangerous commands like ; rm -rf /.
Sources: apps/cli/src/modules/common/pathSecurity.ts, apps/cli/CLAUDE.md:165-180
Conclusion
The Claude Code Integration transforms a standard CLI-based AI agent into a distributed, multi-device platform. By balancing high-performance local PTY wrapping with flexible SDK automation, it ensures that Claude Code remains accessible and secure regardless of the user's location or device.