claude-code-fleet

Run, monitor and secure parallel Claude Code agents across a Mac, a cloud VM and an iPhone over Tailscale. Bash + launchd/systemd tooling, ADR-driven, tested with bats.

Parallel Claude Code agents on two machines, steered from a third:

• MacBook (macbook) and cloud (core-vm-cloud, Tailscale name cloud) each run Agent View in tmux and one Remote Control server per allowlisted repo.
• iPhone reaches both via mosh (Moshi) over Tailscale, or the Claude app (Remote Control). ntfy pushes arrive only when you're away from the Mac.
• Cloud sounds play on the Mac (Choo Choo) through a relay the Mac opens; cloud can never connect to the Mac.

Architecture

flowchart LR
  iPhone -- "mosh / Claude app" --> Mac
  iPhone -- "mosh over Tailscale" --> Cloud
  Mac -- "ssh, rsync, settings sync" --> Cloud
  Cloud -. "ntfy push (away only)" .-> iPhone
  Cloud -. "sound relay opened by Mac" .-> Mac

Loading

Stack: Bash, bats, shellcheck, Make, tmux, Tailscale (ACL policy with tests), systemd, launchd, jq.

Where to start

I want to…	Read
Understand the design	docs/architecture.md, docs/spec.md, ADRs
See what is built and what is next	Roadmap, phase logs
Build everything from nothing	docs/runbooks/00-bootstrap-from-zero.md
Rebuild one device	mac-rebuild · cloud-rebuild · iphone-setup
Tailnet policy, cloud node, Mac rename	tailscale
Add / remove a repo	add-repo · remove-repo
Change Claude Code settings	sync-settings
Check it all works	verify · troubleshooting
Change this repo (agents)	CLAUDE.md

Status: built in phases, see prompts/plan.md and docs/progress/. Runbooks mark steps whose scripts do not exist yet with the phase that delivers them.

Commands

make help          # every target
make lint test     # shellcheck + bats (brew install shellcheck bats-core)

Infrastructure (VM, disk, Tailscale package, Vault) lives in the separate oci-free-tier-platform repo (~/code/oci-free-tier-platform).

Getting started

make lint test                 # shellcheck + bats
./install.sh mac               # idempotent; backs up ~/.claude/settings.json first
./install.sh cloud             # rsync + units over ssh (needs a reachable host named `cloud`)
make doctor                    # health check

Layout

bin/       agent and fleet scripts      config/   sanitized Claude, tmux, Tailscale config
hooks/     Claude Code hooks            docs/     architecture, ADRs, runbooks, phase logs
tests/     bats suites + fakes          install.sh  idempotent installer (mac | cloud)

Design decisions

0001 Tailscale on OCI · 0002 ownership split · 0003 repo allowlist · 0004 ntfy public topic · 0005 capture/apply settings · 0006 global profile and memory in git

License

MIT