CodeVetter · Repo Unpack · Contributor handoff
microsoft/terminal
This is a Windows-only C++/WinRT + WinUI 3 codebase; you cannot build or run it on Linux/macOS. Read AGENTS.md first: the project has a strict AI-usage policy that bans most AI-authored public contributions and Co-authored-by AI credits. Build with tools/razzle.cmd + bcz (or OpenConsole.psm1 Invoke-OpenConsoleBuild), test with tools/runut.cmd (TAEF). Conventions: wil RAII + THROW_IF_*/RETURN_IF_* macros, til:: types, fmt, .idl files generate .g.cpp via cppwinrt (never edit generated files), settings changes follow doc/AddASetting.md, new actions go through the ALL_SHORTCUT_ACTIONS X-macro. Key traps: STA must precede XAML creation, don't hold static refs to ApplicationState in callbacks, first tab must be created synchronously, and WindowsTerminal.exe can't just be double-clicked when packaged.
- AGENTS.md is an AI usage POLICY, not a build guide: it permits only small localized AI fixes and disclosed+maintainer-approved contributions, bans AI-authored public interactions and Co-authored-by AI credits, and instructs agents to STOP and explain the restriction if the work is prohibited. Read it before producing any PR-bound change.
- Build requires Windows with VS 2026 18.6+, Windows 11 SDK 10.0.26100.8249+, PowerShell 7+, .NET Framework 4.7.2 targeting pack (for test projects), Developer Mode enabled; quickest setup is `winget configure .config/configuration.winget`.
- Build commands: `Import-Module ./tools/OpenConsole.psm1; Set-MsBuildDevEnvironment; Invoke-OpenConsoleBuild` in PowerShell, or `tools\razzle.cmd` then `bcz` in cmd; bcz supports dbg/rel/no_clean/exclusive args. Debug via the CascadiaPackage project with 'Native Only' debugging, x64 or x86 (not Any CPU).
- Tests: tools/runut.cmd runs the TAEF unit suite (must match tools/tests.xml), tools/runft.cmd runs feature tests, tools/runuia.cmd runs the WinAppDriver UIA suite; repo convention is a ut_ folder per project and ft_ for functional tests (doc/ORGANIZATION.md).
- Coding conventions: wil::unique_* RAII wrappers and THROW_IF_WIN32_BOOL_FALSE/RETURN_IF_FAILED/CATCH_LOG/CATCH_RETURN error macros, til:: geometry/string types, fmt::format with FMT_COMPILE, gsl::narrow for casts, winrt namespaces with .idl-defined runtimeclasses; see doc/STYLE.md, doc/WIL.md, doc/EXCEPTIONS.md.
- cppwinrt generates *.g.cpp/*.g.h from .idl files at build time (cppwinrt.build.*.props) — edit the .idl, never the generated files; many projects pair a source dir with a dll/ subdir holding the .vcxproj and .def.
- settings.json lives at CascadiaSettings::SettingsPath(): packaged LocalState (8wekyb3d8bbwe), %LOCALAPPDATA%\Microsoft\Windows Terminal for unpackaged, or beside the exe when a '.portable' file exists; first-run on Preview/Canary migrates the Release channel's file.
- Known traps documented in-code: init_apartment(STA) must precede any Xaml object (main.cpp '!!! LOAD BEARING !!!'); the first tab must be created synchronously because WinUI won't size hidden content and ControlCore needs a size (TerminalPage ProcessStartupActions GH#13136); don't keep a static ref to ApplicationState in the folder-watcher callback or teardown crashes (AppLogic.cpp).
- You cannot launch a packaged build by running WindowsTerminal.exe directly (GH#926/GH#4043) — deploy/debug through CascadiaPackage; the wt.exe shim resolves WindowsTerminal.exe from its own directory.
- Files to read before editing a feature: src/cascadia/TerminalApp/TerminalPage.cpp (action handlers, tab/pane lifecycle), src/cascadia/TerminalSettingsModel/AllShortcutActions.h + ActionArgsMagic.h (action plumbing), src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp (settings layering), src/cascadia/TerminalControl/ControlCore.cpp + TermControl.cpp (control/renderer/connection glue), src/cascadia/WindowsTerminal/WindowEmperor.cpp (process model).
- Safe-edit boundaries: TerminalCore/parser/adapter changes are UI-agnostic and unit-testable via UnitTests_TerminalCore + ConParser/ConAdapter tests; settings-model changes should round-trip through UnitTests_SettingsModel; UI changes in TerminalApp/TerminalControl can't be validated without a Windows desktop — prefer unit-testable layers when possible. (inferred)
- Localization: user-facing strings go through Resources.resw per project and RS_/USES_RESOURCE/GetStringResource helpers; WindowsTerminal.exe borrows TerminalApp's resources via UTILS_DEFINE_LIBRARY_RESOURCE_SCOPE("TerminalApp/Resources") marked '!! BODGY !!' — add new strings there, not in WindowsTerminal.