Understand sessions and chats
A session is the unit of work with an agent in Visual Studio Code. It brings together the workspace and code changes for a task. A chat is a conversation within that session, and a session can contain multiple chats when the harness supports them.
This article helps you choose between starting a new chat, forking a conversation, and creating a new session. It explains what chats share, how to finish individual conversations, and how to continue work across surfaces or hand it off to another agent.
To create and organize sessions, see Manage agent sessions.
What is a session?
A session contains one or more chats. Each chat records your prompts, the agent's responses, the tool calls it makes, and the context it accumulates along the way. Its conversation history contributes to the language model's context window and isn't automatically shared with other chats or sessions.
Use a session to organize related conversations, follow their progress, and review their combined results.
The session's execution environment determines where it works on code. An Agent Host session can use a workspace on your machine, a connected host, or inside a Dev Container on either host, depending on the available harness. A container changes the development environment, not how the session organizes the conversation and task.
Chats within a session
A session can contain more than one chat. Each chat is an independent conversation with its own history, title, status, and agent or model selection, but all chats in a session share the same workspace and code isolation. A new chat starts blank and doesn't inherit the conversation history of the other chats in the session.
The session has a main chat. Additional interactive conversations are called peer chats. You can prompt each peer chat independently. This differs from a subagent, which an agent starts to perform delegated work.
Running several chats in one session lets you work on related tasks against the same codebase at the same time without switching sessions. This capability runs on the Agent Host and is available for harnesses that support it, such as Copilot and Claude. Learn how to run multiple chats in a session.
For example, you're adding a sign-in form. Use one chat to build the form and another chat in the same session to write tests. The test-writing chat can read the implementation files once they're saved, but it doesn't inherit the first chat's conversation. Include requirements such as rejecting an empty email address in the second chat's prompt, rather than relying on your earlier discussion.
Both chats can edit the same files. When you need separate working directories, use separate sessions with worktree isolation, where available.
Choose a new chat, a fork, or a new session
Continue in the same chat when you're working on the same task and its conversation history is still relevant. When you need a separate conversation, choose based on whether you want to retain that history and share the same workspace.
| Choose | When to use it | Conversation history | Workspace and code changes |
|---|---|---|---|
| New chat in the same session | Work on a related task with a fresh conversation, such as writing tests for the feature another chat is implementing. | Starts without the other chats' history. | Shares the session's workspace and worktree. |
| Fork a conversation | Explore an alternative approach while retaining the requirements and discussion so far. | Inherits the source conversation up to the fork point. The original conversation remains available. | Can share the original session and worktree. Forking doesn't guarantee separate code changes. |
| New session | Start an unrelated task, work in another project, or choose a separate execution environment or worktree. | Starts without the previous chat's history. | Uses the folder or worktree selected for the new session. |
A fork can open as another chat in the same session or as a new session, depending on the harness. Forking a conversation isn't the same as creating a Git branch or a separate worktree. For example, a fork of a Copilot worktree session continues to use the original worktree.
Separate conversations don't guarantee separate files. If two chats or sessions use the same folder or worktree, their edits affect the same files. Use separate sessions with worktree isolation, where available, when changes must stay separate.
Sessions can run in parallel and keep running when you switch between them. To return an existing conversation and affected workspace files to an earlier point instead of branching the conversation, see Restore a checkpoint.
Sessions across surfaces
You can continue a supported Agent Host session in the Chat view or the Agents window. Switching windows doesn't create a session, fork the conversation, or change its harness, workspace, or worktree.
Both interfaces provide access to the session's main chat and interactive peer chats, but their navigation and management controls differ. For the steps in each interface, see Run multiple chats in a session.
VS Code can also discover supported local sessions created in Copilot CLI, the GitHub Copilot app, Claude Code, and Codex. A discovered session is external until you send a message from VS Code. The Agent Host then adopts the session, and the external-session filter no longer controls whether it appears. Learn how to view sessions from other applications.
On the Agent Host, an agent can also coordinate work across sessions. It can list sessions, create new sessions or chats, read another session's recent context, and send follow-up messages between sessions.
Hand off a session
Handoff continues ongoing work with a different agent configuration and carries the full conversation history and context with it. A handoff can change the harness, execution environment, or agent role. Use handoff when another configuration is a better fit for the next part of the task.
Common handoffs include:
- Harness to harness: continue a Copilot session with Claude or Codex to use provider-specific capabilities.
- Plan to implementation: use the Plan agent to produce a reviewed plan, then hand off to an implementation agent.
- Continue in the cloud: hand off a well-scoped task to the Cloud target for remote execution and a pull request workflow.
Learn how to hand off an ongoing session.
Remote and synced sessions
A session doesn't have to run on your local machine, and it doesn't have to stay on one device:
- Remote sessions run on a machine other than the one you work from. You can connect the Agents window to a remote host over SSH or a dev tunnel, or use Copilot remote control (
/remote on) to monitor and steer a running Copilot session from GitHub. Learn more about connecting to a remote machine and remote control for Copilot sessions. - Synced sessions are backed up to your GitHub account so you can access them across devices. Learn more about syncing sessions.
- Session insights let you query your session history to review what you worked on. Learn more about session insights.
Close a chat or finish work
Closing, marking done, and deleting serve different purposes:
- Close a chat tab: hide the chat from the chat area without deleting its conversation. You can reopen it later.
- Mark a chat as done: remove a completed conversation from the active sessions list while retaining its title and history. Restore it when you want to continue.
- Delete a chat: permanently remove the conversation. Unlike closing or marking done, deletion can't be undone.
In the Agents window, supported additional chats can be marked as done independently. This doesn't mark the main chat, other chats, or the owning session as done. Main chats, side chats, and subagent chats don't support being marked as done independently.
For the steps and available actions, see Manage chats within a session and Mark an individual chat as done.