multi-workspace 3.2.7

Multi

multi

multi is a better way to work with VS Code/Cursor on multiple Git repos at once. It is an alternative to multi-root workspaces that offers more flexibility and control. With multi, you can gain control over how tasks, debug runnables, and various IDE and linter settings are combined from multiple project repos ("sub-repos") located within a root workspace folder.

Documentation

Features:

• Generates files in your root .vscode folder from sub-repo launch.json, tasks.json, and settings.json files.
• Supports optional installSets so installer scripts can sync only a public/runtime subset of repos.
• Optionally generates CLAUDE.md and AGENTS.md files from tracked AGENTS.parts/*.md files.
• In monorepo mode, syncs sub-repo GitHub workflows into root .github/workflows.

Installation

Using pipx:

• Install pipx
• Run pipx install multi-workspace

Using uv

• Install uv
• Run uv tool install multi-workspace

Getting started

To get started, create a new workspace directory that will house all your related repos and run:

multi init

When prompted, paste in the URLs of all the repositories you want to have in your workspace. You can optionally specify descriptions of what they do, which can be included in generated agent instruction files when that feature is enabled.

For scripts, you can also initialize non-interactively:

multi init \
  --repo https://github.com/org/backend \
  --repo-description "Backend API" \
  --repo https://github.com/org/frontend \
  --repo-description "Frontend app"

To create GitHub repositories first, add --github-repo entries. This uses gh repo create and defaults to private visibility:

multi init \
  --github-repo org/backend \
  --github-description "Backend API" \
  --github-repo org/frontend \
  --github-description "Frontend app"

For --github-repo, the GitHub CLI (gh) must already be installed and authenticated.

When repository slugs are product-prefixed, multi init automatically writes short local directory names into multi.json when the slug matches the workspace name prefix. For example, in a t-ide/ workspace, t-ide-cli becomes local folder cli.

The same naming rule applies to multi add, so adding https://github.com/org/t-ide-cli inside a t-ide/ workspace will also default to local folder cli.

For public installer workflows, add installSets to repo entries and run a filtered sync:

{
  "repos": [
    { "name": "cli", "url": "https://github.com/org/product-cli", "installSets": ["default", "dev"] },
    { "name": "ios", "url": "[e-mail]:org/product-ios.git", "installSets": ["dev"] }
  ]
}

multi sync --install-set default

Running multi sync without --install-set still includes every repo. Repos without installSets are included in every named set.

To grant or remove GitHub collaborator access across every GitHub repo in a workspace, use:

multi collaborator add octocat --permission maintain --yes
multi collaborator add --yes
multi collaborator accept --yes
multi collaborator remove octocat --yes
multi collaborator recent-users

When the workspace root repository has a GitHub origin, multi collaborator applies the change there too.

The invited collaborator can run multi collaborator accept --yes with their own gh authentication to accept pending invitations for the workspace repos.

Recent collaborator usernames are saved under ~/.multi, and multi collaborator add can prompt from that list when no username is supplied.

If one repo fails, multi collaborator continues through the rest of the workspace and reports the failures at the end.

It is recommended you also install the VS Code Extension that automatically keeps your project synced when edits are made to synced files. To manually sync, you can run multi sync.