Skip to main content
wspace (published as @wazoo/workspace) is a Git-native CLI that manages multi-repository Wazoo workspaces without Git submodules. It consolidates workspace conventions into a manifest (repos.json) and standardizes feature development with Git worktrees.

​
Overview

Complex applications and agent infrastructure often span multiple independent Git repositories. wspace treats repository families as a synchronized ecosystem without submodules:
  • Submodules: Preserves independent Git history, remotes, package managers, and release surfaces for every repository.
  • Git worktree isolation: Isolates feature development into linked worktrees (worktrees/<repo>/<feature>), preventing dirty state in base checkouts.
  • Conservative operations: Mutating commands (update, worktree, env sync) refuse to rewrite user history, touch dirty repositories, or alter unmanaged checkouts.
  • Project agnostic: Configured via JSON manifest files (repos.json or custom --manifest <path>).

​
Repositories and packages

​
Installation

Install the wspace binary using Deno:

​
Command reference

​
wspace check

Performs a read-only health check across all manifest-managed repositories and linked feature worktrees.
  • Reports status for each repository: CLEAN, DIRTY, FEATURE_CLEAN, DIVERGED, UNKNOWN, MISSING, INVALID, PATH_BLOCKED, or ERROR.
  • Inspects linked feature worktrees and flags uncommitted work as WORKTREE_DIRTY.
  • Filters directory scans to exclude managed repositories from unmanaged output.
  • Exits 0 when clean and 1 when any repository or worktree requires attention.

​
wspace init / wspace sync

Clones missing repositories specified in the manifest into the workspace.
  • Exits non-zero (1) if any remote clone fails or collides with a non-Git path (PATH_BLOCKED).
  • Does not reset, overwrite, or clean up existing checkouts.

​
wspace update

Fetches remotes and fast-forwards clean default branches.
  • Skips repositories checked out on feature branches (SKIP_FEATURE) or containing uncommitted changes (SKIP_DIRTY).
  • Fast-forwards only clean default branches tracking remote branches without divergence.

​
wspace worktree add

Creates a linked Git worktree under worktrees/<repo>/<feature> on branch <feature>.
  • Start point defaults to origin/<default> (resolved via origin/HEAD).
  • Validates repository and feature names against path traversal (..).
  • Attaches existing local branches when present.

​
wspace worktree list

Lists active worktrees across all manifest repositories.
  • With --stale, filters to worktrees whose branch is fully merged into the default branch (or missing).

​
wspace worktree remove

Removes a feature worktree and prunes stale Git references.

​
wspace env sync

Synchronizes local environment files (.env, .env.*, .dev.vars) from a secrets/ vault into checkouts and linked worktrees.
  • With --dry-run, previews file creation and overwrites without modifying files.
  • Applies owner-only permissions (0600) on copied files.
  • Rejects destination symlinks.

​
wspace validate

Validates the manifest schema without touching the filesystem or invoking Git.

​
Beginner worktree lifecycle

Execute all commands from the workspace root (the directory containing repos.json):
  1. Check status: wspace check
  2. Refresh baselines: wspace update
  3. Create worktree:
    Or use wspace: wspace worktree add <repo> <feature>
  4. Develop:
  5. Sync local secrets: wspace env sync --dry-run then wspace env sync
  6. Push and create pull request:
  7. Find merged worktrees: wspace worktree list --stale
  8. Clean up: wspace worktree remove <repo> <feature>

​
Path resolution and worktree location

  • Workspace root anchor: Relative repository and worktree paths resolve relative to the directory containing workspace.json (or wspace.json / repos.json), regardless of caller directory.
  • Why $PWD is used with git -C: git -C repos/<repo> changes Git’s working directory to repos/<repo> before executing. Passing a relative path like worktrees/<repo>/<feature> would nest the worktree inside repos/<repo>/worktrees/. Using "$PWD/worktrees/<repo>/<feature>" resolves $PWD from the workspace root before Git runs.
  • Automatic path resolution with wspace: Running wspace worktree add <repo> <feature> resolves absolute paths under worktrees/<repo>/<feature> automatically.

​
Worktree dependency management

Each Git worktree maintains an independent working directory, while package managers optimize dependency caching across worktrees:
  • pnpm: Uses a central content-addressable store (~/.local/share/pnpm/store). Running pnpm install in a new worktree hard-links dependencies from the central store without duplicating files or re-downloading packages.
  • Deno: Uses the global DENO_DIR module cache (~/.cache/deno or %LOCALAPPDATA%\deno), sharing cached dependencies across all worktrees zero-copy.
  • npm / yarn: Running npm install or yarn install inside a worktree installs dependencies for that worktree, fetching packages from the shared user HTTP cache.

​
Manifest schema

Path resolution anchors all relative directories (workspaceRoot, repositoriesDirectory, worktreesDirectory, vaultDirectory) to the folder containing the manifest file.