Spawnpoint

Spawn multi-repo worktree workspaces for feature development.

Working on a feature that spans multiple repos? Spawnpoint creates a dedicated folder with git worktrees from each repo on the same branch, installs dependencies, and copies over config files — so you can start coding (or start a Claude session) immediately.

Install

macOS app

Download the latest .dmg from Releases and drag Spawnpoint into Applications. Lives in your menu bar — no terminal required.

Source: mac/.

CLI

pipx install spawnpoint

Or with pip:

pip install spawnpoint

This installs both spawnpoint and sp as CLI commands. All examples below use sp for brevity.

Quick Start

sp create     # select repos, name a branch, spawn worktrees
sp create -y  # auto-select default base branches (skip base branch prompts)
sp list       # view all workspaces
sp add        # add repos to the current workspace
sp cleanup        # select and remove worktree workspaces
sp light-cleanup  # free space by deleting node_modules, .venv, etc. (keeps code)

On first run, Spawnpoint will ask you to configure your scan directories and workspace location.

How It Works

1. Select repos — Spawnpoint scans your code directories and presents a fuzzy-searchable list of git repos
2. Name a branch — Enter a branch name for your feature
3. Spawn — For each repo, Spawnpoint:
   • Creates a git worktree (or new branch if needed)
   • Initializes submodules
   • Copies .env files, CLAUDE.md, and other config files from the original repo
   • Installs dependencies (detects npm/pnpm/yarn/bun, pip/uv/poetry, bundler, go modules)

All worktrees land in a single folder (~/.spawnpoint/workspaces/<branch-name>/) so you can open the whole workspace in your editor or start an AI coding session.

Commands

Command	Description
sp create	Spawn worktree workspaces
sp create -y	Auto-select default base branches
sp list	List all workspaces
sp list --cd	Interactively select a workspace to cd into
sp repos	List repositories available to select
sp add	Add repos to the current workspace
sp cleanup	Remove worktree workspaces
sp light-cleanup	Free space by deleting reinstallable dirs (node_modules, .venv, etc.)
sp init	Run interactive setup
sp config	View current config
sp config --edit	Edit config in $EDITOR
sp config --reset	Reset to defaults
sp update	Update to latest version
sp --version	Show version

Adding repos to a workspace

When you're inside a spawnpoint workspace and need another repo, run:

sp add

Spawnpoint detects the current workspace and branch, shows repos not yet in the workspace, and adds them. If the workspace was originally single-repo, it automatically restructures to multi-repo layout.

Listing workspaces

sp list

Shows a table of all workspaces with repo count, branch, dirty status, and age.

Use sp list --cd (or sp list with shell integration) to interactively pick a workspace and cd into it.

Non-Interactive Mode (for agents & scripts)

Every interactive command can run fully non-interactively with --no-input (-n), so coding agents and scripts can drive Spawnpoint without prompts. In this mode, every selection must be supplied via flags — a missing required flag exits non-zero with a clear error instead of hanging.

Add --json to any command for machine-readable output on stdout (human-readable text stays on stderr).

Discover what's available

sp repos --json    # repos you can pass to --repos
sp list --json     # existing workspaces (names usable as --workspaces / --workspace)

Create a workspace

sp create --no-input --repos api,web --branch feat-x --base main --json

• --repos — comma-separated repo names (match the names from sp repos).
• --branch — branch name (required).
• --base — base branch for branches that don't exist yet. Optional; defaults to each repo's detected default branch. Required only if no default can be detected.

On success it prints the workspace path to stdout (capture with $(...)), or full JSON with --json.

Add repos to the current workspace

Run from inside a workspace:

sp add --no-input --repos api --base main --json

Remove workspaces

sp cleanup --no-input --workspaces feat-x,bug-y --delete-branches --json

• --workspaces — comma-separated workspace names (from sp list).
• --delete-branches / --keep-branches — required; whether to delete the branches from parent repos.

Free space without deleting code (light cleanup)

sp light-cleanup

Scans selected workspaces for reinstallable artifact directories (node_modules, .venv, venv, __pycache__, .next, target, etc.), shows sizes, lets you pick which types to delete, and removes them. Your code is untouched.

Non-interactive:

sp light-cleanup --no-input --workspaces feat-x,bug-y --json
# delete only specific artifact types:
sp light-cleanup --no-input --workspaces feat-x --artifact-types node_modules,.venv --json

• --workspaces — comma-separated workspace names.
• --artifact-types — comma-separated artifact dir names to delete (default: all found).

cd into a workspace

sp list --cd --no-input --workspace feat-x

Prints the workspace path to stdout (and writes the cd-path file used by shell integration).

If no config exists yet, non-interactive commands auto-create one from detected defaults instead of prompting.

Agent skill

A bundled Claude Code / agent skill teaches agents to drive Spawnpoint non-interactively. Install it via skills.sh:

npx skills add mihirgupta0900/spawnpoint

This adds the spawnpoint skill so agents automatically know to use --no-input --json and the correct flags for each command.

Configuration

Config lives at ~/.spawnpoint/config.toml:

# Directories to scan for git repos
scan_dirs = ['~/code', '~/projects']

# Where workspaces are created
worktree_dir = '~/.spawnpoint/workspaces'

# Additional directories to scan during cleanup (for worktrees created at previous locations)
additional_worktree_dirs = []

# How deep to scan for repos (1-4)
scan_depth = 2

# Files/dirs to copy into new worktrees
copy_patterns_globs = ['.env*']
copy_patterns_files = ['AGENT.md', 'CLAUDE.md', 'GEMINI.md']
copy_patterns_dirs = ['.vscode', 'docs']

# Auto-install dependencies after worktree creation
auto_install_deps = true

# Check for new versions on startup
check_updates = true

Additional worktree dirs

If you change worktree_dir, workspaces created at the old location won't be found during cleanup. Add the old path to additional_worktree_dirs so cleanup and list can still find them:

worktree_dir = '~/new-location/workspaces'
additional_worktree_dirs = ['~/.spawnpoint/workspaces']

When creating a new branch, Spawnpoint automatically detects the repo's default branch to use as the base. No configuration needed.

Shell Integration

During sp init, you'll be offered to install a shell function that wraps common commands with auto-cd:

sp() {
    local cmd="${1:-create}"
    shift 2>/dev/null
    local cd_file="$HOME/.spawnpoint/.cd_path"
    rm -f "$cd_file"
    case "$cmd" in
        create)     spawnpoint create "$@" ;;
        list|ls)    spawnpoint list --cd "$@" ;;
        *)          spawnpoint "$cmd" "$@" ;;
    esac
    if [ -f "$cd_file" ]; then
        local dir=$(cat "$cd_file")
        rm -f "$cd_file"
        [ -n "$dir" ] && cd "$dir"
    fi
}

With shell integration:

• sp — create a workspace and cd into it
• sp list or sp ls — pick a workspace and cd into it
• sp cleanup, sp add, etc. — passed through to spawnpoint

Without shell integration, sp still works for all commands — you just won't get auto-cd for create/list.

Requirements

• Python 3.10+
• git

Uninstall

pipx uninstall spawnpoint
rm -rf ~/.spawnpoint

License

MIT