
workspaces
Manage isolated git worktree workspaces for multi-repo development
- version
- 1.0.1
- GitHub stars
- 123
Install
/plugin install workspaces@ai-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceCommands 2
Name
workspaces:create
Synopsis
/workspaces:create <short-description> <repo1|url> [repo2...]
Description
The workspaces:create command creates a dedicated workspace directory with git worktrees for multi-repository development. It intelligently parses the workspace description to identify repositories, PR URLs, and JIRA keys, then sets up isolated git worktrees on a new feature branch or checks out a PR for review.
This command streamlines working on tasks that span multiple repositories by keeping all related code changes synchronized in a single workspace.
Implementation
Workflow
- [ ] Step 1: Gather info and check configuration
- [ ] Step 2: Parse workspace description
- [ ] Step 3: Ask user to confirm
- [ ] Step 4: Validate and execute
Step 1: Gather info and check configuration
Run the gather script (which includes preflight check):
${CLAUDE_PLUGIN_ROOT}/commands/create/gather.sh
If the output contains STATUS: NOT_CONFIGURED:
-
Use AskUserQuestion to ask the user for:
- Git repositories root: Full path to where git repos are cloned (e.g.,
/home/user/git-reposor~/work/repos) - Workspaces root: Full path to where workspaces will be created (e.g.,
/home/user/workspacesor~/dev/workspaces)
- Git repositories root: Full path to where git repos are cloned (e.g.,
-
Run gather again with the user's paths:
${CLAUDE_PLUGIN_ROOT}/commands/create/gather.sh --repos-root <REPOS_PATH> --workspaces-root <WORKSPACES_PATH> -
Verify the output shows
CONFIGURATION SAVEDbefore proceeding to Step 2
If TEMPLATE is MISSING: Abort with error.
Step 2: Parse workspace description
Read configured paths: From Step 1 output, note the === CONFIG === section values:
REPOS_ROOT— use this path when doing any direct git operations on repos (e.g.,git worktree add)WORKSPACES_ROOT— use this path when referencing workspace locations
Check for custom rules: From Step 1 output, check if === CUSTOM_PROMPT === section is present:
- If present: Apply the aliases and auto-detect rules defined in that section
- If not present: Use generic parsing without aliases or auto-detect
Extract from workspace description:
- GitHub PR URLs:
github.com/{org}/{repo}/pull/{number} - Jira keys: Pattern
[A-Z]+-[0-9]+(e.g., TEAM-1234, PROJECT-567) - Repository names: Match against repos listed in Step 1 REPOS section
Apply custom rules (if custom-prompt.md was found):
- Expand any aliases defined in the file
- Apply auto-detect rules to add dependent repositories
Workspace directory name priority:
- Jira key (if found in description)
review-{repo}-{pr}(if PR URL found)feature-{summary}(derive from description)
Step 3: Ask user to confirm
Use AskUserQuestion for:
- Repositories: 1-3 specific combinations
- Workspace name: 1-3 actual suggestions
If user picks "Other" for repositories: Ask a second confirmation to verify their custom repo list before proceeding.
Step 4: Execute workspace creation
Use the workspace NAME (not full path).
For feature workspaces:
${CLAUDE_PLUGIN_ROOT}/commands/create/execute.sh {WORKSPACE_NAME} {BRANCH} feature {REPO1} {REPO2} ...
For PR review workspaces:
${CLAUDE_PLUGIN_ROOT}/commands/create/execute.sh {WORKSPACE_NAME} {BRANCH} review:{PR_NUM} {REPO1} {REPO2} ...
Example: Use feature-azure-template-field (not /home/user/workspaces/feature-azure-template-field).
The script will create the workspace with worktrees for each repository. If any issues are found, the script will abort with an error message.
Report the workspace location and worktrees created to the user.
Name
workspaces:delete
Synopsis
/workspaces:delete <workspace-name>
Description
The workspaces:delete command removes a workspace directory and its associated git worktrees. Before deletion, it checks the status of all repositories in the workspace to detect uncommitted changes or unpushed commits, prompting the user for confirmation when issues are found.
This command helps clean up task workspaces created by /workspaces:create while ensuring no work is accidentally lost.
Implementation
Workflow
- [ ] Step 1: Identify workspace and check configuration
- [ ] Step 2: Execute deletion
Step 1: Identify workspace and check configuration
Get available workspaces (includes configuration check):
${CLAUDE_PLUGIN_ROOT}/commands/delete/list.sh
If the output contains STATUS: NOT_CONFIGURED:
-
Use AskUserQuestion to ask the user for:
- Git repositories root: Full path to where git repos are cloned (e.g.,
/home/user/git-reposor~/work/repos) - Workspaces root: Full path to where workspaces will be created (e.g.,
/home/user/workspacesor~/dev/workspaces)
- Git repositories root: Full path to where git repos are cloned (e.g.,
-
Run list again with the user's paths:
${CLAUDE_PLUGIN_ROOT}/commands/delete/list.sh --repos-root <REPOS_PATH> --workspaces-root <WORKSPACES_PATH> -
Verify the output shows
CONFIGURATION SAVEDbefore proceeding to Step 2
Read configured paths: From the output, note the === CONFIG === section values:
REPOS_ROOT— use this path when doing any direct git operations on reposWORKSPACES_ROOT— use this path when referencing workspace locations
Match user's input against the workspace list:
- Exact match found: Proceed to Step 2
- Partial matches found: Use AskUserQuestion to let user select from matches
- No matches: Use AskUserQuestion to let user select from all workspaces or cancel
Step 2: Execute deletion
Use the workspace NAME (not full path) from Step 1.
Example: If the workspace is at /home/user/workspaces/feature-azure-template-field, use feature-azure-template-field (not the full path).
Step 2.1: Attempt deletion
Execute the deletion script:
${CLAUDE_PLUGIN_ROOT}/commands/delete/execute.sh {WORKSPACE_NAME}
The script will:
- Check status of all repositories in the workspace
- Display the status to the user
- Proceed automatically if workspace is clean
- Request user input if there are uncommitted changes or unpushed commits
Step 2.2: Handle the result
Case A: Exit code 0 (success)
The workspace was clean and has been deleted successfully. Report completion to user.
Case B: Exit code 2 (user input required)
The workspace has uncommitted changes or unpushed commits. The status has already been displayed to the user.
Use AskUserQuestion with these options:
- "Keep branches (Recommended)" - Description: "Delete workspace but keep git branches. You can still access unpushed commits from the main repository."
- "Delete branches" - Description: "Delete workspace AND branches. Warning: uncommitted changes and unpushed commits will be lost."
- "Abort" - Description: "Cancel the deletion operation."
Then execute based on user's choice:
If user chose "Keep branches":
${CLAUDE_PLUGIN_ROOT}/commands/delete/execute.sh {WORKSPACE_NAME} --keep-branches
If user chose "Delete branches":
${CLAUDE_PLUGIN_ROOT}/commands/delete/execute.sh {WORKSPACE_NAME} --delete-branches
If user chose "Abort":
- Do not execute deletion
- Inform user: "Deletion cancelled. Workspace remains intact."
Case C: Exit code 1 (error)
An error occurred (e.g., workspace not found, configuration issue). Report the error to the user.
Sponsors
Details
- Marketplace
- openshift-eng/ai-helpers
- Source
- plugins/workspaces
- Category
- Development
- Keywords
- git, worktree, workspace, multi-repo
More from openshift-eng/ai-helpers
All 56- yamlv0.0.2
- agendasv0.0.3
- agentic-docsv2.2.12
- ai-sbomv0.0.1
- bigqueryv0.0.2
- bigquery-ci-datav0.0.3
- bigquery-cost-analysisv0.0.7
- civ0.0.111
- ci-extrasv0.3.0
- code-reviewv0.0.18
- compliancev0.4.1
- consolev0.1.0
- container-imagev0.0.2
- docv0.0.2
- etcdv0.0.2
- gitv0.0.7
- githubv0.3.0
- golangv0.7.0
- gopls-lspv1.0.0
- gwapiv0.0.1
- hcpv0.0.3
- hello-worldv1.0.3
- jirav0.9.8
- lvmsv0.1.1