Paws CLI

Independently maintained Paws CLI, published as @wangjs-jacky/paws. Paws originated from the MIT-licensed Happy project but now has its own product and release line. Source: wangjs-jacky/happy.

Code on the go — control AI coding agents from your phone, browser, or terminal.

Free. Open source. Code anywhere.

Installation

npm install -g @wangjs-jacky/paws

This installs paws as the primary command and happy as a compatibility alias.

Note: the happy command name conflicts with the official happy / happy-coder npm packages. If you have one of them installed globally, remove it first (npm rm -g happy happy-coder), or install with --force and use paws.

Server

By default Paws connects to the relay configured by the current build. Session payloads are end-to-end encrypted before synchronization; relay infrastructure still processes operational metadata needed for routing and delivery.

To use your own relay, deploy happy-server and point the CLI (and the mobile/web app) at it:

# one-off
HAPPY_SERVER_URL=https://your-server.example.com paws

# or persist it in ~/.happy/settings.json
{
  "serverUrl": "https://your-server.example.com",
  "webappUrl": "https://your-webapp.example.com"
}

Usage

Claude Code (default)

paws
# or
paws claude

This will:

1. Start a Claude Code session
2. Display a QR code to connect from your mobile device or browser
3. Allow real-time session control — all communication is end-to-end encrypted
4. Start new sessions directly from your phone or web while your computer is online

More agents

paws codex
paws gemini
paws openclaw

# or any ACP-compatible CLI
paws acp opencode
paws acp -- custom-agent --flag

Daemon

The daemon is a background service that stays running on your machine. It lets you spawn and manage coding sessions remotely — from your phone or the web app — without needing an open terminal.

paws daemon start
paws daemon stop
paws daemon status
paws daemon list

The daemon starts automatically when you run paws, so you usually don't need to manage it manually.

Keeping the daemon running across reboots

If you want the daemon to come back automatically after a reboot — without opening a paws session first — start it from your shell profile so it inherits your normal user session context (PATH, keychain access, OAuth credentials):

# ~/.zshrc or ~/.bashrc
if [[ -o interactive ]] && [[ -z "$HAPPY_DAEMON_CHECKED" ]]; then
    export HAPPY_DAEMON_CHECKED=1
    () {
        local state=$HOME/.happy/daemon.state.json
        local pid=$(grep -oE '"pid"[[:space:]]*:[[:space:]]*[0-9]+' "$state" 2>/dev/null | grep -oE '[0-9]+')
        if [[ -z "$pid" ]] || ! kill -0 "$pid" 2>/dev/null; then
            paws daemon start >/dev/null 2>&1
        fi
    } &!
fi

The first interactive shell after a reboot triggers the start; subsequent shells short-circuit because the daemon is already running.

macOS users: prefer this shell-init approach over a launchd LaunchAgent. A LaunchAgent runs in an agent domain that is detached from your GUI/Aqua login session, which means the bundled claude-agent-sdk cannot reach the macOS keychain and silently fails authentication ("Failed to authenticate. API Error: 401 terminated", duration_api_ms: 0). If you must use launchd, your wrapper has to read the OAuth access token from ~/.claude/.credentials.json and export it as CLAUDE_CODE_OAUTH_TOKEN before exec'ing the daemon — and you'll need to handle token rotation yourself.

Authentication

paws auth login
paws auth logout

Paws uses cryptographic key pairs for authentication — your private key stays on your machine. Session payloads are end-to-end encrypted before synchronization.

To connect third-party agent APIs:

paws connect gemini
paws connect claude
paws connect codex
paws connect status

Commands

| Command | Description | |---------|-------------| | paws | Start Claude Code session (default) | | paws codex | Start Codex mode | | paws gemini | Start Gemini CLI session | | paws openclaw | Start OpenClaw session | | paws acp | Start any ACP-compatible agent | | paws resume <id> | Resume a previous session | | paws notify | Send push notification to your devices | | paws doctor | Diagnostics & troubleshooting |

Advanced

Environment Variables

| Variable | Description | |----------|-------------| | HAPPY_SERVER_URL | Custom server URL (default: maintainer's self-hosted relay) | | HAPPY_WEBAPP_URL | Custom web app URL (default: maintainer's self-hosted webapp) | | HAPPY_HOME_DIR | Custom home directory for Paws data (default: ~/.happy) | | HAPPY_DISABLE_CAFFEINATE | Disable macOS sleep prevention | | HAPPY_EXPERIMENTAL | Enable experimental features | | HAPPY_CODEX_APP_SERVER_MODE | Codex transport: spawn (default) or experimental shared Unix Socket mode | | HAPPY_CODEX_APP_SERVER_SOCKET | Absolute path to a shared Codex app-server socket (default: $CODEX_HOME/app-server-control/app-server-control.sock) | | HAPPY_CODEX_APPROVAL_AUTHORITY | Shared-mode approval responder: desktop (default) or paws |

Shared Codex Desktop Thread (experimental)

By default, paws codex starts its own Codex app-server over stdio. Shared mode instead attaches Paws to an already running, protocol-compatible Codex app-server over its Unix control socket:

HAPPY_CODEX_APP_SERVER_MODE=shared \
HAPPY_CODEX_APPROVAL_AUTHORITY=desktop \
paws codex --resume <codex-thread-id>

This lets Codex Desktop and Paws observe and continue the same persisted Codex Thread through one writer process. From inside the current Codex Thread, the installed /paws skill runs happy attach; it discovers CODEX_THREAD_ID and starts the shared Paws bridge in the background, so no Thread ID needs to be copied manually. A newly attached Paws Session receives the existing Thread history. On reconnect, its saved turn cursor backfills only the Desktop Turns created while the bridge was offline. Turns entered in either client are mirrored into Paws without echoing a Paws-originated user message twice.

Shared mode does not start, upgrade, or stop the app-server. The socket must already exist, and its Codex version must be compatible with the clients. Codex Desktop also has to be launched in its local-daemon mode so it uses that same server; this is not the Desktop app's default setup.

Only one approval responder should be active. Keep the default desktop value while Desktop owns approvals; select paws only when Paws should answer them. The mode is designed for handoff, not simultaneous competing user Turns. Wait for the active Turn to finish before continuing from the other client.

Sandbox (experimental)

Paws can run agents inside an OS-level sandbox to restrict file system and network access.

paws sandbox configure
paws sandbox status
paws sandbox disable

Building from source

git clone https://github.com/wangjs-jacky/happy
cd happy
pnpm install
pnpm --filter @wangjs-jacky/paws run build
node packages/happy-cli/bin/happy.mjs --help

Requirements

• Node.js >= 20.0.0
• For Claude: claude CLI installed & logged in
• For Codex: codex CLI installed & logged in
• For Gemini: npm install -g @google/gemini-cli + paws connect gemini

License

MIT