Use the VS Code Agents application (Insiders)

The Visual Studio Code Agents application is a separate app, installed alongside VS Code, built for the agent-first experience. The Agents application gives you access to all your workspaces without needing to open each one individually in a separate window. You can run multiple sessions in parallel across all your projects, all from one place.

The Agents application shares your sessions with the main VS Code window, so you can switch between them at any time.

In this article, you learn about the VS Code Agents application and how to start and manage agent sessions across your projects.

Prerequisites

The Agents application is installed together with VS Code Insiders. It doesn't require a separate download or installation.

• Visual Studio Code Insiders installed. Download VS Code Insiders.
• Access to GitHub Copilot. Follow the steps in Set up GitHub Copilot in VS Code to sign in and activate your subscription.

Code-first vs. agent-first

There are two primary ways to work with AI in VS Code:

• Code-first: you write code in the editor and use AI as a coding assistant to help you implement features, fix bugs, and refactor code. Your primary interface is the editor for editing code, testing, and debugging. You use AI to enhance your existing coding workflow.

• Agent-first: you build applications by handing off (high-level) tasks to an AI agent. The agent plans, implements, and verifies the result. Your primary interface is chat and the sessions list for organizing work, while the editor is a secondary interface for reviewing and tweaking the AI's implementation when necessary. You use AI to shift how you work and focus more on defining the problem and reviewing solutions.

The Agents application is built for the agent-first approach. It provides a focused environment for managing agent sessions across all your projects, with chat as the central interface for interacting with your agents. The Agents application is a complement to VS Code, which is optimized for the code-first approach.

Open the Agents application

The Agents application is a separate application that runs alongside your main VS Code window. To open the Agents application, use one of the following methods:

• Open the Agents application directly from your Start menu or Applications folder by launching Visual Studio Code Agents - Insiders (Windows and macOS).

  Note

  The option to launch the Agents application from the OS is currently not available on Linux. You can still access the Agents application on Linux through the command line or from within VS Code.

• In VS Code, select the Agents icon in the title bar or run Chat: Open Agents Application from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

  You can also open the Agents application directly from the VS Code welcome page.

• Run code-insiders --agents from the command line.

The Agents application requires GitHub authentication to access your Copilot subscription and sessions. After first launch, you'll be signed in to GitHub if you've already signed in within VS Code .

Interface overview

The Agents application picks up your existing Copilot CLI, Cloud, and Claude agent sessions across your workspaces. You can switch between agent sessions across the different workspaces without needing to open each workspace in a separate window.

The Agents window has the following main areas:

1. Sessions list: in the sidebar, where you can view and manage all your sessions across workspaces. By default, sessions are grouped by workspace. Right-click a session to see more commands, such as renaming, marking as done, pinning, and more.

2. Customizations panel: below the sessions list, where you can access your agent customizations to tailor the agent behavior to your workflow and preferences.

3. Chat area: in the center, where you see the chat conversation history and where you can interact with the agent through prompts.

4. Changes panel: on the right, where you can review file changes and other artifacts generated by your agent during a session, and view a file explorer of the workspace.

Start an agent session

The Agents application and VS Code share the same underlying agent sessions (Copilot CLI, Copilot cloud, and Claude agent). This means that any session you start in the Agents application is immediately available in VS Code.

To start a new agent session in the Agents application:

1. Select New at the top of the sidebar or press ⌘N (Windows, Linux Ctrl+N).

   

2. Use the workspace dropdown to select a local folder or GitHub repository for your chat session.

   The type of agent is determined by the type of workspace you select:

   • Folder: choose between the Copilot CLI or Claude agent to start a new session. You can select Continue In to hand off the session to a Copilot Cloud agent at any time during the session.
   • Repository: sessions started in a GitHub repository use the Copilot cloud agent.

   You can directly start a session scoped to a specific workspace by hovering over a workspace in the sessions list and selecting +.

   Tip

   You can track and create sessions that run on a remote machine via SSH or a dev tunnel. See Open a session on a remote machine for more information.

3. For Copilot CLI sessions, choose between folder and worktree isolation for the session.

   With worktree isolation, the agent operates in a separate folder created by Git worktree, which keeps changes isolated from your main workspace until you're ready to merge them.

   With folder isolation, the agent operates directly in your main workspace, and changes are applied directly to your files. This is the default behavior for non-Git projects.

   Optionally, select a source control branch to base the session on.

   

4. Optionally, select a custom agent and language model for the session. You can change these at any point during the session.

5. Type a prompt that describes what you want to accomplish, and press Enter.

   The agent breaks down your task into steps, writes code, runs commands, and self-corrects when something goes wrong. Continue the conversation to refine the results or change direction.

Manage and review file changes

The Changes panel in the Agents application provides a dedicated view with detailed information about the files and agent edits made during a session. The Changes panel is split into two main tabs:

• Files tab: a file explorer view of all files in the workspace.
• Changes tab: a list of files that have been changed, added, or deleted by the agent. Select the Branch Changes dropdown to choose which changes to view.

To review changes made by the agent, select a file in the Changes tab to open a diff view that shows the edits the agent has made compared to the current state of the workspace. While reviewing the changes in the diff view, you can comment directly in the file to signal the agent to make adjustments.

You can open the diff view side-by-side with the Chat view inside the Agents application or open it in a modal window to focus on the changes. Use the layout controls in the diff view toolbar to toggle between different display modes.

After reviewing the changes, the Changes panel provides the following options to act on the edits made by the agent:

• Commit: when using folder isolation, commit the changes made by the agent directly to your workspace.
• Merge: when using worktree isolation, merge (and optionally sync upstream) and create a pull request.
• Checkout: for Copilot Cloud sessions, check out the branch associated with the session's pull request locally to review or request further edits.

Validate agent changes locally

In addition to reviewing changes in the Changes panel, you can also validate the edits made by the agent locally before committing or merging them. The Agents application supports running tasks and commands in the context of the current session. For example, you can run a build or tests to ensure that the changes made by the agent do not break your project, or start a development server to verify that the edits behave as expected in a running environment.

To configure tasks in the Agents application:

1. Start or open a session.

2. Select the Tasks dropdown in the title bar and select Add Task.

   

3. Provide the task details:

   • Name: a descriptive name for the task.
   • Command: the command to run when the task is executed (for example, npm run build or pytest).
   • Run Options: automatically run the task when the session worktree is created.
   • Save In: choose whether to save the task configuration in the workspace or your user profile for reuse across projects.

4. Select Add Task to save the task configuration.

Once the task is configured, it will appear in the Tasks dropdown, and you can run it in the context of the current session to validate the changes made by the agent.

If your application involves browser-based behavior, you can use the integrated browser in the Agents application. Select a localhost link from the chat session to open it in the integrated browser inside the Agents application. The browser tab will persist across session switches, so if you open another session, the browser tab will open to the same page you had open previously and preserve the state of that page.

Alternatively, you can also select a localhost link from the integrated terminal or open the integrated browser with the Open Integrated Browser command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). You can use the layout controls in the integrated browser to show it as a modal window or embedded in the Agents application layout alongside other views.

If you want to run terminal commands in the context of the current session, select the Open Terminal icon in the title bar to open an integrated terminal with its current working directory set to the session's folder or worktree.

Open a session on a remote machine

You can connect to a remote machine to start a session there or track the progress of an existing session running on that machine. This is useful when you're away from your main development machine but still want to check in on your agent's work, or to take advantage of the remote machine's resources, such as specialized hardware or a specific environment configuration.

The Agents application connects to the remote machine using the Agent Host Protocol (AHP) over SSH or a dev tunnel. When you connect, the application automatically installs and starts the Copilot CLI on the remote machine. This also means that the remote machine must be powered on and accessible over the network.

Connect via SSH

Prerequisite: the remote machine must be accessible over SSH. No extra agent installation is needed on the remote machine.

To start a session on a remote machine via SSH:

1. Select New or press ⌘N (Windows, Linux Ctrl+N) to start a new agent session.

2. In the workspace dropdown, select SSH. If you've already set up SSH connections, they will appear as options in the dropdown.

   

3. Enter the SSH connection string for the remote machine (for example, user@hostname).

4. Select the folder on the remote machine to use for the session.

5. Type a prompt and press Enter to start the session.

Connect via dev tunnel

Prerequisites:

• A dev tunnel is already running on the remote machine. See Developing with Remote Tunnels for setup instructions.

To start a session on a remote machine via dev tunnel:

1. Select New or press ⌘N (Windows, Linux Ctrl+N) to start a new agent session.

2. In the workspace dropdown, select Tunnels and choose your account type.

   

3. Choose the active dev tunnel from the list.

4. Select the folder on the remote machine to use for the session.

5. Type a prompt and press Enter to start the session.

Create a sub-session

When you have an active session, you can start a sub-session to give the agent a separate, parallel task within the same workspace. A sub-session shares the same workspace and worktree as the parent session, but starts with a blank chat. The sub-session doesn't carry over the parent's conversation history.

This is useful when you want to work on an independent task in the same project without interrupting the ongoing session or starting a completely new one from scratch.

To create a sub-session:

1. In an active session, select New Sub-Session (+) in the application title bar.

   Notice that a new tab appears in the chat area for the sub-session, alongside the tab for the parent session. The sub-session does not appear as a separate item in the sessions list.

   

2. Type a prompt and press Enter to start the sub-session.

Manage your sessions

The sessions list in the sidebar shows all your active sessions across workspaces. You can group sessions by project or by timeframe to keep track of related work. Each session item surfaces the key information such as session name, workspace, agent type, and file change stats.

Use the filter and search options to narrow down the list and find the session you want to work on.

Select any session to view the chat conversation history and pick up where you left off. The Changes panel surfaces the latest file updates from the agent and a file explorer view of the workspace.

Right-click on any session in the list to see additional management options, such as renaming, deleting, and more. For advanced session management, such as archiving, forking, checkpoints, and exporting, see Manage chat sessions in chat documentation.

Customize agents for your project and workflow

The Customizations panel gives you direct access to all AI customization options:

The Agent Customizations panel enables you to easily manage all your customizations in one place:

• View and edit existing customizations for the project (workspace), or across all your projects (user).
• Add new customzations by using the built-in editor or by generating them from a prompt.
• Install plugins or MCP servers from the marketplace.
• Enable or disable customizations without removing them.

Use the dropdown in the top left of the Agent Customizations panel to choose which agent the customizations should apply to.

Switch to another GitHub account

To use a different GitHub account in the Agents application, select the account icon in the top right corner of the application window and choose Sign out. After signing out, select Sign in to authenticate with a different GitHub account.

Limitations

• The agent can't directly open the integrated browser for you for now. You can start the integrated browser from the Command Palette (Browser: Open Integrated Browser) or by selecting a localhost link in the Agents app.

• The Agents application currently only supports the following agent types: Copilot CLI, Copilot Cloud, and Claude agent. To use local or other third-party agents, manage your sessions from the main VS Code window.

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

• The agents dropdown currently doesn't have the plan agent. You can still use the /plan command in a Copilot CLI or Claude agent session. In Copilot CLI sessions, the plan agent is also automatically invoked when you refer ask for creating a plan in your prompt.

• Sub-sessions are currently not yet supported for Claude agent sessions.

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

Frequently asked questions

Next steps

• Manage chat sessions - checkpoints, forking, archiving, and exporting sessions.
• Using agents - agent types, delegation, and autonomy levels.
• Customize AI - full customization reference.
• Best practices - tips for effective prompting.