Manage isolated git worktree workspaces for multi-repo development

version
1.0.1
GitHub stars
123

Install

/plugin install workspaces@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Commands 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:

  1. Use AskUserQuestion to ask the user for:

    • Git repositories root: Full path to where git repos are cloned (e.g., /home/user/git-repos or ~/work/repos)
    • Workspaces root: Full path to where workspaces will be created (e.g., /home/user/workspaces or ~/dev/workspaces)
  2. Run gather again with the user's paths:

    ${CLAUDE_PLUGIN_ROOT}/commands/create/gather.sh --repos-root <REPOS_PATH> --workspaces-root <WORKSPACES_PATH>
    
  3. Verify the output shows CONFIGURATION SAVED before 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:

  1. Jira key (if found in description)
  2. review-{repo}-{pr} (if PR URL found)
  3. 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:

  1. Use AskUserQuestion to ask the user for:

    • Git repositories root: Full path to where git repos are cloned (e.g., /home/user/git-repos or ~/work/repos)
    • Workspaces root: Full path to where workspaces will be created (e.g., /home/user/workspaces or ~/dev/workspaces)
  2. Run list again with the user's paths:

    ${CLAUDE_PLUGIN_ROOT}/commands/delete/list.sh --repos-root <REPOS_PATH> --workspaces-root <WORKSPACES_PATH>
    
  3. Verify the output shows CONFIGURATION SAVED before 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 repos
  • WORKSPACES_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:

  1. Check status of all repositories in the workspace
  2. Display the status to the user
  3. Proceed automatically if workspace is clean
  4. 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:

  1. "Keep branches (Recommended)" - Description: "Delete workspace but keep git branches. You can still access unpushed commits from the main repository."
  2. "Delete branches" - Description: "Delete workspace AND branches. Warning: uncommitted changes and unpushed commits will be lost."
  3. "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