workspaces

Shell utilities for creating workspaces (git worktrees) with optional Python virtual environments using uv.

Overview

Create isolated workspaces for parallel development. Each workspace gets its own branch. Python projects (detected via pyproject.toml) automatically get an activated virtual environment. Uses uv sync for fast, reproducible environment setup.

Requirements

• bash or zsh
• git
• uv - install with brew install uv
• pyproject.toml in Python projects (no requirements.txt support)

Installation

mkdir -p ~/.local/bin
cp venv-functions.sh workspace-functions.sh ~/.local/bin/
chmod +x ~/.local/bin/venv-functions.sh

Add to ~/.zshrc or ~/.bashrc:

source ~/.local/bin/workspace-functions.sh

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

Usage

Create a workspace

From any git repository:

workspace              # From HEAD
workspace main         # From main branch
workspace main --python      # Force Python venv setup
workspace main --python-version 3.12  # Specify Python version

This creates:

• Workspace at ~/.workspaces/<repo>/<name>
• Branch with the same name (Docker-style random name like eager-turing)
• Activated virtual environment (if Python project detected or --python flag used)

Python environment detection

A Python venv is automatically created when:

• --python or --py flag is passed, OR
• pyproject.toml exists in the project root

Set up venv in current directory

venv-setup            # Python 3.14
venv-setup 3.12       # Specify version

List workspaces

workspace list

Remove a workspace

workspace remove <name>

Removes the workspace directory and deletes the branch.

Show help

workspace help

Configuration

Workspace location

Workspaces are stored at ~/.workspaces/<repo>/<name>.

Python version

Default Python version is 3.14. Override per-command with --python-version or modify DEFAULT_PYTHON_VERSION in venv-functions.sh.

Virtual environment setup

venv-functions.sh uses uv sync and automatically:

• Creates .venv directory with all dependencies
• Creates/updates uv.lock for reproducible builds
• Pins Python version in .python-version file
• Installs dev dependencies from [dependency-groups]
• Offers to install missing Python versions via uv python install
• Adds .venv to .gitignore if missing
• Creates .vscode/settings.json for Python interpreter

Lockfile (uv.lock)

When setting up a Python environment, uv.lock is automatically created. This file:

• Ensures reproducible builds across machines and workspaces
• Should be committed to git
• Is automatically kept in sync by uv sync

Using with Claude Code

Claude Code works seamlessly with uv-managed projects. Use uv run to execute commands without activating the virtual environment:

uv run python script.py       # Run Python scripts
uv run pytest                  # Run tests
uv run ruff check .            # Run linters

This is the recommended approach for tooling and CI/CD pipelines.

Standalone venv setup

Run venv-functions.sh directly in any directory with pyproject.toml:

~/.local/bin/venv-functions.sh                        # Python 3.14
~/.local/bin/venv-functions.sh --python-version 3.12  # Specify version
~/.local/bin/venv-functions.sh --non-interactive      # Auto-install Python if needed
~/.local/bin/venv-functions.sh --force-non-git        # Skip git check

Non-interactive mode

Use --non-interactive when calling from scripts or automation:

• Syncs project dependencies (idempotent)
• Auto-installs missing Python version
• Creates/updates uv.lock

License

MIT