Paws

Control the AI coding agents running on your computer — right from your phone.

Run paws claude or paws codex on your computer, then watch progress, send instructions and approve permissions from the mobile or web app.
End-to-end encrypted. Fully self-hostable.

🌐 Website • 📱 Android APK • 📦 CLI on npm • 📚 Getting Started • 🇨🇳 中文

---

Paws is an independently maintained, heavily customized fork of Happy — rebranded with its own app builds, CLI package, self-hosted OTA pipeline and website. Everything documented here refers to this fork; for upstream credits see Acknowledgements.

🚀 Quick Start

1. Install the CLI on your computer

npm install -g @wangjs-jacky/paws

This provides the paws and happy commands (plus paws-mcp / happy-mcp for MCP integration).

2. Get the app on your phone

Download the latest Android APK from GitHub Releases (arm64, sideload install). A web app is also bundled with the self-hosted server.

3. Wrap your agent and pair

# Instead of claude / codex, run:
paws claude
# or
paws codex

Scan the QR code with the app to pair — from then on the session is mirrored to your phone.

4. (Optional) Let your phone start new sessions

paws daemon start

With the daemon running, the app can spawn fresh sessions on this machine remotely — no desk visit needed.

For source installs, server options, app builds and troubleshooting, read the Getting Started guide (中文版).

🐾 Why Paws?

• 📱 Remote control for your coding agents — Claude Code, Codex, Gemini, OpenCode and other ACP-compatible agents
• 🔔 Reliable push notifications — direct FCM on Android, and alerts fire even while the app is in the foreground
• 🖼️ Full image workflow — attach images when creating a session, HEIC auto-normalization, fullscreen image viewer
• ⚡ Switch devices instantly — take over from phone or desktop with one keypress
• 🔐 End-to-end encrypted — the sync server only ever relays ciphertext; your code and conversations stay private
• 🏠 Fully self-hostable — run your own sync server (Docker, zero-config PGlite) and your own OTA update channel

🔧 How It Works

Mobile / Web App
    |
    |  HTTP + WebSocket, end-to-end encrypted payloads
    v
Sync Server (self-hosted or upstream)
    |
    |  encrypted sync, machine presence, session state
    v
paws CLI / daemon on your computer
    |
    v
Claude Code / Codex / Gemini / OpenCode / ACP-compatible agents

The CLI wraps your agent's terminal session. Keep working locally as usual; when you pick the session up from your phone it seamlessly switches to remote mode, and any keypress on your keyboard takes it back.

✨ What's Different from Upstream Happy?

Area	Paws
Branding	Marmot mascot, Paws app name, splash & mascot-linked theme
CLI distribution	Published on npm as @wangjs-jacky/paws with trusted-publishing CI
Android push	Migrated from Expo Push to direct FCM; notifications also shown in-foreground, tap to jump into the session
Images	Restored image upload, first-screen attachments, fullscreen viewer, HEIC normalization for vision models
OTA updates	Self-hosted OTA pipeline with preview / production channels, per-PR preview builds, and a version browser site to pin any historical build via QR code
Extras	Health check-in dashboard fed by your own Markdown notes, desktop screenshot capture, session attach command, and a steady stream of UX fixes

📦 Project Components

Package	What it is
packages/happy-app	Mobile + web client (Expo) — ships as the Paws app
packages/happy-cli	The paws CLI — wraps Claude Code / Codex, daemon, MCP tools
packages/happy-server	Self-hostable sync server with bundled web app
packages/happy-agent	CLI for controlling agents remotely (create, send, monitor)
packages/happy-wire	Shared wire types & Zod schemas

Related repositories:

• paws-landing — the product website, built with an AI-driven design → deploy pipeline
• happy-ota-site — OTA version browser (scan a QR to pin a build)

🏠 Self-Hosting

The sync server is a single Docker container with zero-config embedded PGlite (or external PostgreSQL). Point the CLI and app at it and the loop is closed — nothing leaves your network:

export HAPPY_SERVER_URL=http://your-server:3005
paws claude

See the Getting Started guide and the intranet deployment manual for full instructions.

🙏 Acknowledgements

Paws began as a fork of Happy by the slopus team — a brilliant piece of engineering, generously MIT-licensed. The happy package on npm and the Happy apps in the App Store / Play Store belong to upstream; this fork ships its own CLI (@wangjs-jacky/paws) and its own app builds.

📄 License

MIT — see LICENSE for details.