BeachViber

Control Claude Code from your phone. Send prompts, approve tools, and monitor sessions remotely through an end-to-end encrypted connection.

Phone App ←—(encrypted)—→ Relay Server ←—(encrypted)—→ Computer Agent ←—→ Claude Code

Install

npm install -g @beachviber/agent

Requires Node.js 20+ and Claude Code 2.0.0+ on your PATH.

Quick Start

beachviber

On first run:

1. A QR code appears — scan it with the BeachViber App
2. In your terminal, enter the verification code shown on your BeachViber App
3. Done — you're paired and encrypted end-to-end

On subsequent runs, the agent reconnects automatically.

What You Can Do

From your phone:

• Browse projects on your machine
• Start Claude Code sessions and send prompts
• Approve or deny tool use (file writes, shell commands, etc.)
• View session history and transcripts
• Manage multiple desktops from one phone

Security

End-to-end encrypted. All sensitive messages (prompts, responses, tool approvals) are encrypted with X25519 + AES-256-GCM. The relay server cannot read message contents.

Keys stay on your machine. Private keys are stored in the OS keychain (macOS Keychain, Linux Secret Service, or Windows DPAPI fallback) as PKCS8 DER — never in plaintext config files.

Tool approval via control protocol. The agent uses Claude Code's --permission-prompt-tool stdio protocol to intercept tool calls in real time. Tools already in your Claude allow list are auto-approved. Everything else is sent to your phone for approval.

Configuration

The agent stores config in ~/.beachviber/.

Uninstall

npm uninstall -g @beachviber/agent

Protocol

The agent communicates over WebSocket using JSON messages. Each message has a type, optional sessionId, timestamp, and payload. When paired, the payload is replaced with an encrypted field containing an AES-256-GCM envelope.

| Type | Direction | Description | |------|-----------|-------------| | register | Desktop → Relay | Register with device token and public key | | registered | Relay → Desktop | Registration confirmed | | hello | Phone → Desktop | Phone handshake with version info | | hello_ack | Desktop → Phone | Handshake response with capabilities | | projects_request | Phone → Desktop | List available projects | | projects_response | Desktop → Phone | Project list with git info | | session_create | Phone → Desktop | Start a Claude Code session | | session_created | Desktop → Phone | Session started confirmation | | session_end | Phone → Desktop | End a session | | sessions_request | Phone → Desktop | List all sessions | | sessions_response | Desktop → Phone | Session list with metadata | | prompt | Phone → Desktop | Send a prompt to Claude | | stream_start | Desktop → Phone | Claude started responding | | stream_delta | Desktop → Phone | Streaming text/tool-use chunk | | stream_meta | Desktop → Phone | Status metadata (thinking, compacting, usage) | | stream_end | Desktop → Phone | Claude finished responding | | tool_approval_request | Desktop → Phone | Tool needs approval | | tool_approval_response | Phone → Desktop | Approve/deny tool use | | session_history_request | Phone → Desktop | Get session transcript | | session_history_response | Desktop → Phone | Transcript messages | | stop | Phone → Desktop | Interrupt current Claude response | | rename_session | Phone → Desktop | Rename a session | | process_spawned | Desktop → Phone | Claude process started for session | | wake | Phone → Desktop | Unlock the agent remotely | | sleep_notify | Desktop → Phone | Agent locked (timer expired) | | verify_code | Desktop → Phone | Pairing verification code | | verify_code_ack | Phone → Desktop | Verification result + public key | | heartbeat | Desktop → Relay | Keep-alive |

Learn More

https://www.beachviber.com

Contributing

See CONTRIBUTING.md for development setup, project structure, and guidelines.

License

MIT