Skip to content

Getting Started

This guide will help you install Multi and set up your first multi-repo workspace.

Prerequisites

  • Python 3.9 or higher
  • Git

Installation

pipx installs Python CLI tools in isolated environments:

pipx install multi-workspace

uv is a fast Python package installer:

uv tool install multi-workspace

pip install multi-workspace

Verify the installation:

multi --version

Creating a Workspace

Step 1: Create a Workspace Directory

Create a new directory that will house all your related repositories:

mkdir my-workspace
cd my-workspace

Step 2: Initialize the Workspace

Run the interactive init command:

multi init

Step 3: Add Repository URLs

When prompted, paste the URLs of the repositories you want to include. You can optionally add descriptions for each repository:

Enter repository URLs (one per line, empty line to finish):
> https://github.com/org/backend
Description (optional): Backend API service
> https://github.com/org/frontend
Description (optional): React frontend application
> https://github.com/org/shared
Description (optional): Shared utilities and types
>

The init command will:

  1. Create a multi.json configuration file
  2. Run multi sync
  3. Clone repositories (standard mode)
  4. Set up the initial .vscode configuration
  5. Create a README.md for your workspace if missing
  6. Optionally create Cursor rules with repository descriptions

Automation Path

For scripts/automation, you can initialize directly from the command line:

multi init \
  --repo https://github.com/org/backend \
  --repo-description "Backend API service" \
  --repo https://github.com/org/frontend \
  --repo-description "React frontend application"

If you want multi init to create the GitHub repositories first, use --github-repo. This shells out to gh repo create, requires gh to be installed and authenticated, and defaults to private repositories:

multi init \
  --github-repo org/backend \
  --github-description "Backend API service" \
  --github-repo org/frontend \
  --github-description "React frontend application"

You can override the defaults with --github-visibility public|private|internal and choose the URL format written to multi.json with --github-clone-protocol https|ssh.

You can still hand-author multi.json and run:

multi sync

multi init automatically uses short local repo names when the remote slug starts with the workspace directory name. Example: in a t-ide/ workspace, https://github.com/org/t-ide-cli becomes local folder cli. If you hand-author multi.json, keep using that same convention.

The same convention applies when you later run multi add.

VS Code Extension

For the best experience, install the Multi Workspace VS Code Extension. The extension automatically runs multi sync when relevant files change, keeping your workspace configuration up to date.

Manual Syncing

If you prefer not to use the extension, you can manually sync your workspace:

multi sync

This command:

  • Ensures all repositories are cloned and up to date
  • Merges .vscode configurations from all sub-repos
  • Generates CLAUDE.md files from Cursor rules

Next Steps