What is ConPTY in Windows Terminal? The Windows Pseudo-Console API Explained

ConPTY (Pseudo-Console) is a Windows 10/Server 2019 API that enables applications to create headless console sessions and communicate via anonymous pipes, allowing Windows Terminal to host traditional command-line tools in modern tabbed interfaces without legacy console window constraints.

ConPTY revolutionized terminal emulation on Windows by providing a bridge between legacy console applications and modern UI frameworks. In the microsoft/terminal repository, ConPTY serves as the foundational layer that powers every tab, enabling processes like PowerShell, WSL, and cmd.exe to run inside Windows Terminal's hardware-accelerated interface while maintaining full compatibility with standard console APIs.

Understanding the ConPTY Architecture

The ConPTY implementation in Windows Terminal consists of three distinct layers that handle everything from low-level handle management to high-level UI integration.

Low-Level ConPTY Library

At the foundation, the low-level ConPTY library wraps the native Windows APIs CreatePseudoConsole, ResizePseudoConsole, and ShowHidePseudoConsole. This layer manages the three critical handles defined in src/winconpty/winconpty.h:

• hSignal – Anonymous pipe for out-of-band control messages (resize, show/hide, clear)
• hPtyReference – Reference handle keeping the underlying conhost.exe process alive
• hConPtyProcess – Handle to the conhost.exe process hosting the pseudo-console

The implementation in src/winconpty/winconpty.cpp provides thin C-style wrappers like ConptyCreatePseudoConsoleAsUser that the rest of the codebase consumes.

ConPTY Connection Layer

The ConPTY connection layer implements the ITerminalConnection interface used by Windows Terminal's UI. Defined in src/cascadia/TerminalConnection/ConptyConnection.h and implemented in the matching .cpp file, this layer:

• Manages the pseudo-console lifecycle from creation to destruction
• Launches child processes (cmd, PowerShell, WSL) with the appropriate attribute lists
• Forwards input/output between the UI and the pseudo-console pipes
• Handles resize and focus events via the signal pipe
• Propagates VT-sequence signals back to the host

Sample Implementations

For developers building custom applications, the repository provides a managed wrapper in samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs. This sample demonstrates creating pipes, starting a pseudo-console, and reading/writing VT-aware streams without requiring the full Windows Terminal UI framework.

Creating and Managing Pseudo-Consoles

The process of establishing a ConPTY session involves several precise steps to ensure proper handle inheritance and process isolation.

Initializing the Pseudo-Console

Windows Terminal creates a pseudo-console by calling ConptyCreatePseudoConsoleAsUser from src/winconpty/winconpty.h:

HRESULT WINAPI ConptyCreatePseudoConsoleAsUser(
    HANDLE hToken, COORD size,
    HANDLE hInput, HANDLE hOutput,
    DWORD dwFlags, HPCON* phPC);

This function returns an HPCON handle and populates a PseudoConsole structure containing the three critical handles. The hToken parameter allows running the console under a specific user context, while hInput and hOutput are the anonymous pipe handles for VT-encoded data streams.

Handle Inheritance and Process Lifetime

A critical aspect of ConPTY is handle inheritance. The hPtyReference handle is duplicated into the child process via CreateProcess using the PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE attribute. This ensures the pseudo-console stays alive even if the parent (Windows Terminal) terminates unexpectedly—the reference count only drops to zero when all client processes exit.

STARTUPINFOEXW siEx = { sizeof(siEx) };
size_t attrSize = 0;
InitializeProcThreadAttributeList(nullptr, 1, 0, &attrSize);
siEx.lpAttributeList = reinterpret_cast<LPPROC_THREAD_ATTRIBUTE_LIST>(HeapAlloc(GetProcessHeap(), 0, attrSize));
InitializeProcThreadAttributeList(siEx.lpAttributeList, 1, 0, &attrSize);
UpdateProcThreadAttribute(siEx.lpAttributeList,
                         0,
                         PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,
                         hPc,
                         sizeof(hPc),
                         nullptr,
                         nullptr);

CreateProcessW(L"C:\\Windows\\System32\\cmd.exe",
               nullptr, nullptr, nullptr, FALSE,
               EXTENDED_STARTUPINFO_PRESENT, nullptr,
               nullptr, &siEx.StartupInfo, &pi);

VT-Aware I/O and Signal Handling

ConPTY operates entirely through VT-encoded streams, enabling modern terminal features while maintaining backward compatibility.

The Signal Pipe Architecture

Control messages flow through the hSignal pipe defined in src/winconpty/winconpty.h. ConPTY sends signals such as PTY_SIGNAL_SHOW_HIDE_WINDOW, PTY_SIGNAL_CLEAR, and PTY_SIGNAL_RESIZE_WINDOW through this out-of-band channel. The ConptyConnection class reads this pipe on a dedicated signal thread and updates the UI accordingly, as implemented in src/host/VtIo.cpp and src/cascadia/TerminalConnection/ConptyConnection.cpp.

Handling Resize and Focus Events

When a user resizes a Windows Terminal tab, the ConptyConnection::Resize method calls _ResizePseudoConsole to update the pseudo-console dimensions:

void ConptyConnection::Resize(uint32_t rows, uint32_t columns)
{
    _rows = rows;
    _cols = columns;
    _ResizePseudoConsole(_hPC.get(), { static_cast<SHORT>(columns), static_cast<SHORT>(rows) });
}

Similarly, focus changes trigger ShowHide or ReparentWindow signals that propagate through the signal pipe to conhost.exe, ensuring the child process receives accurate focus state notifications via standard console APIs.

State Machine Integration

All VT sequences flowing through ConPTY are parsed by Windows Terminal's StateMachine, implemented in src/terminal/parser/stateMachine.cpp. This component translates incoming VT streams into rendering operations while forwarding specific sequences (such as focus events) back to ConPTY via the signal pipe, creating a bidirectional communication channel.

Why ConPTY Matters for Windows Terminal

ConPTY provides three critical advantages that enable Windows Terminal to function as a modern, high-performance terminal emulator.

Process Isolation – Each tab runs inside its own conhost.exe process via ConPTY. If a child application crashes or hangs, it cannot bring down the entire Windows Terminal instance or affect other tabs.

Performance Optimization – By bypassing the legacy Console API and delivering raw VT streams directly through anonymous pipes, ConPTY eliminates extra translation layers. The terminal receives VT-encoded data that maps directly to modern GPU-accelerated rendering pipelines.

Backward Compatibility – Because ConPTY hosts child processes inside genuine conhost.exe instances, all standard Windows console APIs (such as ReadConsoleInput, SetConsoleMode, and WriteConsole) continue to function exactly as legacy applications expect. The UI layer gains full VT support while maintaining compatibility with decades of existing command-line tools.

Summary

• ConPTY is the Windows 10/Server 2019 Pseudo-Console API that enables headless console sessions via anonymous pipes.
• Windows Terminal uses ConPTY to host each tab in an isolated conhost.exe process, implementing the ITerminalConnection interface through ConptyConnection.
• The architecture consists of three layers: the low-level winconpty library wrapping native APIs, the C++/WinRT connection layer managing lifecycle and I/O, and sample implementations demonstrating managed usage.
• Critical implementation details include the three-handle structure (hSignal, hPtyReference, hConPtyProcess), VT-encoded I/O streams, and signal pipe architecture for resize/focus events.
• ConPTY provides process isolation, performance improvements through raw VT streams, and full backward compatibility with legacy console APIs.

Frequently Asked Questions

What is the difference between ConPTY and traditional console APIs?

Traditional Windows console applications interact with the console subsystem through the Console API (functions like ReadConsole and WriteConsole), which requires a visible console window or complex workarounds for headless operation. ConPTY provides a modern, headless alternative that uses anonymous pipes for VT-encoded input/output, allowing terminal emulators to host console applications without creating visible console windows while maintaining full API compatibility through the underlying conhost.exe process.

Is ConPTY available on all Windows versions?

ConPTY was introduced in Windows 10 version 1809 (October 2018 Update) and Windows Server 2019. It is not available on earlier Windows versions such as Windows 8.1 or Windows 7. Applications attempting to use ConPTY APIs on unsupported systems will receive error codes from the CreatePseudoConsole function and should fall back to traditional console hosting methods.

How does ConPTY handle process isolation?

ConPTY achieves process isolation by hosting each pseudo-console inside a separate conhost.exe process. When Windows Terminal creates a new tab, it initializes a ConPTY session that spawns a dedicated conhost.exe instance via the ConptyCreatePseudoConsoleAsUser function. The hPtyReference handle maintains a reference count on this process, ensuring that even if the terminal crashes, the console session persists until the child application exits. This architecture prevents a single misbehaving application from crashing the entire terminal emulator.

Can I use ConPTY in my own applications?

Yes, Microsoft provides the ConPTY API as a public Windows API surface, and the microsoft/terminal repository includes sample implementations demonstrating integration. Developers can use the native Windows API functions (CreatePseudoConsole, ResizePseudoConsole, ClosePseudoConsole) directly, or reference the samples/ConPTY/GUIConsole/GUIConsole.ConPTY/Terminal.cs file for a managed C# implementation. The key requirements are Windows 10 version 1809 or later, and proper handle management for the input/output pipes and signal channel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}