Skip to main content

Workspaces

Workspace commands create and manage multi-repo workspaces.

Commands​

x4 workspace bootstrap
x4 workspace status
x4 workspace test
x4 workspace commit
x4 workspace cleanup

Top-level aliases also exist:

x4 bootstrap
x4 status
x4 test
x4 cleanup

Bootstrap Flow​

After bootstrap, x4 status shows the active workspace id, repo set, registry path, sandbox profile, branch, and each attached repo path. The same registry path is recorded in .x4/workspace.yaml as registryPath and in the generated .x4/x4-workspace.code-workspace settings as x4.registryPath.

Commit Behavior​

x4 workspace commit commits each dirty workspace repo independently with the same message. It is useful when a feature spans multiple repos but should still produce repo-local commits.

x4 workspace commit -m "Implement shared feature"

Options:

  • --dry-run: print the commit plan.
  • --allow-empty: create empty commits in clean repos.
  • --allow-session-branch: allow committing on temporary session branches.

Cleanup Behavior​

x4 workspace cleanup removes generated worktrees and branches. It refuses dirty attached repos unless --force is provided.

x4 workspace cleanup --dry-run
x4 workspace cleanup --force --prune-artifacts