[FEATURE] Named profiles for worktree.sparsePaths to support multi-service monorepos

1. PREFLIGHT CHECKLIST

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

2. PROBLEM STATEMENT

worktree.sparsePaths only supports a single flat array of paths. In monorepos with multiple services, different tasks require different subsets of the repo. There's no way to define named configurations and select one when launching a worktree.

Currently, if I'm working on service A I need paths ["services/auth/", "shared/utils/", "package.json"], but if I'm working on service B I need ["services/billing/", "shared/models/", "package.json"]. I have to manually edit settings.json every time I switch contexts, or leave sparsePaths broad enough to cover everything — which defeats the purpose of sparse checkout in large repos.

3. PROPOSED SOLUTION

Support named profiles in worktree.sparsePaths, with an optional defaultProfile:

{
  "worktree": {
    "sparsePaths": {
      "auth": ["services/auth/", "shared/utils/", "package.json"],
      "billing": ["services/billing/", "shared/models/", "package.json"],
      "full-stack": ["services/auth/", "services/billing/", "shared/", "package.json"]
    },
    "defaultProfile": "auth"
  }
}

Select a profile at launch:

claude --worktree --sparse-profile auth
claude -w --sparse-profile billing

Backwards compatible — a plain array still works as today (unnamed default profile):

{
  "worktree": {
    "sparsePaths": ["services/auth/", "shared/utils/"]
  }
}

Default selection and error behavior:

• If --sparse-profile is provided, use that profile. Error if the name doesn't match any defined profile.
• If --sparse-profile is omitted and defaultProfile is set, use that profile. Error if defaultProfile points to a nonexistent profile.
• If --sparse-profile is omitted and no defaultProfile is set but profiles exist, error with a message listing available profiles.
• If --sparse-profile is passed but sparsePaths is the legacy array form (not profiles), error.

4. ALTERNATIVE SOLUTIONS

• Per-project settings: Put different sparsePaths in each repo's .claude/settings.json. Works for single-service repos but not for monorepos where one repo contains multiple services.
• Script wrapper: A shell script that rewrites sparsePaths before launching Claude. Hacky, error-prone, doesn't integrate with the CLI.
• Manual editing: Edit settings.json before each session. Tedious and defeats the workflow benefits of worktrees.

5. PRIORITY

• [ ] Critical - Blocking my work
• [ ] High - Significant impact on productivity
• [x] Medium - Would be very helpful
• [ ] Low - Nice to have

6. FEATURE CATEGORY

• [x] CLI commands and flags
• [ ] Interactive mode (TUI)
• [ ] File operations
• [ ] API and model interactions
• [ ] MCP server integration
• [ ] Performance and speed
• [x] Configuration and settings
• [ ] Developer tools/SDK
• [ ] Documentation
• [ ] Other

7. USE CASE EXAMPLE

Scenario: Monorepo with 6 services, working on auth + billing

1. I configure two sparse profiles in global or project settings
2. I launch claude --worktree --sparse-profile auth — agent gets only auth-related paths
3. In another terminal, claude --worktree --sparse-profile billing — agent gets only billing paths
4. Each worktree is minimal, fast to create, and scoped to the relevant code
5. No manual config editing between sessions

Without profiles, I either sparse-checkout everything (slow, noisy) or manually swap the config each time.

8. ADDITIONAL CONTEXT

worktree.sparsePaths was added in v2.1.76 (March 14, 2026). This would be a natural extension of that feature for monorepo workflows.