How It Works
Happy Coder lets you watch and control Claude Code from your phone. It uses strong end to end encryption to keep your code private. This page explains how the system works.
The Three Parts
Happy Coder has three main parts that work together:
1. CLI Program (happy) - This runs on your computer. It starts Claude Code
and watches what it does. Then it encrypts this information and sends it to a
server.
2. Mobile App - This runs on your phone. It gets the encrypted data from the server and shows you what Claude Code is doing. All the display code lives here.
3. Relay Server - This connects your computer and phone. It passes encrypted messages between them. The server can't read your data - it just moves encrypted blobs around.
flowchart LR
%% --- Nodes (with responsibility sublabels) ---------------------------
subgraph Computer
happy["CLI<br>Encrypts & Sends"]
end
subgraph Happy Server
relay["Relay Server<br>Stores & Forwards"]
end
subgraph Phone
app["Mobile App<br>Decrypts & Displays"]
end
%% --- Encrypted data flow --------------------------------------------
happy -->|encrypted data| relay
relay -->|encrypted blob| app
%% --- Styling ---------------------------------------------------------
classDef nodeGrey fill:#d3d3d3,stroke:#a9a9a9,color:#000,stroke-width:1.5px;
class happy,relay,app nodeGrey
classDef linkGrey stroke:#a9a9a9,stroke-width:1.5px;
linkStyle 0,1 stroke:#a9a9a9,stroke-width:1.5px;
Why You Need the Relay Server
The server solves a simple problem: firewalls. Your phone and computer are usually on different networks. They can't talk directly to each other.
The server acts like a post office. Both your phone and computer connect out to the server. This works because firewalls usually allow outgoing connections. The server stores messages until both devices are ready.
Without the server, you'd need to set up port forwarding and deal with changing IP addresses. That's hard and often doesn't work on mobile networks.
Trust and Security
You might wonder: "The developers run the server. Why should I trust them?"
Good question! You don't have to trust us. Here's why:
Your Data Stays Private
Your computer shows a QR code with a one-time public key. Your phone scans it and sends back your account's public key, sealed so only your computer can open it. For each session your computer makes a random key, encrypts your data with it, and stores that key on the server locked to your account's public key. The server only sees encrypted blobs - it can't read them.
Diagram needed: Show the encryption flow. QR code containing the CLI's one-time public key, scanned by the phone; the phone sends back the account's public key; each session gets its own random key, wrapped with that public key.
How Your Devices Connect
Your phone (or browser) logs in with a key derived from your account secret:
Zero Round-Trip Authentication: The device sends everything at once:
- The device picks a random challenge (not the server!)
- The device signs this challenge with its secret key
- The device sends: challenge + signature + public key
The server checks the signature matches the public key. If it does, it issues a token. This happens instantly - no back-and-forth needed. Your computer receives its token when you approve its QR code from your phone.
Extra Security: The server stores your account's public signing key, never a secret key.
This design stops many attacks. The server can't trick you into revealing your secret key. Even if someone hacks the server, they can't read your data.
Diagram needed: Show the authentication flow with challenge-response mechanism. Include the public key hash as channel ID, and the cryptographic proof process.
Run Your Own Server
The server is open source (about 12,000 lines of TypeScript). You can:
- Check that it really just forwards messages
- Run your own server (takes 2 minutes to set up)
- Write your own server from our spec
Both the phone app and CLI have settings to use your own server. It's easy to switch.
How Data Moves
When you run happy on your computer:
- The CLI starts Claude Code
- Claude Code starts working on your project
- The CLI watches what Claude Code does
- It encrypts this information with your secret key
- It sends the encrypted blob to the server
- The server saves the blob and sends it to your phone
- Your phone decrypts it and shows you what's happening
The server never knows what you're working on. Your messages, code and session metadata reach it only as encrypted data.
Why Save Encrypted Blobs?
The server saves encrypted blobs for two good reasons:
See Your History: When you close Claude Code, the CLI program stops. But you can still open your phone app next week and see what you built. You can copy old ideas into new projects. This is really helpful for keeping track of your work.
Handle Bad Connections: This is the big one. Say you're on a train or hiking. Your phone loses signal all the time. But your computer at home stays connected to the server. It keeps sending updates about what Claude Code is doing.
When your phone gets signal again, it catches up on everything it missed. You don't lose any messages. You can check Claude Code's progress whenever you have signal.
Diagram needed: Show the resilient connection scenario - CLI with stable connection continuously uploading, phone with intermittent connection catching up on missed messages when it reconnects, database storing all encrypted blobs in between.
For Contributors
Every part of Happy Coder is open source: the CLI, the app, and the relay server. We use a relay server to connect your devices across different networks. The server can't read your data because everything is encrypted with keys that never leave your devices.
Important: Keep the server dumb. Don't add server features. Put your logic in the mobile app where it belongs. If you need more capabilities from the CLI, keep it simple there too. Use the generic API to run a command and report the output back to the mobile app. Do not build lots of logic into the CLI. Let the mobile app do the real work.
Summary
This design keeps your code private no matter what happens to the server. Even if someone hacks it, they just get encrypted blobs they can't read. The server knows nothing and can tell nothing. That's the whole point.