Use the Agents window

The Agents window provides an agent-first interface in Visual Studio Code for delegating and coordinating tasks across projects. Run independent tasks in parallel, monitor their progress, and review results in one place. Use chat in the editor when you want to collaborate with an agent alongside the code you're editing or debugging.

This guide follows the workflow from choosing where an agent makes changes to monitoring, validating, and integrating its work. Start with one task, then add independent tasks as needed. If you're new to agent-assisted coding, first complete the agents quickstart.

Open the Agents window

Select Open in Agents in the VS Code title bar, or run Chat: Open Agents window from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). The window opens alongside your main editor window.

If you're already signed in to GitHub in VS Code, you'll also be signed in when the Agents window opens. From the command line, use code --agents.

Agents window interface overview

The Agents window separates managing work across projects from working on an individual task. Use the Primary Side Bar to organize sessions and access automations and customizations, the central session area to collaborate with agents, and the Secondary Side Bar to inspect and validate the active session's work.

The available tools depend on the session and enabled features.

Understand the active session

Selecting a session makes it the active session and determines which project and conversation the session tools apply to. When several session panes are visible, select a pane to make it active. The active session is highlighted in the sessions list.

Before you send feedback or run a command, confirm which session is active. Terminal commands and tasks run in that session's folder or worktree, and browser tabs belong to the session where you open them.

Quick chats have no project workspace, so they don't show workspace-specific files and changes.

Start an agent session

Choose a task with a clear outcome and checks you can run to verify it. The following steps start a session in a local project. For other environments or tasks without a project, see Other ways to start a session.

1. Select New Session at the top of the sidebar or press ⌘N (Windows, Linux Ctrl+N). To start directly in a specific workspace, hover over the workspace in the sessions list and select + (New Session).

2. Select This Computer from the environment picker above the input. In the workspace picker, select a recent folder or Open Folder.

   If the workspace isn't trusted, review the Workspace Trust prompt before you continue.

3. For a Git repository, choose Branch to work in your current folder or New Worktree to keep changes separate. Review the isolation choices and requirements before you send the prompt.

4. Review the permission level in the input toolbar. It controls which actions need your approval and is separate from file isolation. Learn about permission levels.

5. Describe the outcome you want, any constraints, and how the agent should check its work. Press Enter to submit the prompt.

   For additional context, select Add Context (+). If prompted, select a repository first. Pasting an issue or pull request URL into the prompt also adds it as a context attachment.

   You can optionally change the agent harness, agent, or model.

Choose where an agent makes changes

For a Git workspace you can choose between applying changes in the current branch or a new worktree. Use the isolation dropdown above the input to choose where the agent edits files.

Choosing a base branch for New Worktree doesn't switch the branch in your active workspace.

Git-ignored files, including dependencies and local configuration, are also absent from new worktrees by default. Run your project's setup or configure which ignored files to include.

Dev Container sessions work directly in the container workspace and don't support New Worktree. See Run a session in a Dev Container.

Work with multiple sessions

You can run multiple agent sessions in parallel, either in the same project or across different projects. Each session has its own conversation and task context, so you can delegate independent work and review one result while another session continues. For example, one session can implement a feature in one project while another investigates a bug in a different project.

Use separate sessions for independent tasks you want to track and review separately. For related conversations you want to keep together, work with multiple chats in a session.

To add another task, select New Session, choose its project, and submit a prompt. You don't need to wait for the other sessions to finish. Switch between them in the sessions list to check progress, answer questions, or give feedback. Sessions can run in parallel without being displayed side by side. Arrange sessions in a grid when you want to keep several conversations visible.

For parallel changes in the same repository, use separate worktrees to keep edits apart. Separate sessions or chats don't automatically isolate files: those using the same folder can edit the same files. Choose tasks that can proceed independently. If one depends on another's result, complete that prerequisite first. For a walkthrough, follow Delegate two tasks without mixing their changes.

Use the sessions list to check status and change statistics. Select a session to inspect its conversation:

• If it needs input, answer its question or review the approval request.
• While it works, check that its changes stay within the task's scope. Send corrections to that session, not another task's conversation.
• When it finishes, review and validate the result. A completed response isn't proof that the task is correct.

Confirm the active session before sending feedback or running commands. For steering and stopping requests, see Use chat. To group, pin, or find sessions, see Organize sessions.

Arrange sessions in a grid

To keep two sessions visible, right-click a session in the list and select Open to the Side. To start another session without replacing the current pane, hold Alt (Option on macOS) and select New Session.

Drag a session to the top, bottom, left, or right edge of another session to create a horizontal or vertical split. A placement preview shows where the session appears.

Only one pane is active at a time. Selecting another session in the list replaces an unpinned active view.

When multiple panes are visible, use the session header's Session Layout menu to arrange or resize them. Maximize expands one pane, and Restore Size returns to the grid. These actions are separate from Session Layout.

Review and finish an agent session

When an agent finishes a task, use the Agents window to review its changes, request revisions, and validate the result. Once the work meets your requirements, commit the changes and integrate them into your project, either locally or through a pull request.

Select the session you want to review to make its files, changes, and tools active.

For more in-depth coding or debugging, select Open in Editor to continue a supported project session in the main editor window, with the editor, debugger, and other development tools alongside the conversation.

Inspect workspace files and changes

In the Secondary Side Bar, use Files to browse the workspace or worktree and Changes to review edits. In Changes, choose Branch for the branch diff, Uncommitted for pending changes, Session for the session's edits, or Last Turn for its latest turn. Review the full relevant change, not only the latest response.

Check that the result meets your requested outcome, preserves required behavior, and contains no unrelated edits.

To provide immediate feedback, open a file's diff, select a range, and use the feedback controls to leave range-based feedback for the agent. For detailed review and recovery controls, see Review AI-generated code edits.

Validate changes

Run the project's tests, build, and any manual checks needed to verify the requested behavior. Check the output for failures or skipped checks rather than relying only on the agent's summary.

• Select Terminal in the session activity bar to run commands in that session's folder or worktree.

• Use the tasks control in the application title bar to run a configured task, or define a new one.

• For a web app, select a localhost link or open an HTML file in the integrated browser. You can also ask the agent to use browser tools, then verify the result yourself.

If a check fails, send the evidence to the same session, request a correction, and repeat the affected checks.

Commit changes

For uncommitted changes, open Changes, select Uncommitted from the changeset dropdown, and then select Commit. VS Code generates a commit message and commits all current changes in the session's Git repository, so review them first. The available Git actions depend on the session type.

Generating the commit message requires signing in to GitHub Copilot, even when the session uses another provider's credentials.

Integrate the result

Committing records the changes but doesn't necessarily put them in the branch where you need them:

• With Branch isolation, edits are already in the selected folder. Follow your normal branch and pull request workflow.
• With New Worktree, edits remain in the separate worktree. Integrate the reviewed branch into your target branch locally, or create a pull request. For a parallel-work example, follow Integrate and retest.

After combining changes from multiple sessions, rerun the relevant checks on the combined result. Keep the sessions available until that validation is complete, then mark finished sessions as done.

Create a pull request

If the session doesn't already have a pull request:

1. Select Create PR in the title bar. Review the repository, source and base branches, and generated title and description. You can edit the text while generation finishes.

2. Select Create as Draft if the changes aren't ready for review.

3. Under After creation, choose Merge Manually to retain control of merging, or Auto-Merge to let GitHub merge when required checks and approvals pass. For auto-merge, select the merge method. Auto-merge isn't available for drafts and doesn't fix failed checks or review feedback.

   The optional Agent merge choice (Experimental) can ask the agent to address blockers. Review its configuration and safeguards before selecting it.

4. Select Create PR. Any uncommitted changes are committed and the branch is pushed before the pull request is created.

To have the agent create the pull request instead, select Pull Request Actions > Send Create PR Message in the form. This asks the agent to generate its own title and description, rather than use the form's text, with your selected draft status and merge options.

Remove a pull request from a session

To remove a pull request artifact without closing the pull request on GitHub, right-click its pill above the chat input and select Remove Pull Request Artifact from Session. If the pill contains multiple pull requests, open its dropdown and select the action for the relevant pull request.

A separate association, such as the one created when you start a session from a pull request, remains unchanged.

Other ways to start a session

Use these workflows when your task needs a different starting point or execution environment.

Start a quick chat

Quick chats aren't scoped to a project. Use one for a question or task that doesn't need a workspace. They appear in the Chats group at the top of the sessions list.

1. Select + on the Chats header (⌘K ⌘N (Windows, Linux Ctrl+K Ctrl+N)) or run New Quick Chat from the Command Palette.

   

2. Choose an available harness, enter your prompt, and submit it.

Quick chats also support nested sessions, where available. With No Workspace selected, each nested session uses its own temporary folder.

Continue a quick chat in a workspace

If a quick chat becomes project-specific, continue it in a local workspace without losing its conversation history.

1. Ask the agent to continue in a specific local folder.
2. Confirm the folder and choose whether to edit it directly or use a worktree.
3. Review and approve the Set Workspace confirmation and any Workspace Trust prompt.

After setup, the chat moves to the workspace's group and the agent continues your request. For chats that already have a workspace, see Move a chat to another folder or worktree.

Open without GitHub sign-in (Experimental)

On desktop, you can run sessions using supported provider credentials instead of a GitHub sign-in:

• Follow the Claude BYOK setup for a supported API key or provider configuration.
• Follow the Codex setup to use a ChatGPT sign-in.
• Configure a supported BYOK model for the Agents window.

If no provider is configured, select Add Models or Sign In in the window. Models and operations that require GitHub authentication prompt you when needed. The browser-based Agents window requires GitHub sign-in.

Run in another environment

For a GitHub repository, select Work in Repository in the workspace picker. To work on another machine, select SSH or Dev Tunnels from the environment picker and follow the remote session setup.

For managed compute that runs independently of your local machine, start a cloud session Cloud sessions is experimental and might change or be removed. . To return to its work later, reopen the existing session.

You can also use the browser-based Agents window to access remote sessions from another device.

Run a session in a Dev Container

Use a Dev Container to run the agent with your project's tools and dependencies. This is supported in the desktop app for local folders and folders on configured SSH, Tunnel, or WSL hosts, but not in the browser-based window.

Before starting:

• Install and run Docker on the host that contains the folder, with its CLI on PATH.
• Add a Dev Container configuration at .devcontainer/devcontainer.json or .devcontainer.json.
• For remote folders, configure the connection to a host that supports Dev Container sessions.

1. Select New Session.
2. In the workspace picker, expand the eligible folder's menu and select Use Dev Container. The workspace label gains the - Dev Container suffix.
3. Choose an available harness and submit your prompt.

To switch back before starting, select Use This Computer or Use Remote Host from the folder menu. Dev Container sessions edit the container workspace directly and don't support New Worktree. For command restrictions, see sandboxing in Dev Containers.

If startup fails, check the workspace-specific Dev Container Output channel. The picker option isn't available for unsupported hosts or folders nested inside another remote environment. Dev Container support is on by default through chat.agentHost.devContainer.enabled Open in VS Code Open in VS Code Insiders .

Idle containers stop after five minutes when no session is working, waiting for input, or holding an unsent draft. Continuing a session restarts the container without losing the conversation. Change the timeout with chat.agentHost.devContainer.idleTimeout Open in VS Code Open in VS Code Insiders (300 seconds by default, 0 to turn off automatic shutdown). Marking sessions as done or deleting them can still remove the container.

Start a session from a pull request

For a local GitHub-backed workspace, start from an existing pull request to ask questions or continue its changes. The session includes the pull request details, changes, and comments, and uses an isolated worktree that tracks its branch.

1. Group the sessions list by workspace.

2. Hover over the workspace, expand the + (New Session) action, and select New Session from Pull Request.

   

3. Select a pull request. The session opens with its title and shows its changes in Changes.

4. Ask questions or request revisions. Review, validate, and commit any new changes, then select Sync Changes in the title bar to update the existing pull request branch.

Work with multiple chats in a session

For related conversations, select + (New Nested Session) on a supported session's row. Keep its folder, or choose another folder, New Worktree, or No Workspace, where supported. The nested session uses the parent's harness by default and stays on the same host.

For shared context, chat tabs, side chats, and moving conversations, see Run multiple chats in a session. To choose another harness, see mixed-harness chats Mixed-harness chats is experimental and might change or be removed. Share feedback about Mixed-harness chats (opens in new tab). .

Compare model results (Preview)

Run the same prompt with multiple models or harnesses to compare responses or isolated code changes. See Compare model results for setup, judging, and synthesis options.

Continue in another interface

To edit or debug alongside a supported project conversation, select Open in Editor in the title bar. To return, select Open in Agents, then select the existing session. Check the supported session types and continuation requirements.

For continuity across apps and devices, use GitHub Environments (Preview). For VS Code-specific remote access, use SSH or dev tunnels. Keep the host and its required application or service running.

Automate follow-up work

Finish a pull request with agent merge

Agent merge monitors a session's pull request and asks the agent to address blockers. It can address reviews, fix failed required checks, resolve conflicts or update a branch, and optionally merge the result. It requires chat.agentMerge.enabled Open in VS Code Open in VS Code Insiders and a supported session.

1. Enable chat.agentMerge.enabled Open in VS Code Open in VS Code Insiders and open a session associated with a pull request.

2. Select Agent merge in the title bar, and then select Enable agent merge.

3. Review the options in its menu. You can also run Configure agent merge for Active Session from the Command Palette.

   • Blockers: select Address Reviews, Fix CI Failures, or Resolve Conflicts and Behind Branches.
   • Merge Pull Request: choose Off to leave merging to you, If Unchanged to merge only if the agent makes no changes, or When Ready to merge after the selected work and required checks and approvals.

These choices are also available when you select Agent merge in the Create PR form. For all options, see the agent merge settings.

For a draft pull request, use Mark Ready in Changes when it is ready for review. While blockers are being addressed, this action is in the action menu.

Agent merge waits for required checks and rechecks readiness before merging or adding the pull request to the merge queue. It turns off if the session starts tracking another branch or pull request.

To review the changes from the most recent agent merge repair cycle, open the Changes view and select Agent merge Changes from the changeset dropdown. This changeset compares the latest completed agent merge repair turn with the preceding completed user turn. It remains empty after your latest message until agent merge completes another repair turn.

To stop monitoring the pull request, select Agent merge in the title bar, and then select Disable agent merge.

Schedule recurring tasks

Automations run saved agent tasks on a schedule or, for cloud automations Cloud automations is in preview and might change before it becomes generally available. Share feedback about Cloud automations (opens in new tab). , in response to supported repository events. Select Automations in the sidebar to get started. Learn how to create and manage agent automations.

Configure the Agents window

You can personalize chat, adjust the window layout, configure settings and extensions, and choose how Markdown files open. See Configure the Agents window for all window-specific options.

For other interaction options, use Voice Mode Voice Mode is experimental and might change or be removed. or canvases Canvases is in preview and might change before it becomes generally available. Share feedback about Canvases (opens in new tab). where supported.

By default, the Chats group remains visible even when empty. Set sessions.list.showEmptyDefaultGroups Open in VS Code Open in VS Code Insiders to false to hide empty default groups.

Configure isolation defaults

The sessions.useWorktree Open in VS Code Open in VS Code Insiders setting controls the initial isolation choice for a workspace that hasn't started a session before. After you start a session, VS Code remembers that workspace's isolation choice instead. The branch selection isn't remembered.

Use git.worktreeIncludeFiles Open in VS Code Open in VS Code Insiders to copy ignored files into new worktrees. For large folders, git.worktreeSymlinkFolders Open in VS Code Open in VS Code Insiders (Experimental) can symlink a folder instead. Changes through the symlink affect the original folder, so don't use it for files that must stay isolated.

Limitations

• Sessions that use the experimental Codex integration can run in both the Agents window and the main VS Code window. Local harness sessions and Codex sessions from the OpenAI extension run only in the main VS Code window.

• Copilot Cloud sessions are only supported for GitHub-backed repositories. For non-GitHub projects, you can still use Copilot in the Agents window.

• The agents dropdown currently doesn't have the plan agent. You can use the /plan command in a Copilot or Claude agent session. In Copilot harness sessions, the plan agent is also automatically invoked when you ask it to create a plan.

• Running multiple chats in a single session is currently supported for sessions that use the Copilot or Claude harness.

• Multi-root sessions are not yet supported in the Agents window. You can ask the agent to work across projects in a single session.

Next steps

• Use chat in VS Code - send and steer requests, add context, and navigate conversations.
• Manage agent sessions - organize, fork, archive, and export sessions.
• Review AI-generated code edits - inspect, revise, or undo agent changes.