# Extension points — microsoft/terminal

> Canonical page: https://codevetter.com/unpack/terminal/extension-points

# Extension points — microsoft/terminal

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

The codebase is built around explicit extension surfaces: the ALL_SHORTCUT_ACTIONS X-macro generates dispatch for every bindable action; ACTION_ARGS_STRUCT macros synthesize args classes with JSON keys; NewTabMenuEntry variants compose the new-tab menu; IDynamicProfileGenerator feeds discovered profiles; ITerminalConnection abstracts transports; IStateMachineEngine/ITermDispatch decouple the VT parser from its consumer; renderers are swappable behind the renderer/base interface; settings fragments + app extensions let third parties inject configuration; and features.xml adds staged feature flags. HwndTerminal/WpfTerminalControl expose the terminal as an embeddable control.
- Adding a new keybindable action means adding one line to ALL_SHORTCUT_ACTIONS in AllShortcutActions.h — the X-macro auto-generates the ShortcutAction enum entry, the ShortcutActionDispatch case that raises the event, and handler declarations consumed by TerminalPage/AppActionHandlers. — [src/cascadia/TerminalSettingsModel/AllShortcutActions.h#L1-60](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/AllShortcutActions.h#L1-L60) [src/cascadia/TerminalApp/ShortcutActionDispatch.cpp#L44-52](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/ShortcutActionDispatch.cpp#L44-L52) [src/cascadia/TerminalApp/AppActionHandlers.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/AppActionHandlers.cpp)
- Action argument types are generated by macro: ACTION_ARGS_STRUCT(MyArgs, MY_ARGS) plus a per-action args X-macro produces the class, its JSON keys, and (de)serialization hooks — documented inline in ActionArgsMagic.h including a godbolt -E tip for debugging expansion. — [src/cascadia/TerminalSettingsModel/ActionArgsMagic.h#L20-50](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/ActionArgsMagic.h#L20-L50)
- The new-tab dropdown is data-driven from settings via NewTabMenuEntry variants — Profile, Folder, Separator, RemainingProfiles, MatchProfiles, Action — recursively materialized by _CreateNewTabFlyoutItems. — [src/cascadia/TerminalSettingsModel/NewTabMenuEntry.h](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/NewTabMenuEntry.h) [src/cascadia/TerminalApp/TerminalPage.cpp#L1155-1280](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/TerminalPage.cpp#L1155-L1280)
- New dynamic profile sources implement IDynamicProfileGenerator and are enumerated during CascadiaSettings::LoadAll -> GenerateProfiles; existing examples are WslDistroGenerator, PowershellCoreProfileGenerator, AzureCloudShellGenerator, VisualStudioGenerator, SshHostGenerator. — [src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h) [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L14-18](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L14-L18) [src/cascadia/TerminalSettingsModel/WslDistroGenerator.h](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/WslDistroGenerator.h)
- Third-party settings injection: JSON 'fragments' dropped in '<LocalState>\Microsoft\Windows Terminal\Fragments' or delivered via the 'com.microsoft.windows.terminal.settings' app-extension host are merged by FindFragmentsAndMergeIntoUserSettings and surfaced as ExtensionPackages in the Settings UI. — [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L125-137](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L125-L137) [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L329-397](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L329-L397)
- New connection transports implement ITerminalConnection (idl: Initialize(ValueSet), Start, WriteInput, Resize, Close; events TerminalOutput/StateChanged) — ConptyConnection, AzureConnection, EchoConnection are the built-ins, and _CreateConnectionFromSettings selects by profile.ConnectionType(). — [src/cascadia/TerminalConnection/ITerminalConnection.idl](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalConnection/ITerminalConnection.idl) [src/cascadia/TerminalConnection/EchoConnection.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalConnection/EchoConnection.cpp) [src/cascadia/TerminalApp/TerminalPage.cpp#L1570-1589](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/TerminalPage.cpp#L1570-L1589)
- The VT parser is engine-agnostic: StateMachine owns an IStateMachineEngine (OutputStateMachineEngine for output, InputStateMachineEngine for input), which forwards to an ITermDispatch/ITerminalApi implementation — letting conhost (AdaptDispatch) and TerminalCore share the same parser. — [src/terminal/parser/stateMachine.cpp#L14-32](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/terminal/parser/stateMachine.cpp#L14-L32) [src/terminal/parser/OutputStateMachineEngine.cpp#L21-44](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/terminal/parser/OutputStateMachineEngine.cpp#L21-L44) [src/terminal/adapter/adaptDispatch.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/terminal/adapter/adaptDispatch.cpp) [src/terminal/parser/InputStateMachineEngine.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/terminal/parser/InputStateMachineEngine.cpp)
- Settings layering is tag-based: ParsedSettings entries carry an OriginTag (InBox, User, Generated, Dynamic, Fragment) and SettingsLoader merges them in a fixed order — new settings sources plug in as additional origins without changing the merge engine. — [src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L102-160](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp#L102-L160)
- New feature flags are added declaratively in src/features.xml with a name/description/stage and per-branding alwaysEnabled/alwaysDisabled tokens, then materialized as TIL_FEATURE_* macros by tools/Generate-FeatureStagingHeader.ps1 (schema: tools/FeatureStagingSchema.xsd). — [src/features.xml](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/features.xml) [tools/Generate-FeatureStagingHeader.ps1](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/tools/Generate-FeatureStagingHeader.ps1) [doc/feature_flags.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/feature_flags.md)
- The terminal control is embeddable: HwndTerminal hosts it as a raw HWND and WpfTerminalControl wraps it for WPF apps — the intended surface for third-party embedding. — [src/cascadia/TerminalControl/HwndTerminal.cpp](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalControl/HwndTerminal.cpp) [src/cascadia/WpfTerminalControl](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/WpfTerminalControl)
- wt subcommands extend through CLI11: _addNewTerminalArgs adds the shared option set to each subcommand and each subcommand registers a callback that pushes ActionAndArgs onto _startupActions — new subcommands follow the new-tab/split-pane pattern. — [src/cascadia/TerminalApp/AppCommandlineArgs.cpp#L216-317](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/src/cascadia/TerminalApp/AppCommandlineArgs.cpp#L216-L317)
- Adding a new setting is a documented recipe (doc/AddASetting.md): model class + .idl property + JSON key in the serialization layer + defaults.json + Settings UI page — the specs folder contains design docs for past additions like marks, unfocused appearance, and quake mode. — [doc/AddASetting.md](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/AddASetting.md) [doc/specs](https://github.com/microsoft/terminal/blob/7c92ecd037476f957809d0813b14d8bc44bb071a/doc/specs)

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)