pingpal

The user-facing CLI for PingPal — this is the package published as pingpal and the thing you npx. It owns identity, config, and the one-command Claude Code setup; the long-lived work happens in the @pingpal/daemon it starts.

npx pingpal init                 # set handle/room/face + wire up Claude Code
npx pingpal join our-team-code   # switch rooms (restarts the daemon)
npx pingpal start                # start the background daemon

Commands

| Command | What it does | | --- | --- | | pingpal init | Prompt for handle / room / face, write ~/.pingpal/config.json, install the push hook (UserPromptSubmit) into ~/.claude/settings.json, and register the MCP server under mcpServers in ~/.claude.json. Idempotent. | | pingpal join <room> | Set/switch your room and restart the daemon so it reconnects. --handle to change handle too. | | pingpal start / stop | Start / stop the background pingpald daemon. | | pingpal status | Daemon + relay + LAN status and a who's-online roster. | | pingpal whoami | Print your current handle, room, and face. | | pingpal relay | Show which relay your room lives on, where that setting came from (PINGPAL_RELAY, config, or default), and whether it is reachable and new enough to host Meet-style rooms. Non-zero exit when it can't. | | pingpal relay use <public\|url> | Point at a relay and write it to ~/.pingpal/config.json — public for the shared instance, or a ws:// / wss:// URL. Probes first and refuses an unreachable or too-old relay; --force sets it anyway. | | pingpal relay deploy <railway\|fly> | Stand up your own relay on Railway or Fly. Both log in through a browser, so if you aren't logged in it prints the command and stops rather than hanging. | | pingpal doctor [--fix] [--json] [--strict] | Check config, relay, daemon, and the Claude Code wiring (hook, MCP server, status line), printing the fix next to each failure. --fix applies the safe repairs, --json emits the checks as JSON, --strict promotes warnings to failures. Exits 0 all-clear, 1 something is broken, 2 warnings only. |

init accepts --handle, --room, --face, --relay to skip the prompts, and --no-hook / --no-mcp to skip either Claude Code integration. pingpal --help documents everything.

init also asks where your room lives — the shared public relay, or one you host. Both are end-to-end encrypted; they differ on who sees the metadata. See Choosing a relay.

What init touches (and how safely)

Both writes are read-modify-write JSON merges that never clobber unrelated keys, and re-running init updates the existing entry in place instead of duplicating it (see claude-settings.ts and its tests):

• Hook → a command hook on the UserPromptSubmit event in ~/.claude/settings.json, running the bundled hook/pingpal-hook.mjs. (UserPromptSubmit because its stdout is injected into the session as context the assistant acts on; Notification only surfaces stderr and Stop's stdout is discarded.)
• MCP → a stdio server entry named pingpal under mcpServers in ~/.claude.json.

Both are registered by absolute path to the bundled Node entry points, so they keep working after a global install where dependency bins aren't on PATH. CLAUDE_HOME overrides the base directory (handy for dry runs and the tests).

Development

pnpm --filter pingpal build
pnpm --filter pingpal test   # settings.json merges, config store, relay probe + `relay use`