Workspace picker redesign: prepare for multi-folder, local GitHub checkout, and PR review sessions

[meganrogge]

Summary

The workspace picker redesign should make the common path—starting useful local work—clear and immediate, while leaving room for richer workspace and environment choices as those capabilities mature.

Latest design decision

When chat.agentSessions.consolidatedRemoteWorkspaces is enabled, use one unified, searchable workspace picker instead of separate Local and Remote tabs. The unified list must retain one Remote entry with a flyout containing connected remote hosts plus SSH..., Tunnels..., WSL..., and other supported remote connection and management actions. Use Start from Scratch rather than No workspace for beginning without a backing workspace. In unified mode, collapse a generated <repo>.worktrees/<branch> recent onto an existing parent-repository entry, and place machine-specific remote workspace recents inside the Remote flyout so users with several development machines do not get a flat list of duplicate repository rows. Local folders, GitHub repository acquisition, Cloud repositories, and enabled remote targets should appear as actions in the same list. Category-specific entry points such as attaching a folder or GitHub context remain scoped. When the setting is disabled, preserve the existing tabbed picker.

Priorities

Priority	Area	Why
P0 — Required	Local checkout for GitHub repositories and independent environment selection	Selecting a repository that is not local currently does not lead to the expected usable desktop workflow. This is the primary gap.
P1 — High value	Local PR review sessions	This builds directly on local checkout and enables a concrete end-to-end workflow: inspect, run, review, edit, and push.
P2 — Preserve existing behavior	Keep multiple folder attachments clear and discoverable	The picker already supports attaching additional folders as agent context. This is a UX guardrail, not a new capability or a multi-root commitment.
P3 — Nice to have	Multi-select issues and start agent work	Useful power-user workflow with precedent in the GitHub Copilot app, but not necessary for the initial workspace picker redesign.

P0 — Local checkout for GitHub repositories

Problem

When a user chooses a GitHub repository they have not checked out locally, they cannot currently proceed with the expected local workflow. Instead, Cloud is selected by default. For a desktop VS Code user, the more natural default is to clone/check out the repository and work on it locally.

Cloud is important and is likely to become more prominent as the environment experience matures, but it should be presented as an environment choice rather than being coupled to repository discovery or treated as the only path for a remote repository.

Proposed direction

• Separate the flow into independent concepts:
  • Source: local folder, GitHub repository, pull request, or issue.
  • Environment: Local or Cloud.
  • Harness/session type: the agent or workflow that operates in that environment.
• For a GitHub repository that is not local:
  • Default the environment to Local.
  • Offer to clone/check out the repository, including a clear destination choice or an appropriate remembered/default clone location.
  • Keep Cloud visible as an explicit alternative.
• Do not encode Cloud as a special session type tied to GitHub repositories. The longer-term model should allow supported harnesses to run in the Cloud environment as capabilities become available.
• Remember an explicit user environment choice when appropriate, but avoid silently changing the default merely because the selected repository is remote.
• Clearly communicate clone, authentication, repository access, and environment availability errors rather than falling back to a different environment.

Acceptance criteria

• Choosing a GitHub repository that is not local offers a clone/checkout flow and defaults to Local.
• Cloud remains a visible, explicit environment choice rather than an implicit consequence of choosing a remote repository.
• Environment selection is modeled independently from source and harness/session type.
• Authentication, clone, checkout, and unsupported-environment failures are surfaced with actionable recovery.

P1 — Local PR review sessions

Problem

The new session page should allow a user to select a pull request and start a review-oriented session against a local checkout of its branch. The user should be able to inspect the diff, run the code and tests, review it, make changes, and push updates where permissions allow.

Proposed direction

• Add pull requests as a source discoverable from the GitHub experience in the picker.
• Provide a Review Pull Request session intent/action.
• On Local:
  • Clone the repository if needed.
  • Fetch and check out the PR branch safely, accounting for forks and branches that cannot be pushed to directly.
  • Preserve PR metadata in the session so review context and relevant actions are available after launch and restoration.
• Allow the normal local toolchain: Files, Changes, terminal, run/debug, tests, review comments, edits, commits, and push when authorized.
• Offer Cloud as an explicit environment option when the selected harness and PR workflow are supported there.

Acceptance criteria

• A user can select a pull request and start a local PR review session against an appropriate checkout.
• The PR session retains enough metadata to support review, restoration, and relevant GitHub actions.
• Fork, permission, and read-only checkout states are clearly communicated.

P2 — Preserve and clarify existing multiple-folder attachments

Current behavior

The workspace picker already distinguishes between:

• Select... — chooses the single execution workspace/root for the session.
• Attach Folder... — adds another folder as agent context without changing the execution workspace.

Users can attach multiple additional folders, and those context attachments remain attached if the execution workspace changes. This already addresses the immediate need to let an agent work with context from more than one folder. It is intentionally different from a true multi-root workspace: Files, Changes/source control, and other surfaces continue to operate against the selected execution workspace.

Direction for this redesign

• Preserve the existing ability to attach multiple folders.
• Keep the distinction between the execution workspace and attached folder context explicit in labels, pills/badges, and accessible descriptions.
• Make the existing attachment action discoverable from the redesigned picker; do not introduce another add-folder mechanism for the same purpose.
• Do not treat true multi-root support as a requirement for this redesign. If multi-root across Files, Changes, persistence, and session launch is pursued later, track it as separate end-to-end work.

Acceptance criteria

• A user can attach multiple folders as agent context while retaining one execution workspace.
• All attached folders remain visible and removable from the new-session experience.
• Changing the execution workspace does not silently discard additional folder attachments.
• The UI does not imply that attached folders become roots in Files or Changes.
• No duplicate Add Folder or Attach Folder affordance is introduced.

P3 — Nice to have: multi-select issues and start agent work

GitHub Copilot app precedent

The GitHub Copilot app's My Work view already provides a useful interaction model:

• Users select multiple issues and/or pull requests in the table.
• A selection toolbar opens an action palette/dropdown.
• The palette offers Chat, New individual sessions, and New session.
• For issues, it also supports choosing a target repository.
• New individual sessions creates one independently trackable workspace/session per selected item.
• New session creates one combined session. For multiple items in a configured local project, it uses a neutral worktree from the repository's default branch and attaches every selected item as context rather than treating the first issue as the primary task.

This is a better reference than exposing only one ambiguous “start working” action: users can choose whether the selected issues belong together or should run independently.

Proposed direction

• Treat this as a follow-up enhancement, not a requirement for the initial workspace picker redesign.
• Add an issues source with multi-selection support when issue-driven workflows are prioritized.
• Once one or more issues are selected, expose an action palette/dropdown with:
  • New Individual Sessions — one independently trackable agent session per issue.
  • New Session — one session with all selected issues attached as context, for related work.
  • Optionally Chat — discuss the selected issues without creating a working checkout.
• If issues span repositories, require a clear target repository for a combined session; individual sessions can resolve their source and checkout per issue.
• Preserve issue URL, number, title, repository, and relevant body/context in the resulting session or sessions.
• For larger individual-session batches, show the scope before launch and report progress/failure per issue.

Follow-up acceptance criteria

• The issues source supports selecting more than one issue.
• The selection action palette clearly distinguishes combined and individual session creation.
• Individual mode starts one independently trackable session per selected issue.
• Combined mode attaches every selected issue as context and uses an explicit target repository.
• Batch launch reports success or failure per issue and permits retrying failed items without relaunching successful ones.

UX principles

• Optimize the default for the most common desktop expectation: selecting remote code should result in a usable local checkout.
• Keep source, environment, and harness choices conceptually independent.
• Reveal complexity progressively; do not make users configure every dimension when sensible defaults exist.
• Do not expose selections that lead to partially supported or misleading session states.
• Future-proof the design without making future capabilities prerequisites for solving today's core workflow.

Follow-up work to identify

P0/P1

• Local clone destination and repository reuse behavior.
• GitHub authentication and repository/PR discovery.
• PR checkout behavior for same-repository branches versus forks.
• Push permissions and safe behavior for read-only PRs.
• Capability negotiation between environments and harnesses.
• Session restoration when the checkout moves, disappears, or changes branches.

P2

• Validate the existing multiple-folder attachment flow in the redesigned picker.
• Ensure execution-workspace and attached-context terminology remains unambiguous.
• Track any future true multi-root work separately across Files, Changes/source control, persistence, and session launch.

P3

• GitHub issue discovery and filtering.
• Combined versus individual session defaults.
• Limits or confirmation thresholds for large issue batches.
• Mapping issues from multiple repositories to checkouts, worktrees, environments, and concurrent sessions.

[meganrogge]

Latest unified-picker refinements (behind chat.agentSessions.consolidatedRemoteWorkspaces):

• Use Open Folder instead of Select... for the local execution-workspace action.
• Do not show the generated Attach Folder action in the execution-workspace picker; folder attachment remains a separate context workflow.
• Remove trailing ellipses from unified-picker action labels. Legacy mode keeps its existing labels.
• Use the GitHub icon for both Add GitHub Repository and Pull Request. Generic Clone Repository keeps the clone icon.
• Remove the subtitle after Start from Scratch.

Also diagnosed the apparent delayed selection of the development worktree: the test launch command itself passed that worktree as an Agents folder handoff. The clean validation launch now omits the folder argument; no handoff is emitted and the picker does not receive that forced selection.

[meganrogge]

Search and icon follow-up:

• The unified picker placeholder is now Search.
• Search is a local, case-insensitive substring filter over rows already loaded in the picker (labels and descriptions for recents/actions). It does not search the filesystem, query GitHub, or search children inside the closed Remote flyout.
• This matches the GitHub app project picker conceptually: its search filters already-configured projects/actions by label; Add GitHub repository opens a separate GitHub repository picker for catalog search.
• Icons now align with the GitHub app: comment for Start from Scratch, folder for local recents/Open Folder, GitHub for Add GitHub Repository and Pull Request, link for Clone Repository, and cloud for Use Repository in Cloud.

The apparent worktree selection was stale state from an earlier dev launch that explicitly handed off the worktree. A clean dedicated --agents launch without a folder handoff now remains on the canonical vscode repository after provider hydration.

[vs-code-engineering]

Sharing media and context from merged PR #334591 for verification:

Summary

• replace the Local/Remote tabs with one searchable workspace picker behind chat.agentSessions.consolidatedRemoteWorkspaces
• add explicit local Add GitHub Repository, Clone Repository, and Use Repository in Cloud flows while preserving the legacy repository action when the setting is disabled
• move remote recents, hosts, SSH, tunnels, WSL, and related actions into a single icon-aware Remote flyout
• align wording and icons with the GitHub app, including Start from Scratch, Open Folder, and the Search placeholder
• collapse generated worktree recents onto known parent repositories without changing the actual execution checkout

Validation

• npm run transpile-client
• ESLint on all changed files
• ./scripts/test.sh --run src/vs/sessions/contrib/chat/test/browser/sessionWorkspacePicker.test.ts src/vs/sessions/contrib/providers/copilotChatSessions/test/browser/copilotChatSessionsProvider.test.ts (169 passing)
• git diff --check
• manually verified the dedicated Agents window after provider hydration and exercised the picker presentation

Source PR: #334591