cc-remote

Launch Claude Code sessions on a remote VM from your local Mac directory context.

What it does

From any local project directory:

1. Maps your local path to the corresponding VM path
2. Creates an isolated git worktree on the VM (using wt helper)
3. Starts a tmux session with Claude Code
4. Sends your prompt to Claude

This lets you fire off remote Claude tasks from your phone or laptop without manually SSH'ing, navigating, and setting up worktrees.

Install

ln -s ~/dev/cc-remote/cc-remote /usr/local/bin/cc-remote

Usage

# From any ~/dev project directory:
cc-remote "fix the auth bug in the login flow"

# With custom session name:
cc-remote -n auth-fix "fix the auth bug"

# Auto-attach after launching:
cc-remote --attach "add dark mode"

# List active sessions:
cc-remote -l

# Kill a session:
cc-remote -k swift-wolf

Options

Option	Description
-n, --name NAME	Custom session name (default: random)
-a, --attach	Attach to session after launching
-l, --list	List active cc-remote sessions
-k, --kill NAME	Kill a session by name
-h, --help	Show help

Path Mapping

By default: ~/dev/X → /opt/services/X

Examples:

• ~/dev/plumbgpt → /opt/services/plumbgpt
• ~/dev/lumifyhub/lumifyhub-web → /opt/services/lumifyhub/lumifyhub-web

Special overrides can be added in PATH_OVERRIDES array for edge cases.

Worktrees

Each session gets its own git worktree at ~/dev/worktrees/<repo>--<session> on the VM, using the wt helper from ~/worktree.sh. This allows:

• Parallel isolated work without branch conflicts
• Auto-copy of .env, .env.local, etc. from main repo
• Clean separation between concurrent Claude sessions

If worktree creation fails (not a git repo, etc.), falls back to using the main repo directory.

Session Names

If no name is provided, a random name is generated using adjective-noun pairs:

• swift-wolf, calm-storm, bright-hawk, etc.

Checking on Sessions

# List all cc-remote sessions
cc-remote -l

# Attach to a session
ssh root@100.75.20.59 -t 'tmux attach -t swift-wolf'

# View session output without attaching
ssh root@100.75.20.59 "tmux capture-pane -t swift-wolf -p | tail -30"

VM Requirements

The VM needs:

• ~/worktree.sh sourced in ~/.zshrc (provides wt command)
• tmux installed
• Claude Code installed (claude command)

Related

• ~/dev/dev-settings/worktree.sh - Backup of VM's worktree helpers
• ~/dev/homelab/README.md - Homelab documentation