# Happy: a mobile and web client for Claude Code and Codex

> Happy wraps the Claude Code and Codex CLIs so you can watch and drive a running session from a phone, with end-to-end encryption and a self-hostable server. It is a convenience layer, not a replacement for either agent.

**slopus/happy** — Mobile and Web client for Codex and Claude Code, with realtime voice, encryption and fully featured

- Repository: https://github.com/slopus/happy
- Website: https://happy.engineering
- Stars: 23,910 · Forks: 2,037
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/slopus-happy

## What Happy adds on top of Claude Code and Codex

Claude Code and Codex are terminal programs. They run where your files are, they stop when they need permission, and they keep going while you are away from the keyboard. Happy targets that gap. The README frames the project as a mobile and web client for both tools, and the stated reason for building it is the authors wanting to "peek at our AI coding tools" during lunch breaks rather than sit at a desk.

The audience is narrow and specific: people who already use one of those two agents daily and want a second screen for it. Happy does not add a model, an agent loop, or a code index. It wraps an existing CLI and relays the session. If you do not run Claude Code or Codex today, there is nothing here for you to wrap.

The repository is a pnpm monorepo. The workspace list in package.json names happy-app (the Expo web and mobile client), happy-cli, happy-agent (a remote control CLI for creating, sending to and monitoring sessions), happy-server (the encrypted sync backend), happy-server-self-host, happy-wire, happy-app-logs and expo-tailcat. That split tells you where the boundaries are: the client, the wrapper, the relay, and the protocol.

## How the session actually moves between your laptop and your phone

The mechanism is a wrapper, not a plugin. You start your agent through Happy instead of starting it directly, and Happy sits between the terminal and the client. The README describes the transition in one sentence: when you want to control the agent from your phone, it restarts the session in remote mode, and to switch back to the computer you press any key on the keyboard.

That restart is the part worth understanding before you rely on it. The session is not mirrored; control is handed over. A keypress on the machine takes it back. The README does not describe what happens to an in-flight tool call at the moment of the switch, and it does not document how a half-written file or a pending permission prompt is handled across the handover. Treat the switch as a control transfer and test it on a throwaway repository before you trust it on a branch you care about.

Encryption is claimed at the transport level. The README says code never leaves your devices unencrypted, and the server package is described as the backend for encrypted sync. The repository also ships a self-host variant (happy-server-self-host) and a standalone Dockerfile that the comments describe as a single container with PGlite, local filesystem storage and no Redis. If you want to verify the encryption story rather than take the README's word for it, that is the code to read: the wire package defines the protocol, the server package implements the relay.

## Installing the CLI and starting a wrapped session

The README gives four steps: download an app, install the CLI, start your agent through it, and optionally grab the desktop build. The CLI install is a single global npm package. The README notes the package was migrated from happy-coder and that the happy name was donated.

```bash
npm install -g happy
```

After that, you change the command you type, not your workflow. To run Claude Code through Happy, the README shows:

```bash
happy claude
```

and for Codex:

```bash
happy codex
```

What you should see is your normal agent session, started through the wrapper. From there the client apps are the other half of the setup: an iOS build on the App Store, an Android build on Google Play, a web app at app.happy.engineering, and a separate macOS app in the slopus/happy-desktop repository. The README presents the desktop app as an alternative for people who would rather not work in a terminal.

One practical note the README states plainly: you run happy in place of claude or codex. Anything you previously did by invoking those binaries directly bypasses Happy entirely, including any shell aliases or scripts that call them by name.

## The self-hosted server and what the Dockerfile commits you to

For teams that cannot send session data through someone else's relay, the repository includes a self-host package and a Dockerfile. The Dockerfile header describes a standalone happy-server: a single container, no external dependencies, PGlite as an embedded Postgres, local filesystem storage, and no Redis. The runtime stage sets NODE_ENV=production, DATA_DIR=/data and PGLITE_DIR=/data/pglite, and installs ffmpeg and curl on top of node:20-slim.

That is a deliberate trade. Embedded Postgres and local files mean one container to run and one volume to back up, at the cost of the scaling and operational tooling a real Postgres deployment gives you. The build stage is also heavy: it activates pnpm 10.11.0 through corepack, installs python3, make and g++ for native modules, and copies the workspace package manifests individually before running pnpm install --frozen-lockfile with SKIP_HAPPY_WIRE_BUILD=1. Expect a slow first build.

The monorepo also carries an environments tool with scripts such as env:new, env:up, env:down, env:server, env:web, env:ios, env:android and env:cli. Those are for developing Happy itself, not for using it, and the README does not present them as a user-facing path.

## Where Happy is the wrong tool

The clearest limitation is the one the README states as a feature: the session restarts when it goes remote. If you are running a long, stateful operation and cannot tolerate a restart, remote mode is not a safe place to be. The documentation does not describe rollback, session recovery, or what a client disconnect mid-turn does to the agent's state.

Second, the wrapper only covers two agents. There is no general-purpose terminal relay here, and the CLI's job is to launch claude or codex under supervision. If your stack is built around a different agent, Happy has no entry point for you.

Third, the trust model. The README says there is no telemetry and no tracking, and that the code is open source so you can audit it. That is a claim about the client and CLI. If you use the hosted web app rather than the self-hosted server, your session still traverses infrastructure you do not operate, encrypted or not. The repository gives you the means to avoid that, and whether you need to is a policy question only your team can answer.

Finally, the release history in the repository shows the CLI on 1.2.5 beta builds (cli-1.2.5-beta.0 through beta.2, dated 2026-09-14 and 2026-09-20). Beta-tagged releases for the component that sits between you and your agent are worth weighing if you need a stable surface.

## How Happy differs from running the agent over SSH or tmux

The obvious alternative is not another product; it is ssh plus tmux. You keep the session on the machine, attach from a phone terminal client, and get the same screen. The difference is in what the two approaches optimize for.

tmux gives you the raw terminal. Nothing is re-encoded, nothing is relayed through a sync server, and there is no restart when you attach, because attaching does not move the process. What tmux does not give you is a native mobile interface, push notifications when the agent is waiting on a permission prompt, or a web client. Happy's README lists all three as reasons to use it, and those are exactly the things a terminal multiplexer will never do.

So the split is honest: choose tmux if you want the session untouched and you are comfortable in a mobile SSH client; choose Happy if the value is the notification and the purpose-built client, and you accept a restart on handover plus a relay in the path. Happy also ships a desktop app for macOS, which tmux obviously does not, though that app lives in a separate repository and is not part of this one.

## Maintenance, licensing and what the repository tells you

The last push to the default branch was on 2026-09-20, and the most recent release is cli-1.2.5-beta.2 from the same day. The repository is not archived. That is a recent commit history, and the release cadence across 2026-09-14 and 2026-09-20 shows active work on the CLI package in particular.

Licensing is MIT, per the README and the LICENSE file at the repository root. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are preserved. That covers the code in this repository. It does not automatically cover the hosted service at happy.engineering, the App Store or Google Play builds, or the separate macOS app, and it says nothing about the terms of Claude Code or Codex themselves, which you still need to satisfy. This is a description of the licence text, not legal advice.

The upgrade cost is mostly the usual one for a global npm CLI: you reinstall to move versions, and the CLI sits between you and your agent, so a regression there is felt immediately. The monorepo's own tooling (pnpm workspaces, the environments scripts) matters only if you fork or contribute; for users, the surface is the happy command and the client apps. The README does not document a version pinning strategy or a compatibility matrix between CLI versions and agent versions, so if that matters to you, it is something to check in the repository rather than assume.

## Conclusion

Happy fits engineers who already run Claude Code or Codex in a terminal and want to check on or unblock a session from a phone, and who accept routing through a sync server they can either trust or self-host. Skip it if your work cannot leave a managed environment, if you need a documented rollback path, or if you are not already a Claude Code or Codex user, since Happy adds nothing on its own. Before adopting it, run npm install -g happy on one machine, start happy claude, and confirm the switch to remote mode and back actually behaves the way the README describes.

## FAQ

### What is Happy, the mobile client for Claude Code and Codex?

It is a mobile and web client that wraps the Claude Code and Codex command-line tools so you can control a running session from a phone. You install the CLI with npm install -g happy and start your agent with happy claude or happy codex instead of the original command.

### How do I install Happy?

The README gives a single command, npm install -g happy, followed by downloading one of the client apps for iOS, Android, web or macOS. The package was migrated from happy-coder.

### Does Happy work without sending my code to a server?

The README states that code never leaves your devices unencrypted, and the repository includes a self-host package plus a standalone Dockerfile for happy-server that uses embedded Postgres and local filesystem storage. The README does not document the encryption scheme in detail, so the wire and server packages are where to verify it.

### What happens to my session when I switch to my phone?

According to the README, the session restarts in remote mode when you take control from a phone, and pressing any key on your computer switches it back. The README does not describe how an in-flight tool call or a pending permission prompt is handled across that restart.

### Is Happy a replacement for Claude Code or Codex?

No. Happy launches those agents through a wrapper; it does not provide a model or an agent of its own. The README describes running happy claude or happy codex in place of the original commands.

## Sources

- [License: MIT](https://github.com/slopus/happy/blob/main/LICENSE)
- [Project website](https://happy.engineering)
- [README](https://github.com/slopus/happy/blob/main/README.md)
- [Releases](https://github.com/slopus/happy/releases)
- [slopus/happy on GitHub](https://github.com/slopus/happy)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/slopus-happy