Development

This guide is for working on remote-cli locally.

Prerequisites

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

remote-cli uses a pure-Go SQLite driver, so local CGO SQLite setup is not required for normal builds.

Run The Unified CLI

go run ./cmd/remote-cli --help
go run ./cmd/remote-cli version

The compatibility entrypoints still exist:

go run ./cmd/agent --help
go run ./cmd/relay

New work should target cmd/remote-cli.

Run Relay

Build the PWA once if you want the relay to serve local assets from disk:

cd pwa
npm install
npm run build
cd ..

Run:

RELAY_ADMIN_PASSWORD=dev-password \
go run ./cmd/remote-cli relay start --url http://localhost:8080 --static-dir pwa/dist

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 Agent

Pair and start:

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

Run after pairing:

go run ./cmd/remote-cli run

Status:

go run ./cmd/remote-cli status

Unpair:

go run ./cmd/remote-cli unpair

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

remote-cli service install
remote-cli service status
remote-cli service logs

Tests And Builds

Go:

go test ./...
go vet ./...
CGO_ENABLED=0 go build ./cmd/remote-cli

PWA:

cd pwa
npm run build
npm run lint

npm package smoke:

CGO_ENABLED=0 go build -o /tmp/remote-cli ./cmd/remote-cli
cd npm/remote-cli
npm pack --ignore-scripts
REMOTE_CLI_BINARY=/tmp/remote-cli node bin/remote-cli.js version

Docker:

docker compose build

Embedded PWA Assets

Release builds run:

cd pwa
npm ci
npm run build
cd ..
rm -rf internal/relay/static/dist
mkdir -p internal/relay/static/dist
cp -R pwa/dist/. internal/relay/static/dist/
go build ./cmd/remote-cli

The repository keeps a tiny fallback internal/relay/static/dist/index.html so Go builds work before a PWA build has been staged.

Local Data

Relay config:

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

Relay DB:

~/.config/remote-cli/relay.db

Agent config:

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

Older ~/.config/remote-cli/config.toml agent configs are migrated automatically.

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

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 on the agent machine:

claude --print "Reply with OK"

Release Workflow

The release workflow runs on tags:

v*

It builds:

• remote-cli-darwin-arm64
• remote-cli-darwin-amd64
• remote-cli-linux-arm64
• remote-cli-linux-amd64
• checksums.txt
• a relay Docker image for advanced deployments

If NPM_TOKEN is configured, the workflow publishes npm/remote-cli to npm with the tag version.