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)

sp template save image-gen   # remember a set of repos you spawn together
sp create -t image-gen       # spawn that set again

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 create -t <name>	Spawn from a saved template
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 template list	List saved templates
sp template save <name>	Create or update a template
sp template show <name>	Show one template
sp template delete <name>	Delete a template
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.

Templates

If the same repos keep coming up together — an image generation stack, a billing surface — save them once as a template and spawn them by name:

sp template save image-gen                      # pick repos interactively
sp template save image-gen --repos chottu,backend,daily-prophet --base staging

Then use it:

sp create -t image-gen        # or --template image-gen

A template stores the repo set, plus an optional base branch and description. sp create uses it as a starting point: the repo picker opens with those repos already selected, so you can still add or drop one for this workspace only. With --no-input the template's repos are used as-is.

Picking a template in sp create

Run sp create with no flags and saved templates are offered first, ahead of the repo picker:

? Start from a template?
❯ Pick repos manually
  billing  (backend, dashboard)
  image-gen  (Image generation stack)

"Pick repos manually" is the default and comes first, so pressing Enter gives you exactly the old behaviour — and the prompt doesn't appear at all until you save your first template. Templates are listed by name with their description, or their repos if they have none.

Pick one and the repo picker opens with those repos already toggled on:

? Select repositories (type to search):
❯   4/4 (3)  Selected: backend, chottu, daily-prophet
❯❯backend
 ❯chottu
 ❯daily-prophet
  dashboard

So a template is two keystrokes (arrow, Enter) and then Enter again to accept the set, or a few TABs to adjust it for this one workspace. Skip the prompt entirely with sp create -t image-gen.

Saving a template

After you confirm the plan, sp create offers to remember the set:

? Save these 3 repos as a template for next time? (y/N)
? Template name: image-gen

The default is No, and the offer is skipped when you picked a single repo or when the set still matches the template you started from. To name it up front instead:

sp create --save-template image-gen

That also works on an existing template, so sp create -t image-gen --save-template image-gen spawns the set and folds in whatever you tweaked in the picker.

Templates live in ~/.spawnpoint/templates.toml and are safe to edit or commit as a dotfile:

[templates."image-gen"]
description = "Image generation stack"
repos = ["chottu", "backend", "daily-prophet"]
base = "staging"

Repo names must match the names from sp repos. Deleting a template never touches workspaces you already spawned.

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)
sp template list --json   # templates you can pass to --template

Create a workspace

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

• --repos — comma-separated repo names (match the names from sp repos). Required unless --template is given.
• --template / -t — take the repo set from a saved template. An explicit --repos overrides it.
• --branch — branch name (required).
• --base — base branch for branches that don't exist yet. Optional; defaults to the template's base, then 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.

Manage templates

sp template save image-gen --no-input --repos api,web --base main --json
sp template show image-gen --json
sp template delete image-gen --no-input --json

• template save requires --repos in --no-input; --base and --description are optional and keep their saved values when omitted.
• A template naming a repo that no longer exists is an error in --no-input; interactively it is a warning and the remaining repos are pre-selected.

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

Templates are stored separately in ~/.spawnpoint/templates.toml, so sp init and sp config --reset leave them alone. See Templates.

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