deep-dive

Main Components of Windows Terminal: A Deep Dive into the Architecture

February 26, 2026 microsoft/terminal ↗

Windows Terminal consists of five loosely-coupled layers—the Cascadia UI frontend, Terminal Control, Terminal Core engine, Connection abstraction layer, and Settings Model—each implemented as separate libraries in the src/cascadia/ directory.

The main components of Windows Terminal are organized into a modular, test-driven architecture that separates presentation from business logic. This design allows the terminal to support multiple shells—such as PowerShell, WSL, and CMD—while maintaining high performance and extensibility. Each layer is compiled into its own static library (e.g., terminalcore-lib, terminalconnection-lib) and exercised by dedicated unit tests.

1. Cascadia UI Layer: The WinUI 3 Frontend

The Cascadia layer provides the native WinUI 3 interface that users interact with directly. It manages the application lifecycle, window chrome, tabbed interface, and the settings editor.

Window Management and Hosting

The executable entry point initializes the application framework and creates the main window host. The IslandWindow and NonClientIslandWindow classes handle the custom title bar and content island hosting.

// src/cascadia/WindowsTerminal/main.cpp
int wmain(int argc, wchar_t** argv)
{
    // Initialize COM and the Windows Terminal application
    winrt::init_apartment();
    
    // WindowEmperor manages the singleton application instance
    auto emperor = winrt::make_self<WindowEmperor>();
    return emperor->Run(argc, argv);
}

Key source files:

Tab and Pane Orchestration

The TerminalApp library contains the TerminalPage class, which manages the tabbed interface and pane splitting logic. It coordinates between the UI shell and the individual terminal controls.

2. Terminal Control: The UI-to-Core Bridge

Terminal Control (TermControl) is the XAML/WinUI control that hosts the rendering surface and forwards user interactions—such as keyboard input, mouse events, and drag-and-drop—to the core engine. It handles Direct2D/DirectWrite rendering, text selection visualization, and scrolling.

The control acts as a glue layer between the declarative UI and the imperative core logic:

// src/cascadia/TerminalControl/TermControl.cpp
void TermControl::SetTerminal(std::shared_ptr<ITerminalApi> terminal)
{
    _terminal = terminal;
    
    // Attach the renderer to the swap chain panel
    _renderer = std::make_unique<Renderer>(
        _terminal.get(),
        _renderEngine.get(),
        _swapChainPanel);
}

Key source files:

3. Terminal Core: The VT Engine and Screen Buffer

The Terminal Core is the engine that implements VT sequence parsing, maintains the screen buffer, handles selection state, and manages clipboard operations. It is deliberately UI-agnostic, allowing it to be unit-tested in isolation without a graphics context.

VT Sequence Parsing

The core parses ANSI/VT escape sequences to manipulate cursor position, colors, and buffer contents. The Terminal class exposes the public API consumed by the control layer.

// src/cascadia/TerminalCore/Terminal.cpp
void Terminal::Write(std::wstring_view text)
{
    // Parse VT sequences and update the buffer
    _stateMachine.ProcessString(text);
}

Selection and Rendering Data

Selection logic is separated into TerminalSelection, while rendering data structures are managed by TerminalRenderData. This separation allows the renderer to query the core for visible text ranges without accessing internal buffer details directly.

Key source files:

4. Terminal Connection: Abstracting Back-Ends

The Terminal Connection layer provides an abstraction over the various back-ends that supply byte streams, including ConPTY (Windows Pseudo Console), WSL, SSH, and Telnet. This layer hides platform-specific plumbing from the UI and core, allowing the terminal to treat all shells uniformly.

ConPTY Integration

The ConPTYConnection class implements the connection interface for Windows native pseudo-terminals, bridging the core terminal with Windows Console APIs.

// Conceptual usage of the connection layer
auto conpty = winrt::make_self<TerminalConnection::ConPTYConnection>();
conpty->Create(L"C:\\Windows\\System32\\cmd.exe");

// Attach to terminal core
terminal->Initialize(conpty.get());

Key source files:

5. Settings Model and Editor: Configuration Management

The Settings Model implements a JSON-driven schema that describes profiles, color schemes, key bindings, and UI preferences. The CascadiaSettings class loads defaults.json and user settings, validates the schema, and provides typed access to configuration values.

The Settings Editor is a WinUI 3 XAML page that binds to the model, allowing users to modify the JSON graphically without hand-editing files.

// Reading configuration values
auto settings = winrt::make_self<CascadiaSettings>();
settings->LoadDefaults();  // reads defaults.json + user settings.json
auto font = settings->GetDefaultAppearance().FontFace();  // "Cascadia Code"

Key source files:

How the Components Interact

The main components of Windows Terminal communicate through well-defined interfaces that maintain separation of concerns:

  1. Windows Terminal (layer 1) creates a TerminalPage → each tab owns a TermControl (layer 2)
  2. The control holds a reference to a Terminal object (layer 3) and a TerminalConnection (layer 4)
  3. The UI reads/writes settings via the CascadiaSettings model (layer 5)
  4. Communication from the UI to the core flows through the ITerminalApi COM-style interface, implemented by TerminalApi in the core

This architecture allows each layer to be developed and tested independently. For example, the TerminalCore can parse VT sequences without a graphics context, while the TerminalConnection can be mocked to test UI behavior without spawning real shells.

Summary

  • Cascadia UI Layer: The WinUI 3 executable that manages windows, tabs, and the settings editor, implemented in src/cascadia/WindowsTerminal/ and src/cascadia/TerminalApp/.
  • Terminal Control: The XAML control that bridges user input and rendering with the core engine, located in src/cascadia/TerminalControl/.
  • Terminal Core: The UI-agnostic VT parser and screen buffer engine, found in src/cascadia/TerminalCore/.
  • Terminal Connection: The abstraction layer for ConPTY, WSL, and SSH back-ends, implemented in src/cascadia/TerminalConnection/.
  • Settings Model: The JSON-driven configuration system with a graphical editor, located in src/cascadia/TerminalSettingsModel/ and src/cascadia/TerminalSettingsEditor/.

Frequently Asked Questions

What programming languages are used in Windows Terminal?

Windows Terminal is primarily written in C++ using C++/WinRT for Windows Runtime component development. The UI layer uses XAML with WinUI 3 controls. Some build scripts and tooling use PowerShell and Python, but the core terminal engine, connection layer, and settings model are all native C++ code compiled into static libraries.

How does Windows Terminal handle different shell types like WSL and PowerShell?

Windows Terminal uses the Terminal Connection layer to abstract shell-specific implementations. For native Windows shells like PowerShell and CMD, it uses ConPTYConnection which interfaces with the Windows ConPTY API. For WSL, it uses a specialized WSLConnection class that handles the Linux subsystem bridge. All connections implement the same ITerminalConnection interface, allowing the UI and core engine to treat every shell uniformly regardless of the underlying transport mechanism.

Is the Windows Terminal core engine reusable in other applications?

Yes, the Terminal Core is deliberately UI-agnostic and designed for reuse. It exposes a COM-style interface (ITerminalApi) that any host application can implement. Because the core has no dependencies on WinUI or XAML, it can be unit-tested in isolation and embedded into other Windows applications that need VT sequence parsing and screen buffer management without pulling in the full Windows Terminal UI layer.

Where are the unit tests located for these components?

Each major component has a corresponding unit test project located under src/*/UnitTests_* directories. For example, the Terminal Core tests are in src/cascadia/UnitTests_TerminalCore/, the Connection tests are in src/cascadia/UnitTests_TerminalConnection/, and the Settings Model tests are in src/cascadia/UnitTests_SettingsModel/. These test suites validate the UI-agnostic business logic without requiring the full application to be running.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →