CodeVetter · Repo Unpack · System map
microsoft/terminal
The repo is one MSBuild workspace (OpenConsole.slnx) producing several binaries: WindowsTerminal.exe (the packaged terminal app, entrypoint in src/cascadia/WindowsTerminal/main.cpp), conhost.exe/OpenConsole.exe (src/host/exe), a wt.exe CLI shim, a shell extension, and many DLL/LIB components under src/cascadia and src/terminal. The terminal app is a Win32 process hosting WinUI 3 XAML islands; a single-instance 'WindowEmperor' owns all windows. Terminal functionality is layered: TerminalConnection (process/pipe IO) -> TerminalControl/ControlCore (XAML + renderer glue) -> TerminalCore (buffer + VT state machine) -> renderer/atlas (D3D text rendering). The conhost side lives under src/host and src/server and talks to the ConDrv driver. Build is MSBuild via tools/razzle.cmd + bcz.cmd or the OpenConsole.psm1 module; CI is Azure Pipelines (build/pipelines), with GitHub Actions only for release publishing and spell-checking.
- The repo builds three products: Windows Terminal, Windows Terminal Preview, and the Windows console host (conhost.exe), plus shared components, ColorTool, and Console API samples.
- WindowsTerminal.exe entrypoint is wWinMain in src/cascadia/WindowsTerminal/main.cpp: it registers the 'Microsoft.Windows.Terminal.Win32Host' TraceLogging provider, resets Ctrl handlers, calls EnsureNativeArchitecture() to block wrong-arch launches, enables WM_POINTER, initializes the thread as STA, then constructs a WindowEmperor and calls HandleCommandlineArgs(nCmdShow).
- WindowEmperor is the single-instance owner of all terminal windows: it builds a branding/elevation/SID-scoped window class name (e.g. 'Windows Terminal Admin <hash> <hash>'), acquires a named mutex or hands the serialized command line to the existing instance via WM_COPYDATA, then runs the process-wide GetMessageW loop that pumps every AppHost window.
- Each visible window is an AppHost wrapping a XAML-island HWND (IslandWindow/NonClientIslandWindow); windows are created by WindowEmperor::CreateNewWindow which constructs AppHost with WindowRequestedArgs and tracks them in _windows.
- The terminal app's code is split into projects under src/cascadia: TerminalApp (window/page/tab/pane UI + actions), TerminalControl (XAML control + ControlCore), TerminalCore (UI-agnostic terminal: buffer, VT parser wiring), TerminalSettingsModel (settings.json model), TerminalConnection (ConPTY/Azure/Echo connection types), TerminalSettingsEditor (Settings UI), plus helpers (ElevateShim, ShellExtension, wt shim, WpfTerminalControl).
- Client processes are spawned through ConPTY: ConptyConnection::Start calls ConptyCreatePseudoConsole (statically linked from src/inc/conpty-static.h / src/winconpty) then _LaunchAttachedClient uses CreateProcessW with PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE.
- conhost.exe is built from src/host/exe (Host.EXE.vcxproj) with wWinMain in exemain.cpp; it registers COM out-of-proc class objects (including CConsoleHandoff for incoming ConPTY handoff), honors the HKCU\Console ForceV2 registry value for the legacy console, and initializes the server side under src/server (ConDrvDeviceComm, IoDispatchers, ApiDispatchers).
- wt.exe is a ~40-line shim (src/cascadia/wt/shim.cpp) that replaces its own filename with WindowsTerminal.exe in the same directory and CreateProcessW's it, prepending its own name (wt/wtd) to the command line.
- Packaging is MSIX via src/cascadia/CascadiaPackage/CascadiaPackage.wapproj with four branding manifests (Package.appxmanifest, Package-Pre.appxmanifest, Package-Can.appxmanifest, Package-Dev.appxmanifest) selected by WT_BRANDING_* macros.
- Third-party dependencies are managed by vcpkg (vcpkg.json): fmt 12.1.0, ms-gsl 4.2.2, jsoncpp 1.9.6, cli11 2.6.1, cmark 0.31.1, with overlay ports/triplets under dep/vcpkg-overlay-*.
- The master build is OpenConsole.slnx (XML solution listing ~all vcxproj/csproj/wapproj with AuditMode/Debug/Fuzzing/Release configs on x86/x64/arm64); conhost.slnf is a filtered solution for conhost-only work, and Scratch.sln exists for experiments.
- Developer builds run through tools/: razzle.cmd sets up the environment, bcz.cmd/bx.cmd wrap MSBuild Clean;Build, and tools/OpenConsole.psm1 provides Invoke-OpenConsoleBuild/Set-MsBuildDevEnvironment; tests run via tools/runut.cmd, runft.cmd, runuia.cmd.
- CI is Azure Pipelines, not GitHub Actions: build/pipelines/ci.yml runs an Audit x64 stage, a code-format check (templates-v2/job-check-code-format.yml), and per-platform builds for x64/x86/arm64 with a runTests parameter; the three .github/workflows files only handle winget publishing, check-spelling, and project-board automation.
- Feature flags are declared in src/features.xml (e.g. Feature_ReceiveIncomingHandoff, Feature_AttemptHandoff, Feature_ConhostAtlasEngineCustomShaders) with per-branding alwaysEnabled/alwaysDisabled tokens, and turned into TIL_FEATURE_* macros by tools/Generate-FeatureStagingHeader.ps1.