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.

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

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

1.4 Rendering Pipeline

1.5 Terminal Adapter and Parser

1.6 Supporting Libraries

1.7 External Dependencies (vendored in oss/)

1.8 vcpkg Dependencies (build-time)

1.9 Technology Stack

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:

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

2.2 Build-Time (Developer Box)

The fastest way to set up a developer box:

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

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

{
  "$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

UI Settings

Clipboard and Selection Settings

Warning and Confirmation Settings

Rendering Settings

Compatibility Settings

Experimental Global Settings

Profile Source Control

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

Appearance

Background Image

Font

Note

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

Cursor

Input and Scrolling

Bell

Shell Integration

Compatibility (Per-Profile)

Drag and Drop

Lifecycle

Nested Appearance

Experimental (Per-Profile)

3.5 Color Schemes

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

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

WindowTheme

TabTheme

TabRowTheme

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:

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

Complete Action Reference (76 Actions)

Tab Management:

Pane Management:

Window Management:

Clipboard and Selection:

Scrollback:

Application:

3.8 Keybindings

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

{ "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:

[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:

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:

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:

{
  "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

All three Store packages coexist on a machine without conflict.

4.2 Enterprise MSIX Deployment

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:

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

{
  "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

# 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:

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:

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:

Capabilities that depend on shell integration:

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):

$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):

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):

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:

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

Audit what Terminal emits locally:

# 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

5.8 Crash Dump Configuration

To enable local crash dumps:

$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

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

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

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

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

7.3 Security-Sensitive Settings

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

8.2 Key Files

8.3 Build from Source

Clone

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

Build via PowerShell

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

Build via cmd

.\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

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

8.4 WinRT Components

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

Running Tests

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

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

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

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:

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:

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

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