grv 0.0.7

Git workspace manager using worktrees

grv

Git workspace manager using worktrees. Clone once, work on many branches simultaneously.

The Problem

With LLM agents reshaping the software engineering workflow, a new pattern is emerging: parallel feature development. Instead of context-switching between branches, developers now spin up multiple workstreams simultaneously—one branch per agent, per experiment, per idea.

Git worktrees are the natural primitive for this workflow. But the standard git worktree flow has friction:

• You need the repo cloned locally first
• You have to decide where to put each worktree
• Worktrees scatter across your filesystem and get lost
• Cleanup is manual and error-prone

Meanwhile, countless tools are appearing daily—each bundling worktree management with CLI agents, dev containers, and other features. But sometimes you just want the primitive.

The Solution

grv is an extremely minimalist worktree manager. Four commands:

grv shell <repo> [branch]  # Shell into a worktree (clones if needed)
grv dir <repo> [branch]    # Print worktree path (for piping)
grv list                    # Browse your worktrees
grv clean                   # Cleanup remotely-backed work

That's it. Use your favorite editor, CLI tools, whatever. But stay organized.

Install

# Run directly (no install needed)
uvx grv [command]

# Or install globally
pip install grv

Usage

# Open a shell in a worktree (clones repo if needed)
grv shell [e-mail]:user/repo.git
grv shell [e-mail]:user/repo.git feature-branch

# Jump straight to a PR
grv shell https://github.com/user/repo/pull/123

# Get worktree path for piping to other tools
grv dir [e-mail]:user/repo.git | xargs code
grv dir https://github.com/user/repo/pull/42 | xargs code

# List all worktrees with status
grv list

# Clean up merged worktrees
grv clean
grv clean --dry-run

How it works

grv manages git worktrees in ~/.grv/:

~/.grv/repos/github_com_user_repo/
├── trunk/              # Base clone (blobless for speed)
└── tree_branches/
    ├── main/           # Worktree for main
    └── feature-branch/ # Worktree for feature-branch

Each branch gets its own directory. Switch between branches by switching directories.

Commands

Command	Description
shell REPO [BRANCH]	Open shell in worktree
dir REPO [BRANCH]	Print worktree path to stdout
list	Show all worktrees with status
clean	Remove safe-to-clean worktrees

REPO can be a git URL or a GitHub PR URL (e.g., https://github.com/user/repo/pull/123). PR URLs require the GitHub CLI (gh) to be installed.

Configuration

Set GRV_ROOT to change the workspace location (default: ~/.grv).

License

MIT