When working on the Agent Sessions window (
src/vs/sessions/
), always follow these guidelines:
1. Read the Specification Documents First
The
src/vs/sessions/
directory contains authoritative specification documents.
Always read the relevant spec before making changes.
Document
Path
Covers
Layer spec
src/vs/sessions/README.md
Layering rules, dependency constraints, folder conventions
Layout spec
src/vs/sessions/LAYOUT.md
Grid structure, part positions, sizing, CSS classes, API reference
AI Customizations
src/vs/sessions/AI_CUSTOMIZATIONS.md
AI customization editor and tree view design
Chat Widget
src/vs/sessions/browser/widget/AGENTS_CHAT_WIDGET.md
Chat widget wrapper architecture, deferred session creation, option delivery
If you modify the implementation, you
must
update the corresponding spec to keep it in sync. Update the Revision History table at the bottom of
LAYOUT.md
with a dated entry.
2. Architecture Overview
2.1 Layering
vs/base ← Foundation utilities
vs/platform ← Platform services
vs/editor ← Text editor core
vs/workbench ← Standard VS Code workbench
vs/sessions ← Agent Sessions window (this layer)
Key constraint:
vs/sessions
may import from
vs/workbench
and all layers below it.
vs/workbench
must
never
import from
vs/sessions
.
2.2 Dependency Rules
✅ Import from
vs/base
,
vs/platform
,
vs/editor
,
vs/workbench
✅ Import within
vs/sessions
(internal)
❌ Never import
vs/sessions
from
vs/workbench
Run
npm run valid-layers-check
to verify layering
2.3 How It Differs from VS Code
Aspect
VS Code Workbench
Agent Sessions Window
Layout
Configurable part positions
Fixed layout, no settings customization
Chrome
Activity bar, status bar, banner
Simplified — none of these
Primary UX
Editor-centric
Chat-first (Chat Bar is a primary part)
Editors
In the grid layout
Modal overlay above the workbench
Titlebar
Menubar, editor actions, layout controls
Session picker, run script, toggle sidebar/panel
Navigation
Activity bar with viewlets
Sidebar (views) + sidebar footer (account)
Entry point
vs/workbench
workbench class
vs/sessions/browser/workbench.ts
Workbench
class
3. Folder Structure
src/vs/sessions/
├── README.md # Layer specification (read first)
├── LAYOUT.md # Authoritative layout specification
├── AI_CUSTOMIZATIONS.md # AI customization design document
├── sessions.common.main.ts # Common (browser + desktop) entry point
├── sessions.desktop.main.ts # Desktop entry point (imports all contributions)
├── common/ # Shared types, context keys, and theme
│ ├── categories.ts # Command categories
│ ├── contextkeys.ts # ChatBar and welcome context keys
│ └── theme.ts # Theme contributions
├── browser/ # Core workbench implementation
│ ├── workbench.ts # Main Workbench class (implements IWorkbenchLayoutService)
│ ├── menus.ts # Agent sessions menu IDs (Menus export)
│ ├── layoutActions.ts # Layout toggle actions (sidebar, panel, auxiliary bar)
│ ├── paneCompositePartService.ts # AgenticPaneCompositePartService
│ ├── widget/ # Agent sessions chat widget
│ │ └── AGENTS_CHAT_WIDGET.md # Chat widget architecture doc
│ ├── parts/ # Workbench part implementations
│ │ ├── parts.ts # AgenticParts enum
│ │ ├── titlebarPart.ts # Titlebar (3-section toolbar layout)
│ │ ├── sidebarPart.ts # Sidebar (with footer for account widget)
│ │ ├── chatBarPart.ts # Chat Bar (primary chat surface)
│ │ ├── auxiliaryBarPart.ts # Auxiliary Bar
│ │ ├── panelPart.ts # Panel (terminal, output, etc.)
│ │ ├── projectBarPart.ts # Project bar (folder entries)
│ │ └── media/ # Part CSS files
│ └── media/ # Layout-specific styles
├── electron-browser/ # Desktop-specific entry points
│ ├── sessions.main.ts # Desktop main bootstrap
│ ├── sessions.ts # Electron process entry
│ ├── sessions.html # Production HTML shell
│ ├── sessions-dev.html # Development HTML shell
│ ├── titleService.ts # Desktop title service override
│ └── parts/
│ └── titlebarPart.ts # Desktop titlebar part
├── services/ # Service overrides
│ ├── configuration/browser/ # Configuration service overrides
│ └── workspace/browser/ # Workspace service overrides
├── test/ # Unit tests
│ └── browser/
│ └── layoutActions.test.ts
└── contrib/ # Feature contributions
├── accountMenu/browser/ # Account widget for sidebar footer
├── agentFeedback/browser/ # Agent feedback attachments, overlays, hover
├── aiCustomizationTreeView/browser/ # AI customization tree view sidebar
├── applyToParentRepo/browser/ # Apply changes to parent repo
├── changesView/browser/ # File changes view
├── chat/browser/ # Chat actions (run script, branch, prompts)
├── configuration/browser/ # Configuration overrides
├── files/browser/ # File-related contributions
├── fileTreeView/browser/ # File tree view (filesystem provider)
├── gitSync/browser/ # Git sync contributions
├── logs/browser/ # Log contributions
├── sessions/browser/ # Sessions view, title bar widget, active session service
├── terminal/browser/ # Terminal contributions
├── welcome/browser/ # Welcome view contribution
└── workspace/browser/ # Workspace contributions
4. Layout
Use the
agent-sessions-layout
skill for detailed guidance on the layout. Key points:
4.1 Visual Layout
┌─────────┬───────────────────────────────────────────────────────┐
│ │ Titlebar │
│ ├────────────────────────────────────┬──────────────────┤
│ Sidebar │ Chat Bar │ Auxiliary Bar │
│ ├────────────────────────────────────┴──────────────────┤
│ │ Panel │
└─────────┴───────────────────────────────────────────────────────┘
Sidebar
spans full window height (root grid level)
Titlebar
is inside the right section
Chat Bar
is the primary interaction surface
Panel
is hidden by default (terminal, output, etc.)
Editor
appears as a
modal overlay
, not in the grid
4.2 Parts
Part
Default Visibility
Notes
Titlebar
Always visible
3-section toolbar (left/center/right)
Sidebar
Visible
Sessions view, AI customization tree
Chat Bar
Visible
Primary chat widget
Auxiliary Bar
Visible
Changes view, etc.
Panel
Hidden
Terminal, output
Editor
Hidden
Main part hidden; editors open via
MODAL_GROUP
into
ModalEditorPart
Not included:
Activity Bar, Status Bar, Banner.
4.3 Editor Modal
The main editor part is hidden (
display:none
). All editors open via
MODAL_GROUP
into the standard
ModalEditorPart
overlay (created on-demand by
EditorParts.createModalEditorPart
). The sessions configuration sets
workbench.editor.useModal
to
'all'
, which causes
findGroup()
to redirect all editor opens to the modal. Click backdrop or press Escape to dismiss.
5. Chat Widget
The Agent Sessions chat experience is built around
AgentSessionsChatWidget
— a wrapper around the core
ChatWidget
that adds:
Deferred session creation
— the UI is interactive before any session resource exists; sessions are created on first message send
Target configuration
— observable state tracking which agent provider (Local, Cloud) is selected
Welcome view
— branded empty state with mascot, target buttons, option pickers, and input slot
Initial session options
— option selections travel atomically with the first request
Configurable picker placement
— pickers can appear in welcome view, input toolbar, or both
Read
browser/widget/AGENTS_CHAT_WIDGET.md
for the full architecture.
Key classes:
AgentSessionsChatWidget
(
browser/widget/agentSessionsChatWidget.ts
) — main wrapper
AgentSessionsChatTargetConfig
(
browser/widget/agentSessionsChatTargetConfig.ts
) — reactive target state
AgentSessionsChatWelcomePart
(
browser/parts/agentSessionsChatWelcomePart.ts
) — welcome view
AgentSessionsChatInputPart
(
browser/parts/agentSessionsChatInputPart.ts
) — standalone input adapter
6. Menus
The agent sessions window uses
its own menu IDs
defined in
browser/menus.ts
via the
Menus
export.
Never use shared
MenuId.
constants
from
vs/platform/actions
for agent sessions UI — use the
Menus.
equivalents instead.
Menu ID
Purpose
Menus.ChatBarTitle
Chat bar title actions
Menus.CommandCenter
Center toolbar with session picker widget
Menus.CommandCenterCenter
Center section of command center
Menus.TitleBarContext
Titlebar context menu
Menus.TitleBarLeftLayout
Left layout toolbar
Menus.TitleBarSessionTitle
Session title in titlebar
Menus.TitleBarSessionMenu
Session menu in titlebar
Menus.TitleBarRightLayout
Right layout toolbar
Menus.PanelTitle
Panel title bar actions
Menus.SidebarTitle
Sidebar title bar actions
Menus.SidebarFooter
Sidebar footer (account widget)
Menus.SidebarCustomizations
Sidebar customizations menu
Menus.AuxiliaryBarTitle
Auxiliary bar title actions
Menus.AuxiliaryBarTitleLeft
Auxiliary bar left title actions
Menus.AgentFeedbackEditorContent
Agent feedback editor content menu
7. Context Keys
Defined in
common/contextkeys.ts
:
Context Key
Type
Purpose
activeChatBar
string
ID of the active chat bar panel
chatBarFocus
boolean
Whether chat bar has keyboard focus
chatBarVisible
boolean
Whether chat bar is visible
sessionsWelcomeVisible
boolean
Whether the sessions welcome overlay is visible
8. Contributions
Feature contributions live under
contrib/
sessions
安装
npx skills add https://github.com/microsoft/vscode --skill sessions