rcpilot 0.8.3

Lightweight self-hosted session manager for Claude Code Remote Control

rcpilot

Claude Code RC is powerful but ephemeral. rcpilot gives it a home.

rcpilot is a lightweight, self-hosted session manager for Claude Code Remote Control. Run it on a Raspberry Pi (or any always-on machine) and get a polished, mobile-friendly web UI to launch, manage, and reconnect to your coding sessions from anywhere — phone, tablet, or browser.

---

What it does

Claude Code's Remote Control mode gives you a shareable session URL. That's great, but it has no persistence, no history, and no management layer. rcpilot wraps it with everything that's missing:

• Launch sessions from any device via a clean web UI
• Reconnect to running sessions — RC URLs are stored and always one tap away
• Full session history per project — every session logged with start time, duration, and status
• Terminal snapshots — captured on session end and browsable any time
• Multiple concurrent sessions per project, all tracked independently
• YOLO mode — one toggle to run sessions with --permission-mode bypassPermissions
• Usage window scheduler — cron-based background job fires claude -p "hi" to start the 5-hour rolling usage window at configured times
• Session naming — auto-named by timestamp, rename anything inline
• Git integration — view diffs, pull, commit, and push without leaving the UI
• PR review — trigger a full Claude code review on any open GitHub PR
• Watchdog — background process monitor marks crashed or timed-out sessions automatically
• Sessions survive restarts — the server can restart without killing active Claude sessions

---

---

Quick start

One-shot demo (no install)

Try it immediately with no installation:

uvx rcpilot

Open http://localhost:8000 in your browser. Config is auto-created at ~/.config/rcpilot/config.toml on first run.

Persistent install

For a machine you want to run rcpilot on permanently:

uv tool install rcpilot

This puts rcpilot on your PATH. Run it manually:

rcpilot

Or set it up as a systemd service so it starts on boot and restarts on crash:

# Download the unit file
curl -o ~/.config/systemd/user/rcpilot.service \
  https://raw.githubusercontent.com/kjozsa/rcpilot/main/rcpilot.service

# Enable and start
systemctl --user enable --now rcpilot

# Check status / logs
systemctl --user status rcpilot
journalctl --user -u rcpilot -f

On a Pi, replace localhost with the Pi's IP or Tailscale hostname.

---

The UI

Each project gets a card showing:

• Running sessions with their RC URL (tap to open in Claude Code)
• Start a new session (optionally named, optionally in YOLO mode)
• Kill a running session
• Git branch, diff stat, pull button, diff viewer, commit & push flow
• PR review launcher
• Full session history with snapshot viewer and inline rename

The UI is mobile-first with large tap targets — works well on iOS Safari and Android Chrome. No app install needed.

---

Sessions survive restarts

Each session runs claude remote-control --spawn=session inside script, which holds the PTY independently of the pilot server process. This means:

• Restarting or crashing rcpilot does not kill active Claude Code sessions
• Sessions persist across Pi reboots — if the RC process is still running, pilot reconnects to it
• Session log files are written continuously to ~/.config/rcpilot/ and captured as snapshots on end

---

Configuration

Create ~/.config/rcpilot/config.toml (or point PILOT_CONFIG at any path):

# Directory scanned for projects — each immediate subdirectory becomes a project
projects_dir = "~/projects"

# Bind address; keep 0.0.0.0 for VPN / LAN access
host = "0.0.0.0"
port = 8000

# SQLite database path
db_path = "~/.config/rcpilot/pilot.db"

# Usage window scheduler — fires "claude -p hi" on a cron schedule to start
# the 5-hour rolling usage window (Pro/Max plans). Standard 5-field cron syntax.
# Example: fire at 07:00 and 12:00 every day
window_cron = "0 7,12 * * *"

All fields are optional — the defaults above apply when the file is absent.

The scheduler runs embedded in the app (no system cron needed). The next scheduled fire time is shown in the UI header. Supported cron syntax: *, */n, a-b, a,b,c.

---

Raspberry Pi + Tailscale setup

This is the intended deployment: a Pi that's always on, accessible from anywhere over a private VPN.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install rcpilot

uv tool install rcpilot

3. Configure

mkdir -p ~/.config/rcpilot
cat > ~/.config/rcpilot/config.toml <<'EOF'
projects_dir = "~/projects"
host = "0.0.0.0"
port = 8000
EOF

4. Install Tailscale

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Then install Tailscale on your phone or laptop. Access rcpilot at http://<pi-tailscale-hostname>:8000 from anywhere with no port forwarding needed.

iOS Safari works great — the UI is designed for it.

---

Security note

rcpilot has no authentication in v0. It is designed to run on a trusted private network (Tailscale, WireGuard, or local LAN only).

Do not expose port 8000 to the public internet.

Simple token-based auth is planned for Phase 3.

---

Requirements

• Python 3.11+
• script (from util-linux) — standard on all Linux distros, no install needed
• claude — Claude Code CLI, must be on PATH and authenticated
• gh — GitHub CLI, only needed for PR review feature

---

Roadmap

Phase	Status	Focus
0 — Foundation	✅ done	Project discovery, web UI, session spawning
1 — Persistence	✅ done	Session history, snapshots, watchdog, git & PR integration
2 — Context memory	🔜 next	Claude API summarization, resume with injected context
3 — Polish	💡 planned	Auth, PWA, PyPI publish, Docker, CI

See ROADMAP.md for details.

---

Development

uv sync --extra dev
uv run pytest
uv run rcpilot

---

License

MIT