Choose and use an agent harness

An agent harness coordinates an agent session, including tool calls, context, and code changes. In Visual Studio Code, you choose an agent harness and where it runs with the Session Target control. This article helps you choose a harness and covers the capabilities that are specific to Local, Copilot, Claude, Codex, and cloud sessions.

For the relationship between harnesses, language models, agent roles, and execution environments, see Agent harnesses.

Compare agent harnesses

Most harnesses share the same chat and session-management experience in VS Code. Your choice primarily affects where the agent runs, which tools and models it can use, and how it applies code changes.

Session target	Where it runs	Code access	Choose it for
Local	In the VS Code extension host on your machine	Current workspace	Interactive work that needs VS Code tools, extension tools, or any model configured in VS Code
Copilot	On the Agent Host on your machine	Current folder or an isolated Git worktree	General coding tasks with the Copilot SDK and Copilot-specific capabilities
Claude	On your machine	Current folder or an isolated Git worktree	Anthropic's agent capabilities, slash commands, and permission modes
Codex	On your machine	Current folder or an isolated Git worktree	OpenAI's Codex capabilities for interactive or background work
Cloud	On the provider's remote infrastructure	A GitHub repository and pull request	Well-scoped tasks that can run independently and benefit from team review

Select an agent harness

You can select an agent harness when you start a new session in the Chat view or the Agents window. When you change the agent harness for an ongoing session, VS Code considers this a handoff and carries the conversation history and context to the new harness.

To select an agent harness:

Open the Chat view (⌃⌘I (Windows, Linux Ctrl+Alt+I)) or Agents window
Select New Chat (+)
Open the Session Target control and choose from the available agent harnesses.
Depending on the selected harness, other options for language model, isolation mode, or custom agents are available.

Learn more about creating and managing sessions.

Choose code isolation

Agent sessions that run on your machine (local, Copilot, Claude, and Codex) can make changes directly to your codebase or in an isolated Git worktree. You can choose the isolation mode when you start a new session in the Chat view or the Agents window.

Copilot, Claude, and Codex sessions that run on your machine can work in your current folder or a new Git worktree.

Choice	Where changes go	Choose it for	Considerations
New Worktree	A new branch and worktree	Parallel tasks that should not modify your active workspace	Starts from committed Git state and requires you to integrate the result
Folder	Your current folder	Small, interactive tasks that should use your current files and uncommitted changes	Agent edits appear immediately in your active workspace

When you start a session in the Agents window, select New Worktree and choose the base branch to isolate the session. If you leave New Worktree unselected, the agent works directly on the code in the workspace. Sessions that you start in the Chat view always use the current workspace.

Screenshot of the New Worktree checkbox and base branch control in the Agents window.

Worktree isolation requires a Git repository with at least one commit. A new worktree contains the committed files from the selected base branch. It does not automatically contain uncommitted tracked changes or untracked files from your primary worktree. Commit changes that the agent needs, or use folder isolation when the task depends on your current uncommitted state.

Git-ignored files, such as .env files and installed dependencies, are also absent by default. Use git.worktreeIncludeFiles Open in VS Code Open in VS Code Insiders to specify ignored files and folders that VS Code should copy into new worktrees. Learn more about including files in a worktree.

Worktree sessions use Bypass Approvals because their code changes are separate from your active workspace. Folder sessions offer the permission levels supported by the selected harness. Worktree isolation does not restrict commands, network access, or access outside the worktree. For those protections, configure agent sandboxing.

Use an agent harness

The Local harness runs interactively in the VS Code extension host and works directly in your current workspace. It can use VS Code built-in tools, extension-provided tools, MCP servers, and the models configured in VS Code, including bring your own key models.

Choose Local for interactive tasks that need immediate feedback or access to editor context, such as diagnostics, test results, terminal output, or selections.

Choose a built-in agent role

Local sessions provide these built-in agent roles:

Agent: autonomously plans and performs complex coding tasks, edits files, runs commands, and iterates on results.
Plan: researches a task and creates a structured implementation plan before code changes. Learn more about planning with agents.

You can switch roles during a session from the agent picker. For specialized workflows, create a custom agent.

The Copilot harness is powered by the Copilot SDK and runs on the Agent Host. The Agent Host owns the session independently of the windows that display it, so a session can continue in the background, appear in multiple windows, and contain multiple chats.

Copilot sessions use the same GitHub authentication context as chat in VS Code. If you use a GitHub Enterprise account for Copilot, the session uses that account. For managed user accounts on GHE.com, complete the setup in Using GitHub Copilot with an account on GHE.com.

Copilot supports slash commands for common session operations. Enter / in the chat input to view available commands. For example, use /compact to reduce conversation context, /research to start deep research, or /yolo and /autoApprove to control automatic tool approval.

Permissions and approvals

The available permission levels depend on the isolation mode:

Worktree: the permission level is Bypass Approvals and can't be changed.
Folder: select Default Approvals or Bypass Approvals from the permissions picker. To also use Assisted permissions, turn on chat.assistedPermissions.enabled Open in VS Code Open in VS Code Insiders .

Because Copilot sessions run on the Agent Host, Autopilot is an agent mode rather than a permission level.

Remote control Copilot sessions

Use "/remote on" to monitor and steer a running Copilot session from GitHub.com or the GitHub Mobile app. Session history, tool activity, status, approvals, and questions stay synchronized between VS Code and GitHub.

To use remote control:

Start or resume a Copilot session.
Enter "/remote on" in the chat input.
Select Open on GitHub or scan the QR code to open the session on another device.

Run "/remote" to check the current status, or enter "/remote off" to stop sharing the session with GitHub.

Remote control requires GitHub authentication and a workspace that maps to a GitHub repository. To turn off remote control support in VS Code, turn off github.copilot.chat.cli.remote.enabled Open in VS Code Open in VS Code Insiders .

Use custom agents with Copilot

To use a custom agent in a Copilot session:

Create a workspace custom agent by running Chat: New Custom Agent from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
Start a Copilot session and select the custom agent from the agent picker.

Only custom agents defined in the workspace are currently available to Copilot sessions.

Run deep research with the research agent

Note

The research agent is in preview and is available only in Copilot sessions in VS Code Insiders.

The research agent investigates a topic and produces a detailed Markdown report with citations. It has read-only access and gathers information from your codebase, relevant GitHub repositories, and the web.

Enter /research followed by a topic:

/research How does the authentication flow work in this codebase?

For research that feeds into an implementation plan, use the Plan agent. For focused research that returns results to the current conversation, use subagents.

Learn more about researching with GitHub Copilot CLI.

Copilot harness limitations

Copilot sessions don't have access to every VS Code built-in or extension-provided tool. They use the models available to the Copilot harness and can currently access only local MCP servers that don't require authentication.

Claude sessions use Anthropic's Claude Agent SDK and can run autonomously on your workspace. VS Code integrates the harness through its SDK while keeping session management, chat, and code review in VS Code. Claude can use your GitHub Copilot subscription for authentication and billing. Turn support on or off with github.copilot.chat.claudeAgent.enabled Open in VS Code Open in VS Code Insiders This setting can be managed by your organization. Contact your administrator to change it..

Claude provides provider-specific slash commands. Enter / in the chat input to view the commands available in your session.

Slash command	Description
`/agents`	Create and manage specialized Claude agents.
`/hooks`	Configure scripts that run at key points in the session lifecycle.
`/memory`	Open and edit `CLAUDE.md` memory files.
`/init`	Create a `CLAUDE.md` memory file for the project.
`/pr-comments`	Get comments from a pull request.
`/review`	Review changes in a pull request.
`/security-review`	Review pending changes for security issues.

Claude supports these permission modes:

Edit automatically: apply changes without asking for approval.
Request approval: ask before applying changes.
Plan: outline the approach before implementation.

Caution

The github.copilot.chat.claudeAgent.allowDangerouslySkipPermissions Open in VS Code Open in VS Code Insiders setting bypasses all permission checks. Use it only in an isolated sandbox environment without internet access.

Learn more about Claude subagents and Claude hooks.

Cloud sessions run on remote infrastructure and work with a GitHub repository. The agent implements the task on a branch and opens a pull request for review. Choose Cloud for well-scoped tasks that can run without access to your local editor context, terminal output, or extension-provided tools.

VS Code supports:

GitHub Copilot cloud agent for implementing features, addressing review feedback, and creating pull requests.
Claude and Codex cloud agents for provider-specific capabilities. Third-party cloud agents are currently in preview.

To use Claude or Codex in the cloud, turn on support in your Copilot account settings. See Managing policies for third-party coding agents. You don't need the provider's VS Code extension for a cloud session.

Start a cloud session

Open the Chat view and select New Chat.
Select Cloud from the Session Target control.
Choose the cloud provider and, when available, a custom agent and model.
Enter a prompt and submit it.

The session runs remotely and appears in the sessions list. Sessions that you create by assigning an issue or pull request to a cloud agent on GitHub.com also appear in VS Code.

You can also select a GitHub repository when you start a session in the Agents window, or hand off an existing session to a cloud harness. In a Copilot session, enter /delegate to continue the task in the cloud.

Cloud sessions use the tools, MCP servers, and models configured by the cloud service. They can't access VS Code built-in tools or local runtime context.

Use Copilot CLI from the terminal

VS Code includes a GitHub Copilot CLI terminal profile. Open it from the Terminal profile dropdown, run Chat: New Copilot CLI Session from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)), or enter copilot in an integrated terminal.

When you start a Copilot CLI session in the terminal, VS Code detects it and adds it to the sessions list. Right-click an existing Copilot session and select Resume in Terminal to continue it from the terminal.

Hand off a session

Handoff changes the target for an ongoing session and carries the conversation history and context to the new target. Use handoff when another harness or execution environment is a better fit for the next part of the task.

For example, continue a Copilot session with Claude or Codex to use provider-specific capabilities, send a well-scoped task to a cloud harness for a pull request workflow, or move from the Plan agent to an implementation agent.

To hand off an ongoing session:

Open the session.
In the chat input, open the Session Target dropdown.
Select the target that should continue the work, such as Copilot, Claude, Codex, or Cloud.

VS Code carries the conversation history and context to the selected target. The tools, permissions, and models might change because each target provides different capabilities.

Tip

In Copilot CLI, enter /delegate to continue the work with a cloud agent.

Hand off a plan to implementation

The Plan agent focuses on researching a task and creating a plan without changing code. After you review the plan:

Select Start Implementation.
Choose an available implementation agent.

The implementation agent receives the plan and conversation context and starts implementing it.

Action	What it does
Hand off	Changes the session target and carries the conversation history and context to the new target.
Fork a session	Creates an independent session from a point in the conversation. Learn more about forking sessions.
Switch surfaces	Opens the same session in the Chat view or Agents window without changing its target or context.

For background on how handoff works, see Sessions and handoff.

Related resources

7/31/2026