Development

This guide is for working on remote-cli locally.

Prerequisites

• Go 1.23+
• Node.js 20+
• npm
• SQLite CGO build support
• Docker, if testing the container
• Claude Code, if testing real agent sessions

Run Relay

go run ./cmd/relay

Useful env vars:

RELAY_ADDR=:8080
RELAY_DB=relay.db
RELAY_URL=http://localhost:8080
RELAY_STATIC_DIR=pwa/dist
RELAY_JWT_SECRET=dev-secret-change-me
RELAY_ADMIN_PASSWORD=dev-password

Run PWA In Dev Mode

cd pwa
npm install
VITE_RELAY_URL=http://localhost:8080 npm run dev

Open:

http://localhost:5173

Run Full Stack Locally

Build PWA:

cd pwa
npm run build
cd ..

Run relay:

go run ./cmd/relay

Open:

http://localhost:8080

Run Agent

Pair:

go run ./cmd/agent pair --relay http://localhost:8080

Run:

go run ./cmd/agent run

Run after pairing:

go run ./cmd/agent pair --relay http://localhost:8080 --run

Status:

go run ./cmd/agent status

Unpair:

go run ./cmd/agent unpair

Service helpers are available in built binaries on macOS and Linux:

remote-cli service install
remote-cli service logs

Tests And Builds

Go:

go test ./...
go build ./cmd/relay
go build ./cmd/agent

PWA:

cd pwa
npm run build
npm run lint

Docker:

docker compose build

Debugging Message Flow

Watch relay logs for:

phone connected
agent registered
session started
session ended

Watch agent logs for:

connected as
session start
claude pid
claude init
turn complete
claude stderr

If no response appears in the PWA, first verify:

claude --print "Reply with OK"

on the agent machine.

Local Data

Relay DB:

relay.db

Agent config:

~/.config/remote-cli/config.toml

For development, deleting these resets state. Do not delete production state without a backup.

Release Workflow

The release workflow is intended to run on tags:

v*

It builds agent binaries and publishes a relay Docker image.

Before using it publicly, confirm repository owner/name, GHCR permissions, and release asset names.