# Windows Terminal — Administrator & Developer Guide

Windows Terminal is Microsoft's modern, GPU-accelerated terminal emulator for Windows 10 and 11. Built with C++20 and WinUI 2 (XAML Islands), it hosts multiple shell profiles in a tabbed, paned interface with full VT100/VT510 sequence support, a DirectX-based rendering pipeline, and extensive JSON-driven configuration. This guide covers every architectural layer, the complete settings surface, enterprise deployment, security hardening, performance tuning, and the developer internals needed to build, extend, or embed the terminal.

For end-user guidance (installation, everyday usage, key bindings, themes), see the User Guide and return here for depth.

| Attribute | Value |
|-----------|-------|
| License | MIT |
| Primary language | C++20 |
| Main binary | `WindowsTerminal.exe` (packaged MSIX) |
| Min supported Windows | 10.0.19041 (version 2004) |
| Package identity | `Microsoft.WindowsTerminal_8wekyb3d8bbwe` |
| Preview identity | `Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe` |
| Canary identity | `Microsoft.WindowsTerminalCanary_8wekyb3d8bbwe` |
| Settings schema | `https://aka.ms/terminal-profiles-schema` |
| Build system | MSBuild + vcpkg (manifest mode) |
| CI | Azure DevOps (`dev.azure.com/shine-oss/terminal`) |

---

## 1. Architecture Overview

Windows Terminal is organized into a stack of reusable layers. Each layer compiles to its own static library or WinRT component; higher layers depend only on lower ones. The repository refers to this stack as **Cascadia**.

### 1.1 Component Stack

```
 ┌──────────────────────────────────────────────────────────────────┐
 │  WindowsTerminal.exe  (Win32 host; wWinMain; WindowEmperor)      │
 │  CascadiaPackage  (MSIX identity, manifest, jumplist, assets)    │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
                              │  hosts
 ┌──────────────────────────────────────────────────────────────────┐
 │  TerminalApp  (WinRT)                                            │
 │    AppLogic · TerminalWindow · TerminalPage · NewTabMenu ·       │
 │    CommandPalette · SettingsUI · Tabs · Panes · AppCmdlineArgs   │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
 ┌──────────────────────────────────────────────────────────────────┐
 │  TerminalControl  (WinRT XAML control, reusable in other apps)   │
 │    TermControl · ControlCore · ControlInteractivity              │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
 ┌──────────────────────────────────────────────────────────────────┐
 │  TerminalCore                                                    │
 │    Terminal · TextBuffer · Scrollback · Selection · Search       │
 │    VT parser · VT state machine · input translator               │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
 ┌──────────────────────────────────────────────────────────────────┐
 │  TerminalSettingsModel / TerminalSettingsEditor  (WinRT)         │
 │    CascadiaSettings · Profile · ColorScheme · Theme · Action     │
 │    JSON serialization, inheritance, migration                    │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
 ┌──────────────────────────────────────────────────────────────────┐
 │  TerminalConnection  (WinRT; pluggable back-ends)                │
 │    ConptyConnection · AzureConnection · EchoConnection · ...     │
 └──────────────────────────────────────────────────────────────────┘
                              ▲
                              │  ConPTY (pseudo console)
                              ▼
 ┌──────────────────────────────────────────────────────────────────┐
 │  OpenConsole.exe  (dev build of conhost.exe)                     │
 │  src/host, src/server, src/renderer, src/terminal                │
 └──────────────────────────────────────────────────────────────────┘
```

### 1.2 Core Components

| Component | Source Path | Role |
|-----------|------------|------|
| `WindowEmperor` | `src/cascadia/WindowsTerminal/WindowEmperor.*` | Manages all windows in the user session; implements the monarch/peasant model for cross-window communication |
| `AppHost` | `src/cascadia/WindowsTerminal/AppHost.*` | Per-window host; creates the XAML island, bridges window and application logic |
| `IslandWindow` / `NonClientIslandWindow` | `src/cascadia/WindowsTerminal/` | Win32 HWND hosting XAML content; handles DPI scaling, virtual desktop interaction, and non-client-area rendering |
| `AppLogic` / `TerminalWindow` | `src/cascadia/TerminalApp/` | Application-level logic; tab and pane management, settings load, language selection |
| `TerminalPage` | `src/cascadia/TerminalApp/TerminalPage.*` | Main UI page; action dispatch, tab management, command palette, new-tab menu |
| `TerminalControl` | `src/cascadia/TerminalControl/` | Reusable WinUI control wrapping the terminal core; `TermControl`, `ControlCore`, `ControlInteractivity` |
| `TerminalCore` | `src/cascadia/TerminalCore/` | VT parsing, buffer management, text storage, selection, search |
| `TerminalConnection` | `src/cascadia/TerminalConnection/` | Connection abstractions: `ConptyConnection`, `AzureConnection`, `EchoConnection`, `EmptyConnection` |
| `TerminalSettingsModel` | `src/cascadia/TerminalSettingsModel/` | Settings parsing, JSON schema, cascading defaults, profile generators, migration |
| `TerminalSettingsEditor` | `src/cascadia/TerminalSettingsEditor/` | Settings UI (XAML pages for each settings category) |

> [!NOTE]
> Windows Terminal is **not** a shell. It hosts shells (PowerShell, cmd, WSL, Azure Cloud Shell, SSH). It does not implement command parsing, completion, or scripting. It is also not cross-platform — it is Windows-only by design.

### 1.3 Host and Server Components

| Component | Source Path | Files | Purpose |
|-----------|------------|-------|---------|
| Console Host | `src/host/` | 92 files, 942K chars | Classic `conhost.exe` — manages console sessions, text buffer, rendering |
| Console Server | `src/server/` | 45 files, 258K chars | ALPC-based API server implementing Win32 Console API calls |
| ConPTY | `src/winconpty/` | 5 files | Pseudo Console API: `CreatePseudoConsole`, `ResizePseudoConsole`, `ClosePseudoConsole` |
| Interactivity | `src/interactivity/` | Win32 + OneCore layers | Input/output interaction layers for different Windows SKUs |

### 1.4 Rendering Pipeline

| Renderer | Source Path | Technology | Use Case |
|----------|------------|------------|----------|
| AtlasEngine | `src/renderer/atlas/` | Direct3D 11 + Direct2D/DirectWrite | GPU-accelerated rendering for Windows Terminal (default) |
| GDI | `src/renderer/gdi/` | GDI | Fallback renderer for `conhost.exe` |
| UIA | `src/renderer/uia/` | UI Automation | Accessibility: emits text-changed and caret-moved events for screen readers |
| WDDM | `src/renderer/wddmcon/` | WDDM Console | Kernel-mode display rendering |

### 1.5 Terminal Adapter and Parser

| Component | Source Path | Purpose |
|-----------|------------|---------|
| VT Adapter | `src/terminal/adapter/` (23 files) | Implements `ITermDispatch` — maps parsed VT sequences to buffer mutations |
| VT Parser | `src/terminal/parser/` | State machine implementing xterm/Ecma-48/DEC VT parsing |
| Input Translator | `src/terminal/input/` | Encodes Win32 virtual keys and modifier state into VT input sequences |

### 1.6 Supporting Libraries

| Library | Source Path | Purpose |
|---------|------------|---------|
| `src/types/` | Common types | Coords, rects, colors, viewport, utils |
| `src/til/` | Terminal Implementation Library | Custom containers, threading primitives (`shared_mutex`, `latch`, `throttled_func`) |
| `src/inc/` | Shared headers | Public headers shared across the tree |
| `src/buffer/` | Text buffer | Text buffer implementation used by both host and Cascadia |
| `src/tsf/` | Text Services Framework | IME (Input Method Editor) support |
| `src/propslib/` | Properties library | Registry-based settings for classic console |
| `src/propsheet/` | Properties dialog | Console properties dialog (29 files, 262K chars) |

### 1.7 External Dependencies (vendored in `oss/`)

| Dependency | Purpose | License |
|------------|---------|---------|
| Chromium `base/numerics` | Safe math (checked/clamped arithmetic) | BSD |
| stb | Image loading | MIT/Public Domain |
| pcg | Random number generation | Apache-2.0 |
| interval_tree | Interval tree data structure | Zlib |
| wyhash | Fast hash function | Unlicense |
| fzf | Fuzzy finder (for suggestions) | MIT (Junegunn Choi / Simon Hauser) |

### 1.8 vcpkg Dependencies (build-time)

| Package | Version | Purpose | License |
|---------|---------|---------|---------|
| `fmt` | 12.1.0 | String formatting | MIT |
| `ms-gsl` | 3.1.0 | Microsoft Guidelines Support Library (`span`, `not_null`) | MIT |
| `jsoncpp` | 1.9.6 | JSON parser for `settings.json` | MIT |
| `cli11` | 2.6.1 | Command-line parser for `wt.exe` sub-commands | BSD-3 |
| `cmark` | 0.31.1 | CommonMark parser (About dialog, command descriptions) | BSD-2 |

### 1.9 Technology Stack

| Component | Technology |
|-----------|-----------|
| Language | C++20 with Microsoft extensions, C++/WinRT |
| UI Framework | WinUI 2 (XAML Islands hosted in Win32) |
| Build System | MSBuild + vcpkg (manifest mode) |
| Rendering | Direct3D 11 (AtlasEngine), GDI fallback |
| Terminal Protocol | VT100/VT220/VT510, Ecma-48 |
| IPC | COM-based Monarch/Peasant remoting, named pipes (ConPTY) |
| Packaging | MSIX (`.msixbundle`) |

### 1.10 Process Model

The MSIX package ships a single executable: `WindowsTerminal.exe`. It runs once per user session and uses a **monarch/peasant** cooperation model:

- **Monarch**: the first Terminal process launched in the session. Owns inter-window RPC.
- **Peasants**: subsequent launches register with the monarch. Commands like `wt -w <name>` are forwarded to whichever peasant owns that named window.
- **WindowEmperor**: the in-process manager that owns every window the monarch has opened.

### 1.11 Connection Back-ends

Each pane runs through an `ITerminalConnection` implementation:

| Connection | Purpose |
|------------|---------|
| `ConptyConnection` | Spawns a child process via `CreatePseudoConsole`. Default for every profile with a `commandline`. |
| `AzureConnection` | Opens an Azure Cloud Shell WebSocket session. |
| `EchoConnection` | Test-only echo back-end. |
| `EmptyConnection` | Used when Terminal displays UI without a live shell. |

### 1.12 Data Flow

```
User input → XAML TerminalControl → ControlInteractivity
  → TerminalInput (VT encoding) → ConPTY pipe → conhost/shell process
  → stdout pipe → ConptyConnection → VT StateMachine parser
  → TextBuffer mutations → Damage tracker → AtlasEngine
  → GPU glyph atlas → DirectComposition → display
```

### 1.13 Settings and Policy Flow

`CascadiaSettings` merges four layers at startup (lowest priority first):

```
          ┌──────────────────────────┐
 lowest   │ defaults.json (baked)    │   Compiled into the binary
          └──────────────────────────┘
                       │
          ┌──────────────────────────┐
          │ Dynamic profile sources  │   WSL, Azure, PowerShell 7, VS, Git Bash
          └──────────────────────────┘
                       │
          ┌──────────────────────────┐
          │ Fragments / extensions   │   %ProgramData% or %LocalAppData%
          └──────────────────────────┘
                       │
          ┌──────────────────────────┐
 highest  │ User settings.json       │   %LocalAppData%\Packages\...\LocalState\
          └──────────────────────────┘
```

For each property, the highest layer that sets the key wins. Arrays with `name`/`guid` keys are merged by key; everything else is replaced wholesale.

---

## 2. System Requirements

### 2.1 Runtime

| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| Windows | 10.0.19041 (version 2004) | 11.0.22621+ |
| Architecture | x64 / ARM64 / x86 | x64 or ARM64 |
| GPU | D3D11 feature level 9_1 (or software WARP) | Any modern dGPU or iGPU |
| RAM | 256 MB free at boot | 1 GB+ for heavy scrollback |
| Disk | ~200 MB | -- |
| .NET | Not required (native C++) | -- |
| VC++ Redist | Required on older Windows 10 (framework package) | Bundled in MSIX dependencies |

### 2.2 Build-Time (Developer Box)

| Requirement | Minimum | Notes |
|-------------|---------|-------|
| OS | Windows 10 2004+ | 11 recommended for full feature set |
| Visual Studio | 2022 (17.8+) | Community, Professional, or Enterprise |
| VS Workloads | Desktop Development with C++, Universal Windows Platform Development | Required |
| Individual Components | C++ (v143) UWP Tools, Git for Windows, Windows App SDK | Required |
| Windows SDK | 10.0.22621 | Manifest builds against older SDKs but 22621 is required |
| PowerShell | 7+ | Required by build scripts |
| vcpkg | Bootstrapped by build | Uses `vcpkg-configuration.json` manifest mode |
| Free disk | ~30 GB | Build output, NuGet packages, vcpkg cache |

The fastest way to set up a developer box:

```powershell
winget configure .config\configuration.winget
```

This installs Visual Studio Community with all required workloads and components automatically. Enterprise and Professional variants exist in the same folder.

> [!TIP]
> Developer Mode must be enabled on the build machine: **Settings > Privacy & Security > For developers > Developer Mode**. This allows MSIX sideloading during development.

---

## 3. Configuration Reference

Everything about the Terminal user experience is defined in JSON. There is no registry, database, or protobuf backing store.

### 3.1 Settings File Locations

| Install Method | Path |
|---------------|------|
| Microsoft Store (Stable) | `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json` |
| Microsoft Store (Preview) | `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\settings.json` |
| Microsoft Store (Canary) | `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalCanary_8wekyb3d8bbwe\LocalState\settings.json` |
| Unpackaged / Portable | `<install root>\settings\settings.json` |

> [!IMPORTANT]
> The schema at `doc/cascadia/profiles.schema.json` (109K chars, 3,300+ lines) is the authoritative source for every recognized setting. Point your editor at `"$schema": "https://aka.ms/terminal-profiles-schema"` for IntelliSense. Terminal itself does not validate against the schema at load time; invalid keys are silently ignored (a warning is trace-logged).

### 3.2 Top-Level JSON Structure

```json
{
  "$schema": "https://aka.ms/terminal-profiles-schema",
  "defaultProfile": "{guid-or-name}",
  "profiles": {
    "defaults": {},
    "list": []
  },
  "schemes": [],
  "actions": [],
  "keybindings": [],
  "themes": [],
  "newTabMenu": []
}
```

### 3.3 Global Settings

All global settings are set at the top level of `settings.json`, alongside `profiles`, `schemes`, etc.

#### Launch Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `defaultProfile` | string | `{61c54bbd-...}` (PowerShell) | GUID or name of the profile opened by default. **Required.** |
| `initialCols` | integer (1-999) | `120` | Column count at first load. Ignored when `launchMode` is `maximized` or `fullscreen`. |
| `initialRows` | integer (1-999) | `30` | Row count at first load. Same caveat as `initialCols`. |
| `initialPosition` | string (Coordinates) | -- | Position of top-left corner on first load. Format: `"x,y"`. `",200"` keeps system X, overrides Y. |
| `centerOnLaunch` | boolean | `false` | Auto-center the window on the display specified by `initialPosition`. |
| `launchMode` | enum | `"default"` | Values: `default`, `maximized`, `fullscreen`, `focus`, `maximizedFocus`. |
| `firstWindowPreference` | enum | `"defaultProfile"` | `"defaultProfile"` or `"persistedWindowLayout"` (restores tabs/panes from last session). |
| `startupActions` | string | `""` | Chain of `wt` sub-commands to execute at launch. |
| `windowingBehavior` | enum | `"useNew"` | `"useNew"` always creates a new window. `"useExisting"` reuses the MRU window on this desktop. `"useAnyExisting"` reuses across desktops. |
| `autoHideWindow` | boolean | `false` | Hide the window as soon as it loses focus. |

#### UI Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `theme` | string or ThemePair | `"dark"` | Name of a theme from the `themes` array, or `"dark"`, `"light"`, `"system"`. Also accepts `{"light":"...","dark":"..."}` for automatic switching. |
| `alwaysOnTop` | boolean | `false` | Keep the window above all other windows. |
| `alwaysShowTabs` | boolean | `true` | Show tab bar even with a single tab. |
| `showTabsInTitlebar` | boolean | `true` | Merge tabs into the title bar. |
| `showTerminalTitleInTitlebar` | boolean | `true` | Display selected tab's title in the title bar. |
| `showTabsFullscreen` | boolean | `false` | Keep tabs visible in fullscreen mode. |
| `tabWidthMode` | enum | `"equal"` | `"equal"`, `"titleLength"`, or `"compact"` (shrinks unfocused tabs to icon only). |
| `tabSwitcherMode` | enum | `"inOrder"` | `"mru"` (most recently used), `"inOrder"`, or `"disabled"`. |
| `newTabPosition` | enum | `"afterLastTab"` | `"afterLastTab"` or `"afterCurrentTab"`. |
| `showAdminShield` | boolean | `true` | Display a shield icon in the tab row when running elevated. |
| `useAcrylicInTabRow` | boolean | `false` | Apply acrylic material (50% opacity) to the tab row. |
| `disableAnimations` | boolean | `false` | Disable all XAML animations. |
| `snapToGridOnResize` | boolean | `false` | Snap window to nearest character boundary on resize. |
| `focusFollowMouse` | boolean | `false` | Focus pane on mouse hover. |
| `minimizeToNotificationArea` | boolean | `false` | Minimize to system tray instead of taskbar. |
| `alwaysShowNotificationIcon` | boolean | `false` | Always show the Terminal icon in the notification area. |
| `language` | string or null | `null` | Override app language (BCP-47 tag, e.g., `"en-US"`). |

#### Clipboard and Selection Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `copyOnSelect` | boolean | `false` | Copy text to clipboard immediately upon selection. |
| `copyFormatting` | CopyFormat | `true` | Include formatting when copying. Values: `true`, `false`, `"html"`, `"rtf"`, `"all"`, `"none"`, or an array of `["html","rtf"]`. |
| `trimBlockSelection` | boolean | `true` | Remove trailing whitespace from rectangular (block) selections. |
| `trimPaste` | boolean | `true` | Strip trailing whitespace from pasted text. |
| `wordDelimiters` | string | `` ./\()\"'-:,.;<>~!@#$%^&*\|+=[]{}~?\│`` | Characters that delimit words for double-click selection. |

#### Warning and Confirmation Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `warning.confirmCloseAllTabs` | boolean | `true` | Confirm before closing a window with multiple tabs. |
| `warning.largePaste` | boolean | `true` | Warn when pasting more than 5 KiB of text. |
| `warning.multiLinePaste` | boolean | `true` | Warn when pasting text containing newlines. |
| `warning.inputService` | boolean | `true` | Warn if Touch Keyboard and Handwriting Panel Service is disabled. |

#### Rendering Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `rendering.graphicsAPI` | enum | -- | `"automatic"`, `"direct2d"`, or `"direct3d11"`. Direct3D 11 is more performant; Direct2D is more stable. |
| `rendering.disablePartialInvalidation` | boolean | -- | When true, uses a FLIP_DISCARD swap chain with no dirty rectangles. Useful for certain GPU/driver combinations. |
| `rendering.software` | boolean | -- | Force software rasterizer (WARP). Almost never needed. |

#### Compatibility Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `compatibility.allowHeadless` | boolean | `false` | Allow Terminal to run in the background with no visible windows. Required for `globalSummon` and `quakeMode` when all windows are closed. |
| `compatibility.enableUnfocusedAcrylic` | boolean | `true` | Allow unfocused windows to retain acrylic instead of switching to opaque. |
| `compatibility.textMeasurement` | enum | `"graphemes"` | How text is grouped into cells: `"graphemes"` (modern, Unicode-correct), `"wcswidth"` (UNIX-style), or `"console"` (legacy Windows behavior). |
| `compatibility.ambiguousWidth` | enum | `"narrow"` | Cell width for East Asian Ambiguous characters: `"narrow"` or `"wide"`. |

#### Experimental Global Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `experimental.detectURLs` | boolean | `true` | Underline URLs on hover; Ctrl+click to open. |
| `experimental.enableColorSelection` | boolean | `false` | Add preset color-selection keybindings (e.g., Alt+6 to color selection red). |
| `experimental.input.forceVT` | boolean | -- | **Deprecated.** Replaced by the per-profile `compatibility.input.forceVT`. |
| `experimental.scrollToZoom` | boolean | `true` | Ctrl+scroll changes font size. |
| `experimental.scrollToChangeOpacity` | boolean | `true` | Ctrl+Shift+scroll changes window opacity. |
| `experimental.useBackgroundImageForWindow` | boolean | `false` | Expand focused profile's background image across the entire window. |

#### Profile Source Control

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `disabledProfileSources` | array of strings | `[]` | Disable dynamic profile generators. Values: `"Microsoft.WSL"`, `"Windows.Terminal.Wsl"`, `"Windows.Terminal.Azure"`, `"Windows.Terminal.PowershellCore"`, `"Windows.Terminal.VisualStudio"`. |

### 3.4 Profile Settings

Profile settings go in `profiles.defaults` (applied to all profiles) or individual entries in `profiles.list`. Use the object form: `"profiles": { "defaults": {...}, "list": [...] }`.

#### Identity and Command

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `guid` | ProfileGuid | -- | Unique identifier in registry format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`. **Required** for list entries. |
| `name` | string | -- | Display name in the dropdown. **Required** for list entries. |
| `source` | string or null | -- | Name of the profile generator that created this profile (e.g., `"Windows.Terminal.Wsl"`). |
| `commandline` | string | -- | Executable to launch (e.g., `"powershell.exe"`, `"wsl.exe -d Ubuntu"`). |
| `startingDirectory` | string or null | -- | Initial working directory for the shell. |
| `icon` | string or null | -- | Image file path, URI, or emoji for the tab, dropdown, and jumplist. |
| `tabTitle` | string or null | -- | Override the default tab title passed to the shell on startup. |
| `suppressApplicationTitle` | boolean | `false` | When true, `tabTitle` is fixed and title-change messages from the shell are ignored. |
| `hidden` | boolean | `false` | Hide this profile from the dropdown without removing it from settings. |
| `elevate` | boolean | `false` | Always open this profile in an elevated context. Triggers UAC if the window is not already admin. |
| `reloadEnvironmentVariables` | boolean | `true` | Reload the environment block when creating a new session (instead of inheriting from the Terminal process). |
| `environment` | object | -- | Key-value pairs of environment variables to set. Names are case-insensitive. Supports `%PATH%`-style expansion. |

#### Appearance

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `colorScheme` | string or SchemePair | `"Campbell"` | Color scheme name. Accepts `{"light":"...","dark":"..."}` for theme-aware switching. |
| `foreground` | Color or null | `"#cccccc"` | Override text color from color scheme. |
| `background` | Color or null | `"#0c0c0c"` | Override background color from color scheme. |
| `cursorColor` | Color or null | -- | Override cursor color from color scheme. |
| `selectionBackground` | Color or null | -- | Override selection background from color scheme. |
| `opacity` | number (0-100) | `100` | Window opacity. Defaults to 50 when `useAcrylic` is true. |
| `useAcrylic` | boolean | `false` | Enable acrylic material background. |
| `padding` | string or integer | `"8, 8, 8, 8"` | Padding around text. Formats: `"8"`, `"8, 8"`, or `"8, 8, 8, 8"` (left, top, right, bottom). |
| `tabColor` | Color or null | -- | Fixed tab color. Overridden by the tab color picker. |
| `intenseTextStyle` | enum | `"bright"` | How intense (bold) text renders: `"bold"`, `"bright"`, `"all"`, or `"none"`. |
| `adjustIndistinguishableColors` | enum | `"never"` | Adjust foreground for visibility against background: `"never"`, `"indexed"`, or `"always"`. |

#### Background Image

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `backgroundImage` | string or null | -- | Path to background image, or `"desktopWallpaper"` to use the current wallpaper. |
| `backgroundImageOpacity` | number (0.0-1.0) | `1.0` | Transparency of the background image. |
| `backgroundImageStretchMode` | enum | `"uniformToFill"` | How image fills the pane: `"fill"`, `"none"`, `"uniform"`, `"uniformToFill"`. |
| `backgroundImageAlignment` | enum | `"center"` | Image alignment: `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"`. |

#### Font

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `font.face` | string | `"Cascadia Mono"` | Font face name. |
| `font.size` | number | `12` | Font size in points. Minimum: 1. |
| `font.weight` | string or integer | `"normal"` | Font weight: `"thin"`, `"extra-light"`, `"light"`, `"semi-light"`, `"normal"`, `"medium"`, `"semi-bold"`, `"bold"`, `"extra-bold"`, `"black"`, `"extra-black"`, or numeric 100-990. |
| `font.features` | object | -- | DWrite font features. Example: `{"ss01": 1, "liga": 0}` enables stylistic set 01 and disables ligatures. |
| `font.axes` | object | -- | DWrite font axes. Example: `{"wght": 200}` sets font weight to 200. |
| `font.cellWidth` | CSSLengthPercentage | -- | Override cell width. Works like CSS `letter-spacing`. |
| `font.cellHeight` | CSSLengthPercentage | -- | Override cell height. Works like CSS `line-height`. Defaults to approximately 1.2x font size. |

> [!NOTE]
> The deprecated aliases `fontFace`, `fontSize`, and `fontWeight` (top-level profile properties) still function but should be replaced with the nested `font.*` form.

#### Cursor

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `cursorShape` | enum | `"bar"` | Cursor shape: `"bar"` (┃), `"doubleUnderscore"` (‗), `"emptyBox"` (▯), `"filledBox"` (█), `"underscore"` (▁), `"vintage"` (▃). |
| `cursorHeight` | integer (1-100) or null | `25` | Cursor height percentage (bottom-up). Only effective when `cursorShape` is `"vintage"`. |

#### Input and Scrolling

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `historySize` | integer | `9001` | Lines of scrollback. Value of `-1` means unlimited (high memory usage). |
| `snapOnInput` | boolean | `true` | Scroll to the input line when typing. |
| `scrollbarState` | enum | `"visible"` | Scrollbar visibility: `"visible"`, `"hidden"`, `"always"`. |
| `altGrAliasing` | boolean | `true` | Treat Ctrl+Alt as AltGr. Set to false on layouts where AltGr is a physical key. |
| `antialiasingMode` | enum | `"grayscale"` | Text antialiasing: `"grayscale"`, `"cleartype"`, `"aliased"`. Requires a new terminal instance to take effect. |

#### Bell

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `bellStyle` | BellStyle | `"audible"` | How BEL characters are handled: `"audible"`, `"window"` (flash), `"taskbar"` (flash icon), `"all"`, `"none"`, or an array like `["audible","taskbar"]`. Also accepts booleans. |
| `bellSound` | string, array, or null | `""` | Custom WAV file path for the bell sound. Accepts an array for random selection. |

#### Shell Integration

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `autoMarkPrompts` | boolean | `true` | Automatically mark prompts (requires OSC 133 integration in the shell). |
| `showMarksOnScrollbar` | boolean | `false` | Show marks added via `addMark` action on the scrollbar. |
| `rightClickContextMenu` | boolean | `false` | Right-click shows a context menu instead of pasting. |
| `answerbackMessage` | string or null | -- | Response string sent when an ENQ control character is received. |

#### Compatibility (Per-Profile)

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `compatibility.reloadEnvironmentVariables` | boolean | `true` | Reload environment variables for new tabs/panes. |
| `compatibility.input.forceVT` | boolean | `false` | Force legacy VT input encoding. Some application keys may stop working. |
| `compatibility.allowDECRQCRA` | boolean | `false` | Support DECRQCRA (Request Checksum of Rectangular Area) escape sequence. |
| `compatibility.allowOSC52` | boolean | `true` | Allow VT applications to set clipboard contents via OSC 52. |

#### Drag and Drop

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `pathTranslationStyle` | enum | `"none"` | Transform dropped file paths: `"none"`, `"wsl"`, `"cygwin"`, `"msys2"`, `"mingw"`. |
| `dragDropDelimiter` | string | `" "` | Delimiter between multiple dropped files. |

#### Lifecycle

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `closeOnExit` | enum or boolean | `"automatic"` | Behavior on shell exit: `"graceful"` (close on clean exit), `"always"`, `"automatic"` (graceful for Terminal-launched, always otherwise), `"never"`. Booleans accepted: `true`=graceful, `false`=never. |

#### Nested Appearance

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `unfocusedAppearance` | AppearanceConfig or null | -- | Override any appearance setting (colors, cursor, background image, opacity, etc.) when the pane is unfocused. |

#### Experimental (Per-Profile)

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `experimental.retroTerminalEffect` | boolean | -- | Enable retro CRT terminal visual effect. |
| `experimental.pixelShaderPath` | string | -- | Path to an HLSL pixel shader. Overrides `retroTerminalEffect`. |
| `experimental.rightClickContextMenu` | boolean | `false` | Show context menu on right-click. |
| `experimental.repositionCursorWithMouse` | boolean | `false` | Click to move the text cursor on the current command line. |
| `experimental.rainbowSuggestions` | boolean | `false` | Display command suggestions in rainbow colors. |

### 3.5 Color Schemes

Array of scheme objects in the `schemes` key. Each scheme defines:

| Property | Type | Description |
|----------|------|-------------|
| `name` | string | Scheme name (referenced by profiles). **Required.** |
| `foreground` | Color | Default text color. |
| `background` | Color | Default background color. |
| `cursorColor` | Color | Cursor color (default: `"#FFFFFF"`). |
| `selectionBackground` | Color | Selection highlight color. |
| `black` | Color | ANSI color 0. |
| `red` | Color | ANSI color 1. |
| `green` | Color | ANSI color 2. |
| `yellow` | Color | ANSI color 3. |
| `blue` | Color | ANSI color 4. |
| `purple` | Color | ANSI color 5. |
| `cyan` | Color | ANSI color 6. |
| `white` | Color | ANSI color 7. |
| `brightBlack` | Color | ANSI color 8. |
| `brightRed` | Color | ANSI color 9. |
| `brightGreen` | Color | ANSI color 10. |
| `brightYellow` | Color | ANSI color 11. |
| `brightBlue` | Color | ANSI color 12. |
| `brightPurple` | Color | ANSI color 13. |
| `brightCyan` | Color | ANSI color 14. |
| `brightWhite` | Color | ANSI color 15. |

Colors use `#RRGGBB` or `#AARRGGBB` format.

**Built-in schemes** (shipped in `defaults.json`): Campbell, Campbell Powershell, Vintage, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, Dark+, VSCode Dark Modern, VSCode Light Modern, CGA, IBM 5153, Dimidium, Ottosson.

### 3.6 Themes

Array of theme objects defining window chrome appearance:

#### Theme Object

| Property | Type | Description |
|----------|------|-------------|
| `name` | string | Theme name. Must not be `"light"`, `"dark"`, or `"system"` (reserved). |
| `window` | WindowTheme | Window frame and application theme settings. |
| `tab` | TabTheme | Individual tab appearance. |
| `tabRow` | TabRowTheme | Tab row (bar) appearance. |

#### WindowTheme

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `applicationTheme` | enum | -- | `"light"`, `"dark"`, or `"system"`. |
| `useMica` | boolean | `false` | Apply Mica material backdrop across the entire window. |
| `frame` | ThemeColor | -- | Window frame color when focused (Windows 11 only). |
| `unfocusedFrame` | ThemeColor | -- | Window frame color when unfocused (Windows 11 only). |
| `experimental.rainbowFrame` | boolean | `false` | Cycle frame through rainbow colors. Overrides `frame`/`unfocusedFrame`. |

#### TabTheme

| Property | Type | Description |
|----------|------|-------------|
| `background` | ThemeColor | Active tab background color. |
| `unfocusedBackground` | ThemeColor | Inactive tab background color. |
| `showCloseButton` | enum | Tab close button visibility: `"always"`, `"hover"`, `"never"`, `"activeOnly"`. |
| `iconStyle` | enum | Tab icon appearance: `"default"`, `"hidden"`, `"monochrome"`. |

#### TabRowTheme

| Property | Type | Description |
|----------|------|-------------|
| `background` | ThemeColor | Tab row color when the window is focused. |
| `unfocusedBackground` | ThemeColor | Tab row color when the window is inactive. |

**ThemeColor** can be a `#RRGGBB` hex, `#RRGGBBAA` hex, `"accent"` (OS accent color), `"terminalBackground"` (active pane's background), or `null`.

The global `theme` setting references a theme by name. The built-in themes are: `dark`, `light`, `system`, `legacyDark`, `legacyLight`, `legacySystem`.

### 3.7 Actions

Array of action definitions in the `actions` key:

```jsonc
{
  "id": "Terminal.OpenNewTab",
  "name": { "key": "OpenNewTabCommandName" },
  "icon": "\uE8A5",
  "command": "newTab"
}
```

| Property | Type | Description |
|----------|------|-------------|
| `id` | string | Stable identifier referenced by keybindings and newTabMenu entries. |
| `name` | string or object | Display name in the command palette. Object form: `{"key": "ResourceName"}` for localized strings. |
| `icon` | string | Path, URI, or emoji. |
| `command` | string or object | Short action name (e.g., `"newTab"`) or object with `"action"` plus argument properties. |
| `iterateOn` | enum | Generate iterable commands: `"profiles"` or `"schemes"`. |

#### Complete Action Reference (76 Actions)

**Tab Management:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `newTab` | NewTerminalArgs | Open a new tab. |
| `duplicateTab` | -- | Duplicate the current tab. |
| `closeTab` | `index` (int or null) | Close a tab (default: focused). |
| `closeOtherTabs` | `index` (int or null) | Close all tabs except the specified one. |
| `closeTabsAfter` | `index` (int or null) | Close all tabs after the specified one. |
| `nextTab` | `tabSwitcherMode` (enum) | Move to the next tab. |
| `prevTab` | `tabSwitcherMode` (enum) | Move to the previous tab. |
| `switchToTab` | `index` (int, required) | Switch to tab by index (0-based). |
| `moveTab` | `direction` (`"forward"` or `"backward"`, required) | Reorder the current tab. |
| `tabSearch` | -- | Open the tab search dialog. |
| `openTabColorPicker` | -- | Open the tab color picker. |
| `openTabRenamer` | -- | Open the tab rename text box. |
| `renameTab` | `title` (string) | Set the tab title. Omit to restore original. |
| `restoreLastClosed` | -- | Reopen the last closed tab or pane. |

**Pane Management:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `splitPane` | `split` (direction), `splitMode`, `size`, NewTerminalArgs | Split the pane. Directions: `"auto"`, `"up"`, `"down"`, `"left"`, `"right"`. |
| `closePane` | -- | Close the focused pane. |
| `closeOtherPanes` | -- | Close all panes except the focused one. |
| `moveFocus` | `direction` (required) | Move focus between panes. Directions: `"left"`, `"right"`, `"up"`, `"down"`, `"previous"`, `"nextInOrder"`, `"previousInOrder"`, `"first"`, `"parent"`, `"child"`. |
| `swapPane` | `direction` (required) | Swap the focused pane with an adjacent one. Same directions as `moveFocus`. |
| `resizePane` | `direction` (required) | Resize the pane boundary. Directions: `"left"`, `"right"`, `"up"`, `"down"`. |
| `movePane` | `index` (int, required) | Move the focused pane to another tab (0-based). |
| `focusPane` | `id` (int) | Focus a pane by its numeric ID. |
| `togglePaneZoom` | -- | Toggle pane zoom (maximize/restore within the tab). |
| `toggleSplitOrientation` | -- | Rotate split between horizontal and vertical. |
| `toggleReadOnlyMode` | -- | Toggle read-only mode on the focused pane. |

**Window Management:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `newWindow` | NewTerminalArgs | Open a new Terminal window. |
| `closeWindow` | -- | Close the current window. |
| `quit` | -- | Close all windows and exit. |
| `toggleFullscreen` | -- | Toggle fullscreen mode. |
| `setFullScreen` | `isFullScreen` (boolean) | Set fullscreen explicitly. |
| `toggleFocusMode` | -- | Toggle focus mode (hides tabs and title bar). |
| `setFocusMode` | `isFocusMode` (boolean) | Set focus mode explicitly. |
| `toggleAlwaysOnTop` | -- | Toggle always-on-top. |
| `setMaximized` | `isMaximized` (boolean) | Set maximized state. |
| `identifyWindow` | -- | Show the window's name/ID overlay. |
| `identifyWindows` | -- | Show name/ID overlays on all windows. |
| `openWindowRenamer` | -- | Open the window rename dialog. |
| `renameWindow` | `name` (string) | Rename the current window. |
| `openSystemMenu` | -- | Open the system menu (Alt+Space equivalent). |
| `globalSummon` | `desktop`, `monitor`, `name`, `dropdownDuration`, `toggleVisibility` | Summon the Terminal window globally. |
| `quakeMode` | -- | Special `globalSummon` for the `_quake` window. |

**Clipboard and Selection:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `copy` | `singleLine`, `withControlSequences`, `dismissSelection`, `copyFormatting` | Copy selected text. |
| `paste` | -- | Paste from clipboard. |
| `selectAll` | -- | Select all buffer text. |
| `markMode` | -- | Enter mark mode (keyboard-driven selection). |
| `toggleBlockSelection` | -- | Switch between block and line selection. |
| `switchSelectionEndpoint` | -- | Move the active selection endpoint. |
| `expandSelectionToWord` | -- | Expand selection to word boundaries. |

**Scrollback:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `scrollUp` | `rowsToScroll` (int or null) | Scroll up by N lines. |
| `scrollDown` | `rowsToScroll` (int or null) | Scroll down by N lines. |
| `scrollUpPage` | -- | Scroll up one page. |
| `scrollDownPage` | -- | Scroll down one page. |
| `scrollToTop` | -- | Scroll to the top of the buffer. |
| `scrollToBottom` | -- | Scroll to the bottom of the buffer. |
| `scrollToMark` | `direction` (`"previous"`, `"next"`, `"first"`, `"last"`, required) | Scroll to a shell-integration mark. |
| `clearBuffer` | `clear` (`"all"`, `"screen"`, `"scrollback"`) | Clear the terminal buffer. |
| `exportBuffer` | `path` (string) | Export buffer contents to a file. If empty, opens a file picker. |
| `addMark` | `color` (Color) | Add a manual mark to the scrollbar. |
| `clearMark` | -- | Clear the mark at the current position. |
| `clearAllMarks` | -- | Clear all marks. |

**Application:**

| Action | Arguments | Description |
|--------|-----------|-------------|
| `openSettings` | `target` (`"settingsUI"`, `"settingsFile"`, `"defaultsFile"`, `"allFiles"`) | Open the settings UI or file. |
| `openNewTabDropdown` | -- | Open the new tab dropdown menu. |
| `commandPalette` | `launchMode` (`"action"` or `"commandLine"`) | Open the command palette. |
| `find` | -- | Open the search dialog. |
| `findMatch` | `direction` (`"next"` or `"prev"`, required) | Navigate search results. |
| `toggleShaderEffects` | -- | Toggle pixel shader effects. |
| `openAbout` | -- | Open the About dialog. |
| `openCWD` | -- | Open the current working directory in File Explorer. |
| `searchWeb` | `queryUrl` (string, required) | Search the web for selected text. `%s` is replaced with the selection. |
| `sendInput` | `input` (string, required) | Send text/escape sequences to the shell. |
| `wt` | `commandline` (string, required) | Execute a `wt` command line in the current window. |
| `multipleActions` | `actions` (array, required) | Execute multiple actions sequentially. |
| `showSuggestions` | `source` (SuggestionSource), `useCommandline` (boolean) | Open the suggestions UI. Sources: `"commandHistory"`, `"tasks"`, `"all"`. |
| `experimental.colorSelection` | `matchMode`, `foreground`, `background` | Color selected text. |
| `adjustFontSize` | `delta` (int, required) | Change font size by delta points. |
| `resetFontSize` | -- | Reset font to default size. |
| `adjustOpacity` | `opacity` (int, -100 to 100), `relative` (boolean) | Change window opacity. |
| `setColorScheme` | `colorScheme` (string, required) | Apply a color scheme to the active pane. |
| `setTabColor` | `color` (Color or null) | Set the tab color. Omit to reset. |

### 3.8 Keybindings

Array of `{ "keys": "<combo>", "id": "<action-id>" }` entries:

```jsonc
{ "keys": "ctrl+shift+t", "id": "Terminal.OpenNewTab" }
```

The `keys` field supports multi-key chords: `"ctrl+k, ctrl+f"` (two consecutive key combinations). The `KeyChordSegment` pattern is:

```text
[ctrl+][alt+][shift+][win+]<KeyName>
```

Where `<KeyName>` is any single character, a function key (`f1`-`f24`), a named key (`enter`, `esc`, `tab`, `space`, `backspace`, `delete`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `insert`, `menu`, `app`, `comma`, `period`, `plus`, `minus`), a numpad key (`numpad0`-`numpad9`, `numpad_add`, `numpad_subtract`, `numpad_multiply`, `numpad_divide`, `numpad_decimal`, `numpad_period`, `numpad_plus`, `numpad_minus`), a browser key (`browser_back`, `browser_forward`, etc.), or an explicit virtual key / scan code: `vk(nnn)`, `sc(nnn)`.

To unbind a default: `{ "keys": "ctrl+shift+t", "id": null }`.

### 3.9 New Tab Menu

Array of menu entries defining the structure of the new tab dropdown:

| Entry Type | Properties | Description |
|------------|-----------|-------------|
| `"profile"` | `profile` (name or GUID), `icon` | A single profile. |
| `"separator"` | -- | A visual separator line. |
| `"folder"` | `name`, `icon`, `entries` (array), `inline` (`"never"` or `"auto"`), `allowEmpty` (boolean) | A nested folder. When `inline` is `"auto"` and the folder has only one entry, it is inlined. |
| `"action"` | `id` (action ID), `icon` | An action button. |
| `"remainingProfiles"` | -- | All profiles not explicitly listed elsewhere. Use at most once (Issue #20124: duplicates cause a crash). |
| `"matchProfiles"` | `name`, `source`, `commandline` | Profiles matching the given criteria. |

> [!WARNING]
> Including more than one `remainingProfiles` entry causes an access violation in `Settings.Model.dll` (Issue #20124). Always use exactly one `remainingProfiles` entry.

### 3.10 Dynamic Profile Sources

Built-in generators that auto-create profiles:

| Generator | Source ID | Notes |
|-----------|----------|-------|
| Windows PowerShell | (hard-coded) | Always present. GUID: `{61c54bbd-c2c6-5271-96e7-009a87ff44bf}`. |
| Command Prompt | (hard-coded) | Always present. GUID: `{0caa0dad-35be-5f56-a8ff-afceeeaa6101}`. |
| PowerShell Core | `Windows.Terminal.PowershellCore` | Detects Store and MSI installs of `pwsh.exe`. |
| WSL | `Windows.Terminal.Wsl` | Enumerates `wsl --list --quiet`. |
| Azure Cloud Shell | `Windows.Terminal.Azure` | Uses `AzureConnection`. |
| Visual Studio | `Windows.Terminal.VisualStudio` | Developer PowerShell and Developer Command Prompt. |
| SSH | `Windows.Terminal.SSH` | Preview: reads `%USERPROFILE%\.ssh\config` and creates one profile per host alias. |

Each generator hashes a stable input (e.g., distro name for WSL) to produce the profile GUID, preventing duplicates across regenerations.

### 3.11 Fragment Extensions

Fragments let third-party installers contribute profiles or color schemes without editing the user's `settings.json`.

**Locations** (either):
- `%ProgramData%\Microsoft\Windows Terminal\Fragments\<publisher>\<app>\*.json`
- `%LocalAppData%\Microsoft\Windows Terminal\Fragments\<publisher>\<app>\*.json`

**Schema:**

```jsonc
{
  "profiles": [ /* same shape as user profiles */ ],
  "schemes":  [ /* same shape as user schemes */ ]
}
```

Fragment-installed profiles appear read-only in the Settings UI. Users can override individual properties in their `settings.json` (user layer wins).

### 3.12 Settings Migration

Terminal migrates settings format changes on load:

- Old `keybindings` entries without `id` are auto-rewritten with synthesized IDs.
- Deprecated keys (`useTabSwitcher`, older bell config, `acrylicOpacity`, `fontFace`, `fontSize`, `fontWeight`) are translated to their replacements.
- Migrated settings are saved back to disk on the first clean exit.

When migration fails (invalid JSON, unknown critical key), Terminal refuses to load user settings and shows an error banner.

### 3.13 Defaults File

The baked-in defaults live in `src/cascadia/TerminalSettingsModel/defaults.json`. At commit `7a83c0f`:

- 2 hard-coded profiles (Windows PowerShell, Command Prompt)
- 16 color schemes
- 6 themes (3 modern + 3 `legacy*`)
- ~150 action definitions
- ~60 default keybindings

Access via Ctrl+Alt+, or the command palette. This file is read-only; edits are lost on update.

---

## 4. Deployment & Scaling

### 4.1 Distribution Channels

| Channel | Package Family | Cadence | Min Windows | Notes |
|---------|---------------|---------|-------------|-------|
| Stable | `Microsoft.WindowsTerminal_8wekyb3d8bbwe` | ~6 weeks | 19041 | Recommended for production |
| Preview | `Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe` | ~6 weeks | 19041 | Feature-flagged; some APIs unstable |
| Canary (App Installer) | `Microsoft.WindowsTerminalCanary_8wekyb3d8bbwe` | Nightly | Windows 11 | Auto-updates |
| Canary (Portable) | No identity | Nightly | 19041 | Unpackaged; uses `.portable` flag |
| Dev (side-loaded) | `WindowsTerminalDev_8wekyb3d8bbwe` | Per-build | 19041 | VS deploy target |

All three Store packages coexist on a machine without conflict.

### 4.2 Enterprise MSIX Deployment

| Method | Command / Notes |
|--------|----------------|
| Microsoft Store | Default. Use Store for Business for air-gapped organizations. |
| winget | `winget install --id Microsoft.WindowsTerminal` |
| Provisioned (per-machine) | `Add-AppxProvisionedPackage -Online -PackagePath <msixbundle>` |
| DISM | `DISM /Online /Add-ProvisionedAppxPackage /PackagePath:<msixbundle>` |
| Intune (LOB app) | Upload `.msixbundle`; target device or user groups. |
| Intune (remediation) | PowerShell script invoking `winget install` under SYSTEM. |

> [!TIP]
> Use the provisioned install (`Add-AppxProvisionedPackage`) for shared PCs and kiosk scenarios so that new user profiles get Terminal automatically at first login.

### 4.3 Pre-staging Settings via Fragment

Ship a per-machine fragment so every user inherits corporate defaults without touching their `settings.json`:

```text
%ProgramData%\Microsoft\Windows Terminal\Fragments\Contoso\main\contoso.json
```

```jsonc
{
  "schemes": [ /* corporate color scheme */ ],
  "profiles": [
    {
      "guid": "{00000000-0000-0000-0000-deadbeef0001}",
      "name": "Contoso PS",
      "commandline": "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned",
      "colorScheme": "Contoso Dark",
      "icon": "%ProgramData%\\Contoso\\brand.png",
      "startingDirectory": "%USERPROFILE%"
    }
  ]
}
```

Deploy via Intune Win32 app, MSI, or Group Policy Preferences. Terminal scans `Fragments\` at each launch.

### 4.4 Portable ZIP Distribution

The portable ZIP excludes `AppxManifest.xml` and includes a `.portable` marker:

- If `.portable` exists next to `WindowsTerminal.exe`, Terminal writes state to `<root>\settings\` instead of `%LocalAppData%\Packages\...`.
- No MSIX identity means no App Execution Alias (`wt.exe`). Use the full path or add the root to `PATH`.

### 4.5 MSIX Internals

`CascadiaPackage` is the MSIX authoring project:

- `Package.appxmanifest` -- publisher identity, capabilities, dependencies.
- Key capabilities: `runFullTrust` (launch arbitrary shells), `userDataSystem` (starting-directory persistence).
- Key declarations: App Execution Alias (`wt.exe`), `Windows.ProtocolActivation` (`wt://` URIs), `Windows.ShellExtension` ("Open in Terminal" in File Explorer).

### 4.6 Locking Down Customization

There is no first-class "admin locks setting X" feature. Three approximations:

1. **File ACLs** -- `icacls` on the per-user `settings.json` path. Breaks the Settings UI save path.
2. **Fragments + user training** -- ship corporate settings in a fragment; brief users to minimize overrides.
3. **AppLocker / WDAC** -- block `WindowsTerminal.exe` from launching unexpected child processes.

> [!NOTE]
> Fine-grained Group Policy for Terminal settings is an open feature request with no ETA. Terminal does not ship its own ADMX template.

### 4.7 Rolling Back a Release

```powershell
# Sideload a specific version
Add-AppxPackage <file>.msixbundle

# Block future Store updates
reg add "HKLM\Software\Policies\Microsoft\WindowsStore" /v AutoDownload /t REG_DWORD /d 2 /f
```

To remove Terminal entirely:

```powershell
Get-AppxPackage -AllUsers Microsoft.WindowsTerminal | Remove-AppxPackage -AllUsers
```

### 4.8 Group Policy and MDM

Terminal does not provide its own ADMX template. Control it indirectly:

| Mechanism | Purpose |
|-----------|---------|
| AppLocker / WDAC | Permit or block `WindowsTerminal.exe`, `OpenConsole.exe`, and child shells |
| Store App Installer policy | Control MSIX sideloading (`HKLM:\Software\Policies\Microsoft\WindowsStore`) |
| Default Terminal CSP | Set default console host on Windows 11 via MDM |
| WSL policy | Control WSL via `.wslconfig` and Group Policy for Optional Features |
| Store update GPO | Pause Store auto-updates. Terminal updates through the Store, not Windows Update. |

---

## 5. Operations

### 5.1 Settings Reset Procedure

1. Close all Terminal windows.
2. Navigate to the settings directory (see section 3.1).
3. Rename `settings.json` to `settings.json.bak`.
4. Relaunch Terminal. A fresh `settings.json` is generated from `defaults.json`.

### 5.2 Persisted Window Layout

Set `"firstWindowPreference": "persistedWindowLayout"` to restore tabs, panes, and window positions across sessions. State is stored in `<LocalState>\state.json`.

> [!TIP]
> Window layout persistence saves the profile, working directory, and pane arrangement. It does **not** preserve in-flight shell state (running commands, environment modifications, scrollback history).

### 5.3 Default Terminal Application (Windows 11)

On Windows 11, Terminal can be set as the default handler for all console applications:

1. **Settings > Privacy & Security > For developers > Terminal**: select "Windows Terminal".
2. Or via MDM: `./Device/Vendor/MSFT/Policy/Config/ConsoleHost/DefaultConsoleHostTerminal`.

When set, all console applications (including those launched from Win+R, Task Scheduler, or Start Menu) open in Terminal instead of the legacy `conhost.exe`.

### 5.4 Notification Area Behavior

When `minimizeToNotificationArea` is `true`:

- Minimized windows move to the system tray.
- A Terminal icon appears in the notification area.
- Right-click the tray icon to access windows or quit.
- Set `alwaysShowNotificationIcon` to `true` to keep the icon visible at all times.

### 5.5 Shell Integration Protocol

Terminal implements the FinalTerm shell-integration dialect plus partial ConEmu and iTerm2 support:

| OSC | Effect |
|-----|--------|
| `0;` / `2;` | Set window title |
| `4;i;rgb:...` | Change palette color `i` for the session |
| `7;file://<host>/<path>` | Report current working directory |
| `8;;url` | Start/end a clickable hyperlink region |
| `9;<text>` | ConEmu: show a notification |
| `9;4;<state>;<value>` | ConEmu: update taskbar progress (0=remove, 1=default, 2=error, 3=indeterminate, 4=warning) |
| `9;9;<path>` | ConEmu: report CWD |
| `133;A` | FinalTerm: begin prompt |
| `133;B` | FinalTerm: end prompt, begin command input |
| `133;C` | FinalTerm: command is executing |
| `133;D;<code>` | FinalTerm: command completed with exit code |
| `1337;CurrentDir=<path>` | iTerm2: report CWD |
| `1337;SetMark` | iTerm2: drop a mark on the scrollbar |

**Capabilities that depend on shell integration:**

| Feature | Required OSC |
|---------|-------------|
| Scroll marks | OSC 133 prompts (or explicit `addMark`) |
| `scrollToMark` / `selectCommand` / `selectOutput` | OSC 133 prompt boundaries |
| `openCWD` / CWD-aware duplicate tab | OSC 7, OSC 9;9, or OSC 1337 |
| Quick Fix | OSC 133 D plus a Quick Fix provider |
| Taskbar progress bar | OSC 9;4 |

> [!NOTE]
> Shell integration is opt-in. Users must source the appropriate snippet in their shell profile. A ready-made drop-in is available at `https://aka.ms/terminal-shell-integration`.

**PowerShell** (`$PROFILE`):

```powershell
$Global:__LastHistoryId = -1
function Global:__Terminal-Get-LastExitCode {
    if ($? -eq $True) { return 0 }
    elseif ($LASTEXITCODE -ne 0) { return $LASTEXITCODE }
    else { return 1 }
}
function Global:Prompt() {
    $gle = $Global:?
    $LastHistoryEntry = Get-History -Count 1
    $Result  = ""
    if ($Global:__LastHistoryId -ne -1) {
        if ($LastHistoryEntry.Id -ne $Global:__LastHistoryId) {
            $Result += "$([char]27)]133;D;{0}$([char]7)" -f (__Terminal-Get-LastExitCode)
        }
    }
    $Result += "$([char]27)]133;A$([char]7)"
    $Result += "$([char]27)]9;9;$([System.IO.Path]::GetFullPath($PWD))$([char]7)"
    $Result += "PS $PWD> "
    $Result += "$([char]27)]133;B$([char]7)"
    $Global:__LastHistoryId = $LastHistoryEntry.Id
    return $Result
}
```

**bash** (WSL, `~/.bashrc`):

```bash
PS0=$'\e]133;C\a'
PS1=$'\e]133;A\a'"${PS1}"$'\e]133;B\a'
PROMPT_COMMAND='printf "\e]133;D;%s\a\e]7;file://%s%s\a" "$?" "$HOSTNAME" "$PWD"'
```

**zsh** (`~/.zshrc`):

```zsh
precmd() {
  printf '\e]133;D;%d\a' "$?"
  printf '\e]7;file://%s%s\a' "$HOSTNAME" "$PWD"
}
preexec() { printf '\e]133;C\a' }
PROMPT=$'%{\e]133;A\a%}'"$PROMPT"$'%{\e]133;B\a%}'
```

### 5.6 Telemetry and Privacy

Terminal uses `TraceLoggingProvider` (ETW) via WIL macros. Events flow into the Windows Diagnostic Data pipeline.

**Collected:** app version, language, dynamic profile generation, feature usage counts (action invocations, command palette opens), non-fatal exceptions, render frame times, startup time.

**Not collected:** terminal contents, keystrokes, command lines, `settings.json` contents, clipboard data, usernames, or paths.

To suppress optional telemetry, set Windows Diagnostic Data to "Required diagnostic data" or lower. For full suppression on Enterprise SKUs:

```powershell
reg add "HKLM\SOFTWARE\Policies\Microsoft\Windows\DataCollection" /v AllowTelemetry /t REG_DWORD /d 0 /f
```

Audit what Terminal emits locally:

```powershell
# ETW providers: Microsoft.Windows.Terminal.App, .Control, .Renderer, Microsoft.Windows.Console.Host
wpr -start GeneralProfile
# Reproduce the scenario
wpr -stop trace.etl
# Analyze in Windows Performance Analyzer
```

### 5.7 State Files and Cache

| Purpose | Path |
|---------|------|
| User settings | `<LocalState>\settings.json` |
| Window layout state | `<LocalState>\state.json` |
| Jumplist | `<LocalState>\WindowsTerminalJumplist.json` |
| Crash dumps (if enabled) | `%LocalAppData%\CrashDumps\WindowsTerminal*.dmp` |
| Logs | ETW only (no file logs) |

### 5.8 Crash Dump Configuration

To enable local crash dumps:

```powershell
$path = "HKLM:\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\WindowsTerminal.exe"
New-Item -Path $path -Force
Set-ItemProperty -Path $path -Name DumpType -Value 2
Set-ItemProperty -Path $path -Name DumpCount -Value 10
Set-ItemProperty -Path $path -Name DumpFolder -Value "%LocalAppData%\CrashDumps"
```

### 5.9 ETW Tracing

```powershell
logman create trace TermTrace -p Microsoft-Windows-Terminal-App -o C:\traces\term.etl -ow
logman start TermTrace
# Reproduce the issue
logman stop TermTrace
logman delete TermTrace
```

Analyze in Windows Performance Analyzer or PerfView.

---

## 6. Performance

### 6.1 AtlasEngine (GPU Renderer)

AtlasEngine is the default renderer for Windows Terminal, written in C++20 with Direct3D 11 + Direct2D/DirectWrite:

- **Glyph atlas**: each unique `(glyph, attributes, cellSize)` tuple gets a tile in a GPU texture. Repeated glyphs reuse tiles, resulting in near-zero per-frame CPU work when text is unchanged.
- **Instanced quads**: the cell grid is drawn as a single instanced draw call per frame.
- **Damage tracking**: only dirty cells are re-rasterized.
- **DirectComposition**: composes onto the XAML visual tree without flicker.

### 6.2 Rendering Configuration

| Setting | Effect | When to Use |
|---------|--------|------------|
| `rendering.graphicsAPI: "direct3d11"` | Use Direct3D 11 backend (more performant) | Default; best for most GPUs |
| `rendering.graphicsAPI: "direct2d"` | Use Direct2D backend (more stable) | When experiencing D3D11 driver bugs |
| `rendering.disablePartialInvalidation: true` | Use FLIP_DISCARD swap chain, no dirty rectangles | When partial invalidation causes artifacts |
| `rendering.software: true` | Force WARP software rasterizer | Only when GPU drivers are broken |

> [!WARNING]
> Software rendering (`rendering.software: true`) is dramatically slower than GPU rendering. Use it only as a diagnostic tool or workaround for broken GPU drivers.

### 6.3 Font and Text Performance

| Setting | Impact |
|---------|--------|
| `font.builtinGlyphs` (default: `true`) | Uses built-in box-drawing glyphs for crisper rendering than font fallback. Keep enabled. |
| `font.features` / `font.axes` | Complex DWrite features increase shaping cost. Disable ligatures (`"liga": 0`) in performance-sensitive scenarios. |
| `compatibility.textMeasurement` | `"graphemes"` is most correct but slightly more expensive. `"console"` is fastest (legacy behavior). |

### 6.4 Buffer and Scrollback

`historySize` (default: 9001) is per-profile, measured in lines. RAM consumption scales with `historySize * visible_column_count`. Very large values (unlimited/`-1`) can consume significant memory for wide terminals with color-intensive output.

The scrollback uses RLE-compressed rows: runs of identical cells are compacted. TUI applications that update single cells at a time (e.g., `btop`) generate more row fragmentation than line-oriented output.

### 6.5 Animation and Visual Effects

| Setting | Effect |
|---------|--------|
| `disableAnimations: true` | Skip XAML transitions. Small improvement on slow hardware. |
| `experimental.retroTerminalEffect` | CRT effect re-renders every frame. Disable for performance. |
| `experimental.pixelShaderPath` | Custom shaders run every frame. Complex shaders tank performance. |

### 6.6 Diagnosing Slowness

1. Open Task Manager > Details. Compare CPU usage of `WindowsTerminal.exe` (renderer) and `OpenConsole.exe` (backend) to isolate the bottleneck.
2. Capture a GPU trace: `wpr -start GeneralProfile -start GPU` for 30 seconds.
3. Disable experimental features (`retroTerminalEffect`, `pixelShaderPath`).
4. Test software rendering -- if performance improves, update GPU drivers.
5. For SSH/WSL latency, use `ServerAliveInterval` and `ControlMaster` for SSH multiplexing.

> [!TIP]
> Issue #20113 documents a "slow for half a second then fast" regression related to render-batching heuristics interacting with certain GPU drivers. If you see this pattern, try toggling `rendering.disablePartialInvalidation`.

---

## 7. Security

### 7.1 Attack Surface

Windows Terminal is a desktop application with no listening sockets and no inbound network surface. The attack surface is limited to:

- **VT sequences from child processes** -- an attacker with shell access can inject OSC sequences.
- **Clipboard** -- any process with clipboard access can stage malicious pastes.
- **`settings.json` tampering** -- a local attacker can execute arbitrary commands via `startupActions`, `elevate`, or modified `commandline` on the default profile.
- **Fragments** -- per-machine fragments in `%ProgramData%` require admin to place but affect every user.
- **MSIX capabilities** -- `runFullTrust` means a compromised Terminal process has the user's full rights.

> [!CAUTION]
> An attacker who gains write access to `settings.json` can preload arbitrary commands via `startupActions` or inject profiles with `"elevate": true`. Restrict write access to the user's `LocalState` directory at the filesystem level.

### 7.2 Built-in Mitigations

| Mitigation | Setting | Description |
|-----------|---------|-------------|
| Multi-line paste warning | `warning.multiLinePaste: true` | Blocks the "copy from malicious webpage, paste executes command" vector. |
| Large paste warning | `warning.largePaste: true` | Prompts for very large pastes. |
| Trim paste | `trimPaste: true` | Strips trailing newlines to prevent forced execution of pasted lines. |
| OSC filtering | Various | Potentially dangerous OSCs (e.g., OSC 52 clipboard write) are gated by config or ignored by default. |
| Title suppression | `suppressApplicationTitle: true` | Prevents remote hosts from spoofing the tab title. |
| Read-only mode | `toggleReadOnlyMode` action | Prevents accidental input to a watched pane. |
| Admin shield | `showAdminShield: true` | Visual indicator when running elevated. |

### 7.3 Security-Sensitive Settings

| Setting | Risk | Recommendation |
|---------|------|----------------|
| `compatibility.allowOSC52` (default: `true`) | VT applications can write to the system clipboard via escape sequences. | Set to `false` in untrusted environments. |
| `compatibility.allowDECRQCRA` (default: `false`) | Allows remote applications to read a checksum of screen content. | Keep `false` unless specific applications require it. |
| `compatibility.input.forceVT` (default: `false`) | Forces legacy VT input encoding. May expose the terminal to input-injection attacks that modern encoding prevents. | Keep `false` unless required for compatibility. |
| `experimental.pixelShaderPath` | Loads arbitrary HLSL compiled at runtime. A compromised config could render a shader that causes GPU hangs. | Disable in hardened environments. |
| `elevate: true` (per-profile) | Every launch triggers UAC. Blind acceptance becomes an escalation vector. | Avoid deploying profiles with `elevate: true` in managed environments. |

### 7.4 Known Security Considerations

- **OSC 7 host trust** (Issue #20072): Terminal honors whatever hostname the shell reports. An attacker over SSH could report a misleading hostname. Verify the host before using `openCWD` over SSH.
- **OSC 8 hyperlinks**: clickable in the terminal. Hovering shows the target URL. Exercise caution clicking links from untrusted shells.
- **Pixel shaders**: `experimental.pixelShaderPath` compiles HLSL at runtime. Can cause GPU hangs or visual exploits.

> [!WARNING]
> Security vulnerabilities should be reported via `[email removed]` or the Microsoft Security Response Center (MSRC) portal at `https://msrc.microsoft.com`. Do not file security bugs as public GitHub issues.

### 7.5 Hardening Checklist

- [ ] Set `compatibility.allowOSC52: false` in fleet-wide fragments for untrusted environments
- [ ] Remove or avoid profiles with `elevate: true`
- [ ] Keep paste warnings enabled (`warning.multiLinePaste`, `warning.largePaste`)
- [ ] Set `autoMarkPrompts: true` for SOC visibility into prompt boundaries
- [ ] Disable Azure Cloud Shell if not needed: `"disabledProfileSources": ["Windows.Terminal.Azure"]`
- [ ] Lock down `%LocalAppData%\Packages\Microsoft.WindowsTerminal_*\LocalState` permissions
- [ ] Prefer Store distribution for automatic security updates
- [ ] Do not deploy custom pixel shaders in managed environments
- [ ] Subscribe to GitHub release RSS feed for prompt patching

---

## 8. Developer Internals

### 8.1 Repository Structure

| Path | Purpose |
|------|---------|
| `src/cascadia/` | All Windows Terminal (Cascadia) application code. Each subdirectory is a WinRT component or app project. |
| `src/cascadia/TerminalApp/` | Main application layer (84 files, 1.1M chars). TerminalPage, CommandPalette, NewTabMenu, AppCommandlineArgs. |
| `src/cascadia/TerminalControl/` | Reusable `TermControl` WinRT XAML control. |
| `src/cascadia/TerminalCore/` | Terminal state (text buffer, scrollback, selection, search). |
| `src/cascadia/TerminalSettingsModel/` | Settings types, JSON loader, `defaults.json`, profile generators. |
| `src/cascadia/TerminalSettingsEditor/` | Settings UI XAML pages. |
| `src/cascadia/TerminalConnection/` | Connection back-ends (ConPTY, Azure, Echo). |
| `src/cascadia/WindowsTerminal/` | Window management (17 files, 276K chars). `wWinMain`, `AppHost`, `WindowEmperor`, `IslandWindow`. |
| `src/cascadia/CascadiaPackage/` | MSIX manifest, jumplist definitions, icons. |
| `src/cascadia/Remoting/` | Cross-window communication (Monarch/Peasant model). |
| `src/cascadia/ShellExtension/` | Windows Shell extension ("Open in Terminal" context menu). |
| `src/cascadia/WpfTerminalControl/` | WPF control for .NET embedding. |
| `src/cascadia/fzf/` | Fuzzy finder integration (MIT, from Junegunn Choi / Simon Hauser). |
| `src/host/` | Console host, `conhost.exe` (92 files, 942K chars). |
| `src/server/` | Console API server (45 files, 258K chars). ALPC-based request handling. |
| `src/terminal/` | Shared VT parser, adapter, input translator. |
| `src/terminal/adapter/` | VT sequence dispatch, `ITermDispatch` implementation (23 files). |
| `src/terminal/parser/` | VT parser state machine. |
| `src/terminal/input/` | Input encoding and translation. |
| `src/renderer/` | Rendering engines: AtlasEngine (GPU), GDI, UIA, WDDM. |
| `src/buffer/` | Text buffer primitives shared by host and Cascadia. |
| `src/types/` | Common types (coords, rects, colors, viewport). |
| `src/til/` | Terminal Implementation Library (custom containers, threading primitives). |
| `src/inc/` | Shared headers (14 files, 67K chars). |
| `src/tsf/` | Text Services Framework / IME support (6 files, 37K chars). |
| `src/propslib/` | Properties library, registry settings (11 files, 79K chars). |
| `src/propsheet/` | Console properties dialog (29 files, 262K chars). |
| `src/winconpty/` | ConPTY API implementation (5 files, 31K chars). |
| `src/interactivity/` | Input/output interaction layers (Win32, OneCore). |
| `src/tools/` | Developer tools: ConsoleBench, ColorTool, echokey, fontlist, integrity, vtpipeterm, RenderingTests, and more. |
| `src/audio/` | MIDI support. |
| `dep/` | Build dependencies (telemetry, Console, NT, Win32K, vcpkg overlay). |
| `oss/` | Vendored open-source components (Chromium numerics, stb, pcg, interval_tree, wyhash, fzf). |
| `doc/` | Documentation and specs. `STYLE.md`, `ORGANIZATION.md`, `EXCEPTIONS.md`, `WIL.md`. |
| `doc/cascadia/` | `profiles.schema.json` (109K chars, the authoritative settings schema). |
| `samples/` | ConPTY sample applications (EchoCon, GUIConsole, MiniTerm, PixelShaders, ReadConsoleInputStream). |
| `tools/` | Release engineering and test tools. `OpenConsole.psm1`, `razzle.cmd`. |
| `scratch/` | Scratch/test island app (ScratchIslandApp). |
| `res/` | Resources: fonts (Cascadia Code), icons, images. |
| `policies/` | Group Policy ADMX templates (`policies/en-US/`). |

### 8.2 Key Files

| File | Significance |
|------|-------------|
| `OpenConsole.slnx` | Top-level Visual Studio solution. Open this to build anything. |
| `src/cascadia/TerminalSettingsModel/defaults.json` | Shipped defaults: every key binding, color scheme, and profile default. |
| `doc/cascadia/profiles.schema.json` | 3,300+ line JSON schema, the contract for `settings.json`. |
| `src/cascadia/WindowsTerminal/main.cpp` | Process entry (`wWinMain`). Dispatches to `WindowEmperor::HandleCommandlineArgs`. |
| `src/cascadia/TerminalApp/AppCommandlineArgs.cpp` | Parses every `wt.exe` argument (CLI11-based). |
| `src/cascadia/TerminalApp/TerminalPage.xaml` | Top-level UI: tab/pane hierarchy, action dispatch. |
| `vcpkg.json` | C++ dependency manifest (manifest mode). |
| `.config/configuration.winget` | Developer box setup configuration. |

### 8.3 Build from Source

#### Clone

```powershell
git clone --recursive https://github.com/microsoft/terminal.git
cd terminal
```

#### Build via PowerShell

```powershell
Import-Module .\tools\OpenConsole.psm1
Set-MsBuildDevEnvironment
Invoke-OpenConsoleBuild
```

| Command | Effect |
|---------|--------|
| `Invoke-OpenConsoleBuild -Configuration Release -Platform x64` | Release x64 build |
| `Invoke-OpenConsoleBuild -Target Rebuild` | Full rebuild |
| `Invoke-OpenConsoleBuild -Target Clean` | Clean |
| `Invoke-OpenConsoleTests` | Run unit tests |

#### Build via cmd

```shell
.\tools\razzle.cmd
bcz
```

#### Build in Visual Studio

1. Open `OpenConsole.slnx`.
2. Select **x64** or **x86** platform (no **Any CPU** -- native C++).
3. Right-click **CascadiaPackage** and set as Startup Project.
4. Set debug properties: "Application process" and "Background task process" to **Native Only**.
5. Press F5.

> [!WARNING]
> Running `WindowsTerminal.exe` directly outside of VS deploy will not work. The app requires MSIX identity for many APIs and must come up through the packaged activation path. See Issues #926 and #4043.

#### Build Artifacts

Output goes to `bin\<Platform>\<Configuration>\`:

- `WindowsTerminal.exe` -- the shell binary
- `OpenConsole.exe` -- locally built `conhost.exe`
- `CascadiaPackage.msix` -- the MSIX bundle
- `TerminalApp.dll`, `TerminalControl.dll`, `TerminalSettingsModel.dll` -- WinRT component DLLs

#### Local Deployment

```powershell
Add-AppxPackage -Register .\bin\x64\Debug\CascadiaPackage\AppxManifest.xml
start shell:AppsFolder\WindowsTerminalDev_8wekyb3d8bbwe!App
```

### 8.4 WinRT Components

| Component | Purpose |
|-----------|---------|
| `Microsoft.Terminal.Control` | Reusable `TermControl` XAML control |
| `Microsoft.Terminal.Core` | Pure terminal state (no UI, no XAML) |
| `Microsoft.Terminal.Settings.Model` | Settings types and JSON I/O |
| `Microsoft.Terminal.Settings.Editor` | Settings UI XAML pages |
| `Microsoft.Terminal.TerminalConnection` | `ITerminalConnection` + shipped implementations |
| `Microsoft.Terminal.UI` | Shared XAML resources |

All emit `.winmd` files that downstream apps can reference.

### 8.5 ConPTY API

The **ConPTY** (Pseudo Console) API enables modern terminals to host legacy Win32 console programs. The API surface consists of three functions:

- `CreatePseudoConsole(size, hInput, hOutput, flags, phPC)` -- creates a pseudo console attached to input/output pipes.
- `ResizePseudoConsole(hPC, size)` -- resizes the pseudo console.
- `ClosePseudoConsole(hPC)` -- tears down the pseudo console.

After creating a ConPTY, attach it to a child process via `UpdateProcThreadAttribute(PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE)`. The child's stdin/stdout/stderr flow through the ConPTY pipes.

**OpenConsole.exe discovery**: Windows Terminal ships `OpenConsole.exe` (built from the same source as `conhost.exe`) alongside its binary. At launch, Terminal looks for `OpenConsole.exe` side-by-side with the current process. If not found, it falls back to the system `conhost.exe`. Architecture detection selects x64, ARM64, or x86 variants as appropriate.

### 8.6 VT Sequence Support

The VT parser (`src/terminal/parser/`) implements:

- CSI (parameter-bearing) sequences
- OSC (string) sequences with BEL or ST terminators
- DCS (device control strings)
- Sixel (in development)
- 256-color and 24-bit (`38;2;r;g;b`) SGR
- Mouse reporting (modes 1000, 1002, 1003, 1006, 1015)

The script `Build-SupportedSequenceIndex.ps1` scans the `ITermDispatch` interface and both `adaptDispatch` (ConHost) and `terminalDispatch` (Terminal) implementations to generate a compatibility matrix of supported sequences.

### 8.7 Code Patterns and Conventions

#### Language and Style

- **C++20** with Microsoft extensions. Compiled `/W4 /WX` (no warnings).
- **Unicode everywhere**: `wchar_t`, `std::wstring`, Windows "W" APIs.
- **STL containers** preferred over home-grown. WIL (Windows Implementation Libraries) for handle management.
- **`gsl::span`, `gsl::not_null`**: Guidelines Support Library for safer pointer handling.
- **No raw `new`/`delete`** outside RAII wrappers. Use `std::make_unique`, WIL smart handles, `com_ptr`.
- 4-space indent, LF line endings, `#pragma once`.
- PascalCase types, camelCase functions, `m_` prefix for members, `s_` for statics, `g_` for globals.

#### Key Patterns

- **C++/WinRT** for WinUI interop. All Cascadia components are WinRT classes.
- **XAML Islands** for hosting WinUI 2 controls in a Win32 window.
- **`winrt::auto_revoke`** for event handler lifetime management (prevents dangling event subscriptions).
- **`ThrottledFunc`** for debouncing UI updates (prevents render thrashing during rapid state changes).
- **`til::`** namespace for custom containers and threading primitives (`shared_mutex`, `latch`, `throttled_func`).
- **`wil::`** (Windows Implementation Libraries) for resource management (`unique_handle`, `com_ptr`, error macros).

#### Exception Strategy

- Core libraries (buffer, renderer, parser) are designed to be exception-hostile; many constructors are `noexcept`.
- Cascadia (new code) uses exceptions freely.
- WIL helpers: `LOG_IF_WIN32_BOOL_FALSE`, `RETURN_IF_FAILED`, `THROW_IF_FAILED` (see `doc/EXCEPTIONS.md`).

#### XAML Conventions

- Use `XamlStyler` (CI validates formatting via `XamlStyler.json` at repo root).
- Prefer `{ThemeResource}` over `{StaticResource}` for theme-varying values.
- Centralize styles in `CommonResources.xaml` or page-level `ResourceDictionary`.

### 8.8 Testing

#### Test Suites

| Suite | Location | Type | Runs On |
|-------|----------|------|---------|
| `UnitTests_*` | `src/*/ut_*` | Native unit tests (TAEF) | Every PR |
| `LocalTests_*` | `src/cascadia/ut_app/` etc. | Requires XAML host | PR + CI with XAML support |
| `FeatureTests` | `src/cascadia/ut_*/` | End-to-end action tests | Nightly |
| `HostAndVTTests` | `src/host/ut_*` | Console host + VT parser | Every PR |
| UIA Tests | `src/cascadia/WindowsTerminal_UIATests/` | UI Automation tests | CI |
| Host UIA Tests | `src/host/ft_uia/` | Console host UIA tests | CI |
| Fuzzer | `src/terminal/parser/ft_fuzzwrapper/` | VT parser fuzzing | Nightly |
| ConsoleBench | `src/tools/ConsoleBench/` | Benchmark tool | Manual |

#### Running Tests

```powershell
Import-Module .\tools\OpenConsole.psm1
Set-MsBuildDevEnvironment
Invoke-OpenConsoleTests
# Filter by test name:
Invoke-OpenConsoleTests -Name *UnitTests_TerminalCore*
```

Tests use **TAEF** (`te.exe`), Microsoft's native test framework.

### 8.9 Contributing

1. Read `CONTRIBUTING.md` in the repo root.
2. Browse issues labeled `help wanted` on GitHub.
3. Sign the Microsoft Contributor License Agreement (CLA) -- a bot guides you on first PR.
4. Fork, branch off `main`, PR against `main`.

#### Pull Request Checklist

- [ ] Linked to an issue (or use `Spec:` prefix for new features)
- [ ] Unit tests added or updated
- [ ] `Resources.resw` updated for new user-visible strings
- [ ] `defaults.json` updated if adding/renaming actions
- [ ] `NOTICE.md` updated if adding a dependency
- [ ] CI green: `UnitTests_*`, `LocalTests_*`, policy check, AzDO pipeline
- [ ] CLA signed

#### Adding a New Action

1. Add the action name and args struct to `ActionArgs.idl` and `ActionArgs.h` in `TerminalSettingsModel`.
2. Update `ActionAndArgs::FromJson` to deserialize it.
3. Implement the handler in `TerminalPage.cpp`.
4. Add a default entry in `defaults.json` with a `Terminal.*` id.
5. Optionally bind it in default keybindings.
6. Add a localized command-name string to `Resources.resw`.
7. Add unit tests in `UnitTests_SettingsModel` and action-level tests in `UnitTests_Control`.

#### Hosting TerminalControl in Your Own App

```xml
<Window xmlns:term="using:Microsoft.Terminal.Control">
    <term:TermControl x:Name="Terminal" />
</Window>
```

```cpp
auto settings = winrt::make<MyControlSettings>();
auto connection = winrt::make<MyConnection>();
Terminal().Initialize(settings, connection);
```

`MyControlSettings` implements `IControlSettings` (font, colors, cursor, padding). `MyConnection` implements `ITerminalConnection` (`Start`, `WriteInput`, `Resize`, `Close`). This is how Visual Studio integrates a Terminal pane.

### 8.10 Release Process

| Channel | Cadence | Gate |
|---------|---------|------|
| Preview | ~3 weeks | None (feature-flagged) |
| Stable | ~6 weeks | Promoted from a baked Preview |
| Canary | Nightly | None (automated from `main`) |

**Version scheme:** `1.x.y.z` where `1` = product generation, `x` = feature train (bumped per Preview), `y` = build (CI-set), `z` = hotfix.

### 8.11 Potential Improvements

From source comments and open issues:

| Issue | Description |
|-------|-------------|
| GH#12190, GH#12169 | Elevated window handoff issues with monarch/peasant model |
| GH#11561 | Window visibility during initialization |
| GH#10583 | Invisible border positioning |
| GH#19806 | Refactor `IconPathConverter::IconWUX()` to not set icon size as side-effect |
| GH#13792 | Full `modifyOtherKeys` support for `Tab`/`Ctrl+I` distinction |
| GH#17000 | Settings UI Rejuvenation (long-running modernization effort) |

**Technical debt:**

- `AppLogic` singleton initialization is split across many lazily-loaded helpers.
- `NewTerminalArgs` + startup-action JSON represent two paths for the same data; consolidation is on the wish list.
- `LocalTests` initialization race (repaired in #19610/#14623) but the pattern remains fragile.
- WinUI 3 migration is incremental -- the app is being lifted off WinUI 2 / XAML Islands.

---

## 9. Integration Points

### 9.1 ConPTY API (Terminal Embedding)

Any application can host a terminal pane using the ConPTY API. Create pipes, call `CreatePseudoConsole`, spawn a child process attached to the ConPTY, and read/write VT sequences on the pipes. See `samples/ConPTY/` for complete C++ and C# examples (EchoCon, GUIConsole, MiniTerm).

### 9.2 Shell Extension

`src/cascadia/ShellExtension/` implements the Windows Shell extension that adds "Open in Terminal" to the File Explorer context menu. Registered via the MSIX package manifest.

### 9.3 Fragment Extensions

Third-party applications can contribute profiles and color schemes by placing JSON files in the Fragments directory (see section 3.11). No code is required. Examples include Git for Windows, Ubuntu WSL, and oh-my-posh.

### 9.4 Remoting (Cross-Window Communication)

`src/cascadia/Remoting/` implements the Monarch/Peasant model:

- Monarch process registers globally and handles cross-window commands.
- Peasant processes delegate operations like `wt -w <name>` to the monarch.
- Used for: tab moves between windows, `globalSummon`, `quakeMode`, `identifyWindows`.

### 9.5 WPF Terminal Control

`src/cascadia/WpfTerminalControl/` provides a .NET-compatible control for embedding terminal functionality in WPF applications. Used in the `WpfTerminalTestNetCore` test project.

### 9.6 Azure Cloud Shell Connection

`AzureConnection` in `TerminalConnection` establishes a WebSocket session to Azure Cloud Shell. Users authenticate through the Terminal UI. Disable this source via `"disabledProfileSources": ["Windows.Terminal.Azure"]`.

### 9.7 Custom Pixel Shaders

Write an HLSL 5.0 pixel shader that processes the Terminal output texture:

```hlsl
Texture2D shaderTexture;
SamplerState samplerState;

cbuffer PixelShaderSettings : register(b0) {
    float  Time;
    float  Scale;
    float2 Resolution;
    float4 Background;
};

float4 main(float4 pos : SV_POSITION, float2 uv : TEXCOORD) : SV_TARGET {
    return shaderTexture.Sample(samplerState, uv);
}
```

Set `experimental.pixelShaderPath` per profile. The `samples/PixelShaders/` directory contains example shaders. Shaders run every frame and can significantly impact performance.

### 9.8 Custom Connection Back-ends

Implement `ITerminalConnection` in a WinRT component, then reference it via a fragment profile with `"connectionType": "{your-guid-here}"`. This requires shipping a `.winmd` and registering an activatable class in the MSIX manifest. Most custom scenarios are better served by a ConPTY connection wrapping a proxy process.

### 9.9 Shell Integration Extensions

Shells can integrate with Terminal by emitting OSC escape sequences (see section 5.5). This enables prompt marks, scroll-to-mark, CWD-aware tab duplication, quick-fix suggestions, and taskbar progress. Custom shells (fish, nushell, xonsh) can source an OSC-emitting prompt snippet to gain these features.

---

## Appendix A -- Action IDs

Every action ID from `defaults.json`, usable in `keybindings` and `newTabMenu` entries:

**Application:** `Terminal.CloseWindow`, `Terminal.ToggleFullscreen`, `Terminal.ToggleFocusMode`, `Terminal.ToggleAlwaysOnTop`, `Terminal.OpenNewTabDropdown`, `Terminal.OpenSettingsUI`, `Terminal.OpenSettingsFile`, `Terminal.OpenDefaultSettingsFile`, `Terminal.OpenSettingsDirectory`, `Terminal.FindText`, `Terminal.FindNextMatch`, `Terminal.FindPrevMatch`, `Terminal.ToggleShaderEffects`, `Terminal.OpenTabColorPicker`, `Terminal.RenameTab`, `Terminal.OpenTabRenamer`, `Terminal.ToggleCommandPalette`, `Terminal.IdentifyWindow`, `Terminal.OpenWindowRenamer`, `Terminal.QuakeMode`, `Terminal.OpenSystemMenu`, `Terminal.Quit`, `Terminal.RestoreLastClosed`, `Terminal.OpenAboutDialog`, `Terminal.OpenTasks`, `Terminal.QuickFix`, `Terminal.Suggestions`, `Terminal.OpenCWD`.

**Tabs:** `Terminal.CloseOtherTabs`, `Terminal.CloseTabsAfter`, `Terminal.MoveTabForward`, `Terminal.MoveTabBackward`, `Terminal.OpenNewTab`, `Terminal.OpenNewWindow`, `Terminal.OpenNewTabProfile0` through `Terminal.OpenNewTabProfile8`, `Terminal.DuplicateTab`, `Terminal.NextTab`, `Terminal.PrevTab`, `Terminal.SwitchToTab0` through `Terminal.SwitchToTab7`, `Terminal.SwitchToLastTab`, `Terminal.MoveTabToNewWindow`.

**Panes:** `Terminal.CloseOtherPanes`, `Terminal.ClosePane`, `Terminal.SplitPaneUp`, `Terminal.SplitPaneDown`, `Terminal.SplitPaneLeft`, `Terminal.SplitPaneRight`, `Terminal.DuplicatePaneDown`, `Terminal.DuplicatePaneRight`, `Terminal.DuplicatePaneAuto`, `Terminal.ResizePaneDown`, `Terminal.ResizePaneLeft`, `Terminal.ResizePaneRight`, `Terminal.ResizePaneUp`, `Terminal.MoveFocusDown`, `Terminal.MoveFocusLeft`, `Terminal.MoveFocusRight`, `Terminal.MoveFocusUp`, `Terminal.MoveFocusPrevious`, `Terminal.MoveFocusPreviousInOrder`, `Terminal.MoveFocusNextInOrder`, `Terminal.MoveFocusFirst`, `Terminal.MoveFocusParent`, `Terminal.MoveFocusChild`, `Terminal.SwapPaneDown`, `Terminal.SwapPaneLeft`, `Terminal.SwapPaneRight`, `Terminal.SwapPaneUp`, `Terminal.SwapPanePrevious`, `Terminal.SwapPanePreviousInOrder`, `Terminal.SwapPaneNextInOrder`, `Terminal.SwapPaneFirst`, `Terminal.ToggleBroadcastInput`, `Terminal.TogglePaneZoom`, `Terminal.ToggleSplitOrientation`, `Terminal.ToggleReadOnlyMode`, `Terminal.EnableReadOnlyMode`, `Terminal.DisableReadOnlyMode`, `Terminal.MovePaneToTab0` through `Terminal.MovePaneToTab8`, `Terminal.MovePaneToNewWindow`, `Terminal.RestartConnection`, `Terminal.OpenSnippetsPane`.

**Clipboard:** `Terminal.CopyToClipboard`, `Terminal.PasteFromClipboard`, `Terminal.SelectAll`, `Terminal.ToggleMarkMode`, `Terminal.ToggleBlockSelection`, `Terminal.SwitchSelectionEndpoint`, `Terminal.ExpandSelectionToWord`, `Terminal.ShowContextMenu`.

**Scrollback:** `Terminal.ScrollDown`, `Terminal.ScrollDownPage`, `Terminal.ScrollUp`, `Terminal.ScrollUpPage`, `Terminal.ScrollToTop`, `Terminal.ScrollToBottom`, `Terminal.ClearBuffer`, `Terminal.ExportBuffer`.

**Visual:** `Terminal.IncreaseFontSize`, `Terminal.DecreaseFontSize`, `Terminal.ResetFontSize`.

**Misc:** `Terminal.SearchWeb`.

---

## Appendix B -- Default Key Bindings

| Keys | Action |
|------|--------|
| `alt+f4` | `Terminal.CloseWindow` |
| `alt+enter` / `f11` | `Terminal.ToggleFullscreen` |
| `ctrl+shift+space` | `Terminal.OpenNewTabDropdown` |
| `ctrl+,` | `Terminal.OpenSettingsUI` |
| `ctrl+shift+,` | `Terminal.OpenSettingsFile` |
| `ctrl+alt+,` | `Terminal.OpenDefaultSettingsFile` |
| `ctrl+shift+f` | `Terminal.FindText` |
| `ctrl+shift+p` | `Terminal.ToggleCommandPalette` |
| `win+sc(41)` | `Terminal.QuakeMode` |
| `alt+space` | `Terminal.OpenSystemMenu` |
| `ctrl+shift+period` | `Terminal.Suggestions` |
| `ctrl+shift+t` | `Terminal.OpenNewTab` |
| `ctrl+shift+n` | `Terminal.OpenNewWindow` |
| `ctrl+shift+1` through `ctrl+shift+9` | `Terminal.OpenNewTabProfile0` through `Terminal.OpenNewTabProfile8` |
| `ctrl+shift+d` | `Terminal.DuplicateTab` |
| `ctrl+tab` / `ctrl+shift+tab` | `Terminal.NextTab` / `Terminal.PrevTab` |
| `ctrl+alt+1` through `ctrl+alt+8` | `Terminal.SwitchToTab0` through `Terminal.SwitchToTab7` |
| `ctrl+alt+9` | `Terminal.SwitchToLastTab` |
| `ctrl+shift+w` | `Terminal.ClosePane` |
| `alt+shift+-` | `Terminal.DuplicatePaneDown` |
| `alt+shift+plus` | `Terminal.DuplicatePaneRight` |
| `alt+shift+down/left/right/up` | `Terminal.ResizePaneDown/Left/Right/Up` |
| `alt+down/left/right/up` | `Terminal.MoveFocusDown/Left/Right/Up` |
| `ctrl+alt+left` | `Terminal.MoveFocusPrevious` |
| `ctrl+shift+c` / `ctrl+insert` / `enter` | `Terminal.CopyToClipboard` |
| `ctrl+shift+v` / `shift+insert` | `Terminal.PasteFromClipboard` |
| `ctrl+shift+a` | `Terminal.SelectAll` |
| `ctrl+shift+m` | `Terminal.ToggleMarkMode` |
| `menu` | `Terminal.ShowContextMenu` |
| `ctrl+shift+down/up` | `Terminal.ScrollDown/Up` |
| `ctrl+shift+pgdn/pgup` | `Terminal.ScrollDownPage/UpPage` |
| `ctrl+shift+home/end` | `Terminal.ScrollToTop/Bottom` |
| `ctrl+shift+k` | `Terminal.ClearBuffer` |
| `ctrl+plus` / `ctrl+numpad_plus` | `Terminal.IncreaseFontSize` |
| `ctrl+minus` / `ctrl+numpad_minus` | `Terminal.DecreaseFontSize` |
| `ctrl+0` / `ctrl+numpad_0` | `Terminal.ResetFontSize` |

---

## Appendix C -- Built-in Color Schemes

Campbell, Campbell Powershell, Vintage, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, Dark+, VSCode Dark Modern, VSCode Light Modern, CGA, IBM 5153, Dimidium, Ottosson.

Exact foreground/background/ANSI values for each scheme can be inspected in `defaults.json` or via the User Guide color reference.

---

## Appendix D -- File Locations

| Purpose | Path |
|---------|------|
| Settings (Stable) | `%LocalAppData%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json` |
| Settings (Preview) | `%LocalAppData%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\settings.json` |
| Settings (Canary) | `%LocalAppData%\Packages\Microsoft.WindowsTerminalCanary_8wekyb3d8bbwe\LocalState\settings.json` |
| Settings (Portable) | `<install root>\settings\settings.json` |
| Per-user fragments | `%LocalAppData%\Microsoft\Windows Terminal\Fragments\<publisher>\<app>\*.json` |
| Per-machine fragments | `%ProgramData%\Microsoft\Windows Terminal\Fragments\<publisher>\<app>\*.json` |
| Window layout state | `<LocalState>\state.json` |
| Jumplist | `<LocalState>\WindowsTerminalJumplist.json` |
| Crash dumps (if enabled) | `%LocalAppData%\CrashDumps\WindowsTerminal*.dmp` |
| Logs | ETW only (no file logs) |

---

_Generated May 2026 from microsoft/terminal at 7a83c0f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._