Manage agent sessions in VS Code

A session is the unit of work with an agent in Visual Studio Code. It brings together the workspace, code changes, and one or more chats for a task. Each chat has its own conversation history and context. This article describes how to manage these conversations and organize sessions across the Chat view and the Agents window.

Start an agent session

Start a new session when you begin an independent task or need a different workspace or configuration. For a fresh conversation that shares an existing session's workspace and code changes, start another chat in that session, where supported.

Choose the surface that matches your workflow:

• Use the Chat view for a workspace-scoped, code-first session beside the editor.
• Use the Agents window to start and monitor sessions across workspaces, attach related projects or GitHub items, or start from an existing pull request. On Windows, you can also launch the Agents window directly by right-clicking the VS Code application icon in the taskbar and selecting Agents Window.

The surfaces share the same underlying sessions, so you can switch between them after you start. To compare all agent interfaces, see Ways to work with agents. To send and steer requests after a session starts, see Use chat in VS Code.

Manage session context

The context window control in the chat input shows how much of the model's context window the active chat is using. Hover over the control to see the token count, a usage breakdown by category, and the total AI credits consumed by the session.

As the conversation grows, the control updates to reflect increasing context usage. The available context depends on the selected model.

How context changes across turns also affects prompt caching. Stable context lets the model provider reuse tokens from earlier requests, which lowers cost and latency. Use the Cache Explorer to check your cache hit rate.

Compact conversation context

Context compaction summarizes earlier conversation history to free space in the context window. Compaction lets you continue the same chat with less irrelevant history and reduces the tokens sent with subsequent requests.

VS Code automatically compacts the conversation when the context window fills. To turn off automatic compaction, set github.copilot.chat.summarizeAgentConversationHistory.enabled Open in VS Code Open in VS Code Insiders to false.

To compact the conversation manually:

• Type /compact in the chat input. Optionally, add instructions for what the summary should retain, for example /compact focus on the database schema decisions.
• Select the context window control, and then select Compact Conversation.

Manual compaction is available for local, background, and Claude agent sessions. To reset the context entirely, start a new session.

Learn more about AI credit consumption.

Run multiple chats in a session

In a supported Agent Host session, use multiple chats to work on related tasks without interrupting an ongoing conversation. The session has a main chat and can contain additional interactive peer chats. Each chat has its own conversation history, title, and agent or language model selection, but all chats share the session's workspace and worktree.

A new chat starts blank and doesn't inherit the history of the other chats. To retain the source conversation's history, fork the conversation instead. Learn more about choosing a chat, a fork, or a new session.

To practice separating and monitoring independent work, follow Delegate two tasks without mixing their changes.

Ask side questions

Use a side chat to ask a question about the current conversation without adding the question or response to the main chat. A side chat opens in a group beside the source chat, so both conversations remain visible. It privately inherits the source conversation as context. Side chats favor explanation over action unless you ask the agent to make changes or perform a task.

Start a side chat in one of these ways:

• Type /btw <question> in the chat input. The side chat branches from the latest turn, including a response that is still in progress.
• Select text in a chat response, enter a question in the Ask Question input, and press Enter. The selected text and its response become context for the side chat.

Each question creates a new side chat. The side chat inherits the agent and language model from the source chat, but inherited messages remain hidden from its transcript.

Sessions list

The sessions list is your central hub for managing all your chat sessions, regardless of where you started them or where they are running. The sessions list shows your sessions with information about their status, type, and file changes.

Hover over a session to see actions for pinning or archiving it. Right-click a session in the list to see additional actions like deleting or changing the session's state. Some actions are specific to the session's harness and state. For example, you can check out a pull request for a cloud session.

Use the pinning action to keep important sessions easily accessible at the top of your list. Pinned sessions stay at the top of the list regardless of their activity or state, so you can quickly find and return to them.

View sessions from other applications

VS Code can discover local agent sessions created by supported applications outside VS Code. You can open and continue sessions from Copilot CLI, the GitHub Copilot app, Claude Code, and Codex in the Chat view or Agents window.

For Copilot sessions, discovery includes sessions that are associated with a repository and were updated within the last seven days.

By default, sessions created in other applications are hidden. To control which sessions appear, open the sessions list filter, select External, and choose one of these options:

• None: hide all external sessions.
• Recent: show the two most recently updated external sessions from the last seven days.
• Last 24 Hours: show external sessions updated within the last 24 hours.
• Last 7 Days: show external sessions updated within the last seven days.
• All: show all discovered external sessions.

The filter applies to the sessions lists in both the Chat view and Agents window. You can also configure it with the chat.agentSessions.showExternal Open in VS Code Open in VS Code Insiders setting.

When you open an external session in the Agents window, a one-time banner indicates that the session was created in another application. You can choose which external sessions to show from the banner. If your choice hides the open session, VS Code asks you to confirm the change.

When you open an external Codex session, only one application can write to the chat at a time. If the chat is still open in ChatGPT or Codex CLI, VS Code keeps the transcript, draft, and attachments available, but disables sending, queueing, and resending. The This chat is open in another app banner appears above the chat input.

To continue the chat in VS Code, fully quit the other application, and then select Retry in the banner. Retrying checks whether the chat is available without sending the draft or adding a transcript entry. After the banner disappears, send the draft yourself.

When you send a message in an external session, the Agent Host adopts it. The session is no longer external, so the External filter no longer affects its visibility.

Archive sessions

To keep the sessions list organized, archive or mark sessions as done when they're completed or you no longer need them. Archiving a session does not delete it. At any time, you can unarchive a session to restore it to the active sessions list.

When you archive (or mark as done) a session, its status changes so it moves out of the active sessions list. For a worktree session, VS Code commits uncommitted changes to the session branch before it removes the worktree folder. If VS Code can't preserve the changes or remove the worktree, the worktree remains. The branch and its commits are preserved, so restoring the session re-creates the worktree from that branch.

For a Dev Container session, marking a session as done removes the container without waiting for the idle shutdown period, but only when no other session or unsent draft uses it. Restoring the session starts a replacement container and preserves the conversation history.

To archive a session, hover over the session in the sessions list and select the Archive (Chat view) or Mark as Done (Agents window) option.

To view your archived sessions, use the filter options in the sessions list and select the Archived (Chat view) or Done (Agents window) filter.

Mark an individual chat as done

In the Agents window, you can mark an additional chat within an Agent Host session as done without affecting the main chat, other chats, or the owning session:

1. Expand the owning session in the sessions list.

2. Right-click the chat, and then select Mark as Done.

Marking a chat as done hides it from the active sessions list and closes its tab, but does not delete it. The chat remains done after you reload the window, and its title and transcript are preserved.

To find a done chat, select the Done filter in the global sessions list. Alternatively, right-click the owning session and select Show Done Chats to show its done chats beneath it. Right-click the done chat and select Restore. The chat becomes active and usable again, with its title and transcript intact, so you can continue sending messages.

You can't mark the main chat, side chats, or subagent chats as done independently.

Delete sessions

To permanently delete a session, right-click the session in the sessions list and select Delete. Deleting a session removes it permanently and can't be undone. For Copilot sessions, deleting the session also removes any associated worktrees created for that session.

If multiple Copilot sessions share the same worktree, such as after you fork a session, deleting one session does not remove the shared worktree while another session still uses it. The worktree is removed only after the last linked session is deleted or archived.

For a Dev Container session, deleting the session removes the container only when no other session or unsent draft uses it. This cleanup also applies when automatic idle shutdown is turned off.

Automatically clean up merged sessions

Configure automatic cleanup to keep inactive Agent Host sessions from accumulating after their pull requests merge. Both settings are disabled by default:

• chat.agentSessions.autoMarkAsDoneMergedSessionsAfterDays Open in VS Code Open in VS Code Insiders controls how many inactive days pass before an eligible session is automatically marked as done.
• chat.agentSessions.autoDeleteArchivedMergedSessionsAfterDays Open in VS Code Open in VS Code Insiders controls the separate grace period between automatically marking an eligible session as done and permanently deleting it.

Set each setting to a positive whole number of days. The recommended value is 15. Set a setting to 0 to disable that part of the cleanup lifecycle.

A session is eligible when it isn't in progress, its last-modified time exceeds the configured threshold, it has at least one merged pull request, and none of its related pull requests are open. External sessions aren't eligible. VS Code checks for eligible sessions when it starts and every hour while either setting is enabled.

Permanent deletion applies only to sessions that VS Code automatically marked as done. Sessions that you mark as done manually aren't deleted automatically. Restoring an automatically completed session clears its deletion eligibility.

When cleanup marks a session as done or deletes it, VS Code removes the session worktree only when the branch tracks an upstream and has no outgoing commits or uncommitted changes. If Git state is unknown or the worktree doesn't meet these conditions, the worktree is retained. Cleanup never force-removes a worktree.

When a merged pull request makes a session eligible, select Configure Automatic Cleanup from the Mark as Done suggestion to open both settings without enabling them.

Fork a chat session

Forking a chat session branches off the conversation and inherits the conversation history from the original session. In single-chat sessions and sessions that don't use an agent host, the fork opens as a new independent session. The conversation is separate, but its code changes are isolated only if the fork uses a different folder or worktree. The new session title is prefixed with "Forked:" to help you identify it.

For multi-chat Copilot sessions in the Agents window, the fork opens as a peer chat in the same session. The peer chat gets an automatically generated title and runs independently from sibling chats.

For Copilot sessions that use worktree isolation, the fork continues to use the same worktree as the original session.

Forking is useful when you want to explore an alternative approach, ask a side question, or branch a long conversation in a different direction without losing the original context.

There are two ways to fork a chat session:

• Fork the entire session: type /fork in the chat input box and press Enter. The fork opens with the full conversation history copied from the current session.

• Fork from a checkpoint: hover over a chat request in the conversation and select the Fork Conversation button. The fork includes only the requests up to and including that checkpoint.

  

Orchestrate sessions from agent host sessions

In agent host sessions, such as Copilot and Claude, agents can use built-in session-management tools to coordinate work across multiple sessions and chats. These tools are also available for Codex sessions when Codex runs on the Agent Host.

With these tools, an agent can:

• List your sessions and inspect metadata like status, workspace, and file changes.
• Create a new session for a sub-task, or create a new chat in an existing session.
• Read recent conversation context from another session before continuing work.
• Send a message to another session or chat to start or steer a follow-up task.

Choose the session relationship first, and then choose the workspace and code isolation:

• Related work: Use currentSession to create a peer chat in the current session. The peer chat shares the current workspace and checkout, so use this option for related research, planning, or other work that doesn't need isolated file changes.
• Unrelated work or a separate deliverable: Use independent to create a separate session. Omit the workspace when the task doesn't need repository files. If it does, choose a trusted folder or worktree. Request a new worktree when file changes must be isolated from your current checkout.

In your prompt, state both the session relationship and the workspace choice. For related, read-only work that needs the current repository context:

Create a peer chat in this session that reuses the current workspace and checkout to review the authentication flow. Do not modify files.

For unrelated work that doesn't need repository files:

Create an independent session with no workspace to research licensing options for a separate project.

When the task needs repository files, you can refer to a workspace by its project name instead of providing an absolute path or workspace URI. For example:

Create an independent session in the vscode workspace with a new worktree to implement and test the authentication change.

If multiple workspaces have the same project name, the agent reports the possible matches instead of choosing one. Session-management tools also support remote workspace URIs and preserve the project URI and working directories for multi-root workspaces.

When a tool creates or targets a session, VS Code shows an Open Session pill in chat so you can jump directly to it.

To keep this workflow safe and predictable:

• Sending a message to another session always requires your confirmation.
• Agents cannot send messages to the same chat they are currently running in.
• Burst sends are capped to avoid unbounded fan-out.
• Archived sessions are excluded from listings unless explicitly requested.

chat.agentHost.agentOrchestrationLimits Open in VS Code Open in VS Code Insiders controls the process-wide limits for sessions and chats that agents create, messages they send, and recursive session creation. The default on value enforces limits that support coordination-heavy workflows. Set it to off to remove the limits. Changes apply without restarting the Agent Host, and reaching a limit doesn't interrupt work that is already running.

Removing orchestration limits doesn't change confirmation requirements or input validation. The safety guidance in this section continues to apply.

Save and export chat sessions

You can save chat sessions to preserve important conversations or reuse them later for similar tasks.

Export a chat session as a JSON file

You can export a chat session to save it for later reference or share it with others. Exporting a chat session creates a JSON file that contains all prompts and responses from the session.

To export a chat session:

1. Open the chat session you want to export in the Chat view.

2. Run the Chat: Export Chat... command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

3. Choose a location to save the JSON file.

Copy chat messages as Markdown

The Chat view supports different options for copying chat messages as Markdown to the clipboard, available through the context menu when you right-click a message or the chat background.

• Copy: Copy an individual prompt or response to the clipboard - the Markdown contains the response text, thinking steps, and tool calls.

• Copy All: Copy the entire chat session in Markdown format, including all prompts, responses, thinking steps, and tool calls.

• Copy Final Response: Copy just the final Markdown section of the agent's response, after the last tool call. This is useful for sharing or reusing the final output without the intermediate steps.

Monitor sessions from the application icon (Preview)

The application icon can show how many unarchived sessions in the Agents window need your attention. The badge appears on the dock icon on macOS, the launcher icon on Linux, or the taskbar icon on Windows.

The badge counts sessions that:

• Have unread results and are no longer in progress.
• Are waiting for your input.
• Have failing CI checks on an open, non-draft pull request and are no longer in progress.

Unread sessions that are still in progress aren't included. The count updates as sessions change state. Reading or archiving a session removes it from the count when it no longer needs your attention.

Use the sessions.showApplicationBadge Open in VS Code Open in VS Code Insiders setting to control the application badge. The setting defaults to true in Insiders and false in Stable.

Session status indicator (Experimental)

The session status indicator provides quick access to your sessions directly from the command center in the title bar. The indicator displays visual badges for unread messages and in-progress sessions, so you can stay informed about AI activity without switching views.

The indicator shows:

• Unread sessions badge: shows the count of chat sessions with new messages. Select the badge to filter the sessions list to show only unread sessions.
• In-progress sessions badge: shows the count of sessions with running agents. Select the badge to filter the sessions list to show only in-progress sessions.
• Sparkle icon: provides quick access to chat and session management options.

You can configure the status indicator's visibility by using the chat.agentsControl.enabled Open in VS Code Open in VS Code Insiders setting.

View sessions on the VS Code welcome page

The VS Code welcome page can act as your startup experience for working with chat sessions. It provides quick access to your recent chat sessions, an embedded chat widget for starting new tasks, and quick actions for common tasks.

To configure the VS Code welcome page as your startup experience, set workbench.startupEditor Open in VS Code Open in VS Code Insiders to agentSessionsWelcomePage.

Related resources

• Use chat in VS Code
• Agents overview
• Add context to chat
• Best practices for using AI