Background agents in Visual Studio Code

Background agents in Visual Studio Code are CLI-based agents, such as Copilot CLI, that run in the background on your local machine. They operate autonomously while you continue other work in the editor. Background agents can use Git worktrees to work isolated from your main workspace and prevent conflicts with your active work.

This article covers the key features of background agents, and how to start and manage background sessions from Copilot CLI or OpenAI Codex.

What are background agents?

Unlike local agents that operate in and have aware of VS Code's editor context, background agents run independently via command-line interfaces (CLIs) on your local machine. You can view and manage all your background agent sessions from the unified Chat view in VS Code. This view also lets you create new background agent sessions directly from VS Code or hand off local agent conversations to background agents.

Because background agents run in the background without user interaction, they are well-suited for tasks that have a well-defined scope and all necessary context. Examples include implementing a feature from a plan, creating multiple variants of a proof of concept, or implementing clearly defined fixes or features.

Background agents autonomously apply changes to your codebase. To prevent interference with your active work in the editor, background agents can use Git worktrees to run in an isolated environment where they can make changes without affecting your main workspace. When you start a background agent session with worktree isolation, VS Code automatically creates a separate folder for that session. You can choose to run a background agent in your main workspace, however this might lead to conflicts.

Background agents run via the CLI and can't directly access VS Code built-in tools and run-time context (like failed tests or text selections). They also don't have access to MCP servers or extension-provided tools. They are limited to the models available via the CLI tool. Background agents can run terminal commands and might prompt you for approvals if needed.

To assign a task to a background agent, you can create a new background session directly from the Chat view, use the agent's dedicated CLI, or hand off a local chat conversation from VS Code as a background agent session.

Copilot CLI

The Copilot CLI is the primary background agent in VS Code. You can use the Copilot CLI directly from the terminal or start and manage sessions from with VS Code.

To get started, make sure to install and set up Copilot CLI. VS Code should handle this for you, but you can also choose to manually install the CLI via the following command:

npm install -g @github/copilot

Learn more about Copilot CLI in the GitHub documentation.

OpenAI Codex

The OpenAI Codex background agent uses OpenAI's Codex to perform coding tasks autonomously. To use the OpenAI Codex agent, make sure to install the OpenAI Codex extension from the Visual Studio Marketplace.

OpenAI Codex in VS Code enables you to use your Copilot Pro+ subscription to authenticate and access Codex without additional setup. Get more information about GitHub Copilot billing and premium requests in the GitHub documentation.

View and manage background agent sessions

You can view and manage all your background agent sessions from the Chat view in VS Code. Filter the session list to show only background agent sessions by selecting the Background Agents from the filter options.

Select a background agent session from the list to open the session details in the Chat view. If you prefer to view the session in an editor tab (chat editor), right-click the session and select Open as Editor.

If you prefer to view a background session in the terminal instead of the chat conversation in VS Code, right-click the session in the Chat view and select Resume Agent Session in Terminal. You can interact with the Copilot CLI directly in VS Code.

Start a background agent session

Depending on your workflow, you can start background agent sessions in several ways. You can create a new session and provide the task details directly by using the CLI, or start a new session from the Chat view in VS Code.

Another approach - especially for complex tasks - is to first interact with a local agent in chat in VS Code, and once the scope and details are clear, hand off the task to a background agent session. For example, you might use the Plan agent to outline a multi-step feature implementation, then delegate the actual coding to a background agent.

Create a Copilot CLI background agent session

You can create a new Copilot CLI background agent session in VS Code in several ways:

• From the Chat view:

  1. Open the Chat view (⌃⌘I (Windows, Linux Ctrl+Alt+I))

  2. Select the New Chat dropdown > New Background Agent

• While you're in a local chat session:

  • Type @cli <task description> in the chat input and send the message

  • Enter a prompt and then select Continue In > Background Agent

• Run the Chat: New Background Agent command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P))

A new background agent session opens where you can provide additional task details and track the progress of the Copilot CLI session.

Create an OpenAI Codex background agent session

To create a new OpenAI Codex background agent session from the Chat view:

• From the Chat view:

  1. Open the Chat view (⌃⌘I (Windows, Linux Ctrl+Alt+I))

  2. Select the New Chat dropdown > New Codex Agent

• Run the Codex: New Codex Agent command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P))

A new Codex background agent session opens where you can provide additional task details and track the progress of the Codex session.

Hand off an agent session to a background agent

For complex tasks, it can be helpful to first interact with a local agent in VS Code chat to clarify requirements, then hand off the task to a background agent for autonomous execution. When you hand off a local agent conversation to a background agent session, the full conversation history and context is passed to the background agent.

To continue a local agent session in a background agent session:

1. Open the Chat view (⌃⌘I (Windows, Linux Ctrl+Alt+I))

2. Interact with a local agent until you're ready to hand off the task to a background agent

3. To hand off to a background agent, you have the following options:

   • Select Continue In and then select Background

     

   • If you're using the Plan agent, select the Start Implementation dropdown and the select Continue in Background to run the implementation in a background agent session

     

   • Type @cli in the chat input to hand off the task to a background agent

The background agent session starts automatically, carrying over the full conversation history and context. You can monitor the background agent's progress in the Chat view.

Create an isolated background agent session (Experimental)

To isolate background agent changes from your main workspace, you can create a background agent session that uses a Git worktree. When you create a worktree, VS Code creates a separate folder for the session. The background agent operates in this isolated folder, to prevent conflicts with your active work.

To use Git worktrees in a background agent session:

1. Start a new Copilot CLI background agent session in VS Code.

2. In the chat input box, select Worktree for the isolation mode.

   

   When you select Workspace, the background agent applies changes directly to your main workspace.

3. Enter a prompt to start the agent session. VS Code automatically creates a new Git worktree.

   All changes made by the background agent are applied to the worktree folder, isolating them from your main workspace.

4. In Source Control view, in the Repositories view, you can view the Git worktree

   

   The Agents view also shows the worktree path for the background agent session.

5. Monitor the background agent's progress in the Agents view

6. After the background agent completes the task, you can review and merge the changes from the worktree back into your main workspace.

   Tip

   Before merging the changes, you can directly apply them from the worktree to your main branch by using the Apply Changes button in the chat editor.

Learn more about using Git worktrees in VS Code source control.

Use custom agents with background agents (Experimental)

Custom agents let you define custom personas and roles for agents in VS Code. For example, you might create a custom agent for performing code reviews. Custom agents can define specific instructions and behaviors.

When you create a background agent session, you can select a custom agent to handle the task. The background agent operates according to the custom agent's defined behavior.

To enable custom agents with background agents:

1. Enable custom agents for background agents with the github.copilot.chat.cli.customAgents.enabled setting

2. Create a custom agent in your workspace with the Chat: New Custom Agent command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P))

   Note

   Currently, only custom agents defined in the workspace are available for background agent sessions. Learn more about creating a custom agent.

3. Create a new background agent session and select the custom agent from the Agents dropdown

   

4. Enter a prompt and notice that the custom agent is used to handle the task

Related resources

• Agents overview: Understand different agent types and how to hand off tasks between agents
• Cloud agents: Learn about cloud agents for tasks requiring GitHub integration
• Custom agents: Create custom agent roles and personas
• GitHub Copilot CLI documentation