# Contributor handoff — microsoft/terminal

> Canonical page: https://codevetter.com/unpack/terminal/agent-handoff

# Contributor handoff — microsoft/terminal

Scanned commit 7c92ecd037476f957809d0813b14d8bc44bb071a (2026-09-18). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [AGENTS.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/AGENTS.md) [CLAUDE.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/CLAUDE.md)
- 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`. — [README.md#L330-365](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/README.md#L330-L365) [.config/configuration.winget](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/.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). — [README.md#L355-390](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/README.md#L355-L390) [tools/bcz.cmd](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/bcz.cmd) [tools/OpenConsole.psm1](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/OpenConsole.psm1)
- 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). — [tools/runut.cmd](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/runut.cmd) [tools/runft.cmd](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/runft.cmd) [tools/runuia.cmd](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/runuia.cmd) [doc/ORGANIZATION.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/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. — [doc/STYLE.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/STYLE.md) [doc/WIL.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/WIL.md) [doc/ORGANIZATION.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/ORGANIZATION.md) [src/cascadia/TerminalConnection/ConptyConnection.cpp#L44-53](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalConnection/ConptyConnection.cpp#L44-L53)
- 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. — [src/cppwinrt.build.pre.props](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cppwinrt.build.pre.props) [src/cppwinrt.build.post.props](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cppwinrt.build.post.props) [src/cascadia/TerminalApp/dll/TerminalApp.vcxproj](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/dll/TerminalApp.vcxproj)
- 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. — [src/cascadia/TerminalSettingsModel/FileUtils.cpp#L13-70](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/FileUtils.cpp#L13-L70) [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L1233-1251](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L1233-L1251)
- 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). — [src/cascadia/WindowsTerminal/main.cpp#L112-121](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/WindowsTerminal/main.cpp#L112-L121) [src/cascadia/TerminalApp/TerminalPage.cpp#L748-763](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/TerminalPage.cpp#L748-L763) [src/cascadia/TerminalApp/AppLogic.cpp#L289-302](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/AppLogic.cpp#L289-L302)
- 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. — [README.md#L380-390](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/README.md#L380-L390) [src/cascadia/wt/shim.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/wt/shim.cpp)
- 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). — [src/cascadia/TerminalApp/TerminalPage.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/TerminalPage.cpp) [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp) [src/cascadia/TerminalControl/ControlCore.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalControl/ControlCore.cpp) [src/cascadia/WindowsTerminal/WindowEmperor.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/WindowsTerminal/WindowEmperor.cpp)
- 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) — [src/cascadia/UnitTests_SettingsModel/SerializationTests.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/UnitTests_SettingsModel/SerializationTests.cpp) [src/cascadia/UnitTests_TerminalCore/TerminalApiTest.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/UnitTests_TerminalCore/TerminalApiTest.cpp) [doc/ORGANIZATION.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/ORGANIZATION.md)
- 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. — [src/cascadia/WindowsTerminal/main.cpp#L25-31](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/WindowsTerminal/main.cpp#L25-L31)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)