luv

A CLI that launches Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments.

luv clones a repo, creates a branch, and drops you into a Claude session ready to work. When the repo ships a .luv/settings.json, it spins up Docker Compose automatically so every command runs in the right environment. Point it at a remote machine and the whole thing runs there in a tmux session you can detach from and reattach to later.

Install

# With uv (recommended)
uv tool install luv-cli

# With pip
pip install luv-cli

Requirements: GitHub CLI (gh) plus either Claude Code or Codex must be installed and authenticated.

Quick start

# One-time setup: default GitHub org, and optionally a remote machine
luv config

# Create a new workspace and launch Claude
luv my-repo "add user authentication"

# Launch Codex in YOLO mode instead
luv --codex my-repo "add user authentication"

# Select Claude explicitly (Claude remains the default)
luv --claude my-repo "add user authentication"

# Base a new workspace off a non-default branch
luv my-repo -b develop "add user authentication"

# Use a different org inline
luv other-org/my-repo "fix the bug"

# Reopen workspace #42
luv my-repo 42

# Open any GitHub PR by URL
luv -l https://github.com/org/repo/pull/123

# Open a shell instead of Claude
luv -n my-repo 42

# Resume last Claude session
luv -r my-repo 42

# Clean up fully-merged workspaces
luv --clean

# See what's running on your remote machine, and reattach
luv ls
luv continue

How it works

Clones the repo into ~/prs/{repo}-{machine}-{number}/
Creates a new branch luv-{machine}-{number}
Configures the selected agent with the workspace's PR conventions
Launches Claude with Opus 5 at max effort, or Codex in YOLO mode

All workspaces live under ~/prs/. The number comes from the repo's GitHub issue counter, and {machine} is a short name for the machine that created the workspace — by default the hostname, or whatever you set with luv config set machine mbp.

The machine name is what keeps two computers apart. Each one works out the next number from GitHub independently, so your laptop and your box will happily pick the same one; without the slug they would both push a branch called luv-43. Folders and branches created before this keep working unchanged.

With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see Remote sessions.

Commands

Command	Description
`luv config`	Interactive setup: remote host, SSH key, default org
`luv config set\|get\|unset <key> [value]`	Read or write a single setting
`luv config list`	Show all settings
`luv --init`	Configure default GitHub org only
`luv ls [--host H] [--prune]`	List live sessions across hosts
`luv continue [<repo> [number]]`	Attach to a live session
`luv handover [<repo> [n]] --to HOST`	Move a session to another machine and resume it there
`luv [org/]<repo> [prompt...]`	Create a new workspace and launch Claude (default)
`luv --codex [org/]<repo> [prompt...]`	Create a workspace and launch Codex in YOLO mode
`luv [org/]<repo> -b <branch> [prompt...]`	Create a workspace based off `<branch>` instead of the default
`luv [org/]<repo> <number> [prompt]`	Reopen an existing workspace
`luv -l <PR URL> [prompt]`	Open any GitHub PR by URL
`luv [org/]<repo> -pr <number> [prompt]`	Open a PR by repo + number
`luv --clean`	Delete workspaces where the branch is fully pushed/merged
`luv --clean -f`	Force delete all workspaces
`luv --clean --safe -f`	Force delete only workspaces older than 24h

Flags

Flag	Description
`--claude`	Launch Claude Code (default)
`--codex`	Launch Codex with approvals and sandboxing bypassed (YOLO mode)
`-n`	Navigate: open a shell instead of Claude
`-r`	Resume: resume the selected agent's last session
`-p`	Launch Claude in plan permission mode (default: `bypassPermissions`)
`-nit`	Non-interactive: run the selected agent and exit (no REPL); Claude streams `stream-json` events to stdout
`-m MODEL`	Model to use; Claude defaults to `claude-opus-5`, while Codex uses its configured CLI default
`-b BRANCH`	Base a new workspace off `BRANCH` (clone + branch from it); recorded in `git config luv.base` so the PR can target it
`-e`	Env: pass `LUV_*` environment variables (with prefix stripped) into the session
`-s HOST`	Run on `HOST` over SSH, overriding the configured remote host
`-i PATH`	SSH identity file to use for this invocation
`--local`	Force local execution even when a remote host is configured
`-f`, `--force`	Skip safety checks (with `--clean`); replace an existing destination folder (with `handover`)
`--safe`	With `--clean -f`, only delete workspaces older than 24h (mtime)

Handover flags:

Flag	Description
`--to HOST`	Destination machine; `local` for the one you're on
`--from HOST`	Source machine, when luv can't tell from its session registry
`--no-agent-state`	Move the workspace only; the agent starts a new conversation
`--no-attach`	Leave the destination session running detached
`--purge`	Delete the source folder once the copy is verified
`-y`	Skip the "an agent may still be running" confirmation

Docker dev environments

If a repo contains .luv/settings.json with a compose_file key, luv automatically starts a Docker Compose environment and runs Claude inside the dev-environment container.

Setup

1. Create .luv/settings.json in your repo:

{
  "compose_file": ".luv/docker-compose.yml"
}

The compose_file path is relative to the repo root.

2. Create the Docker Compose file:

services:
  dev-environment:
    image: your-org/dev-env:latest
    volumes:
      - .:/workspace
    working_dir: /workspace
    stdin_open: true
    tty: true
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev

The dev-environment service must have the selected agent CLI (claude or codex) installed in its image.

How Docker mode works

Detects .luv/settings.json with compose_file key
Tears down any stale environment from a previous run
Starts docker compose up -d --build with a unique project name (luv-{repo}-{machine}-{number}) for network/volume isolation
Verifies the dev-environment service is running
Runs the selected agent inside the container via docker compose exec
The repo is volume-mounted, so all file changes and git commits are visible on the host
On exit (including Ctrl-C), tears down the environment with docker compose down -v

Docker mode works with all flags: -n opens a bash shell in the container, -r resumes a Claude session in the container.

Remote sessions

Point luv at another machine and every workspace command runs there, inside a tmux session that survives disconnects.

luv config                          # set the remote host, SSH key, and org
luv myrepo "fix the flaky test"     # clones and launches Claude on the remote
                                    # ...close the laptop, go home...
luv ls                              # see what's still running
luv continue                        # reattach exactly where you left off

luv re-invokes itself on the remote over SSH, so every flag works there unchanged. The remote needs luv, tmux, gh, and git on its PATH.

Use --local for a one-off local run, -s HOST to target a different machine, and -i PATH for a different SSH key.

Handing a session to another machine

Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:

luv --local myrepo "start something"   # working locally
luv handover myrepo 43 --to box        # resumes mid-conversation on box
luv handover myrepo 43 --to local      # ...and back again later

The whole folder crosses over, including untracked and gitignored files, so a workspace that ran before the move still runs after it. The agent's transcript moves too, so it picks up where it left off rather than starting fresh. Bytes are relayed through the machine you run the command on, so the two ends never need SSH access to each other.

The source folder is left on disk (--purge deletes it), and the workspace keeps the name it was created with.

Full guide, including how to prepare a fresh Ubuntu box and set up SSH keys: docs/remote-sessions.md.

Workspace cleanup

luv --clean scans ~/prs/ and safely removes workspaces that are fully pushed. It checks:

Working tree is clean (no uncommitted changes)
No unpushed commits
If the remote branch is gone, verifies the PR was merged and local HEAD matches

Use luv --clean -f to skip all safety checks and delete everything. Add --safe (i.e. luv --clean --safe -f) to restrict force-delete to workspaces whose folder mtime is older than 24 hours, leaving recently-touched workspaces alone.

Workspaces with a live tmux session are skipped unless you pass -f.

Configuration

Run luv config for interactive setup, or luv --init to set just your default GitHub org. Both save to ~/.luv/config.json:

{
  "org": "exosphere",
  "prs_dir": "~/prs",
  "remote": {
    "host": "box",
    "identity_file": "~/.ssh/id_ed25519",
    "dir": "~/prs"
  }
}

You can also pass org/repo inline to override the default for any command (e.g., luv other-org/my-repo).

Every key, with defaults and resolution order: docs/configuration.md. The session registry that backs luv ls: docs/sessions.md.

License

MIT

Navigation Menu

Repository navigation

README.md

README.md

luv

Install

Quick start

How it works

Commands

Flags

Docker dev environments

Setup

How Docker mode works

Remote sessions

Handing a session to another machine

Workspace cleanup

Configuration

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

luv

Install

Quick start

How it works

Commands

Flags

Docker dev environments

Setup

How Docker mode works

Remote sessions

Handing a session to another machine

Workspace cleanup

Configuration

License