Windows Terminal VT Sequence Categories: Shell Integration Marks Explained

Windows Terminal supports five distinct VT sequence categories—Default, Prompt, Success, Warning, and Error—that classify buffer rows through OSC 133 sequences to enable visual scrollbar marks and quick navigation.

Windows Terminal implements advanced shell integration by parsing VT OSC (Operating System Command) sequences emitted by compatible shells. These sequences assign a MarkCategory enum value to specific buffer rows, storing metadata that powers UI features like color-coded scrollbar thumbnails and jump-to-mark commands.

The Five VT Sequence Categories

The terminal classifies shell integration marks using the MarkCategory enum defined in src/buffer/out/Marks.hpp. Each category determines how the terminal renders the corresponding line in the scrollbar and selection UI.

Default

MarkCategory::Default represents uncategorized marks. When no explicit category is specified in the VT sequence, the terminal attaches this value to the row's ScrollbarData. These marks remain invisible in the UI unless a custom color is explicitly supplied.

Prompt

MarkCategory::Prompt identifies lines containing shell prompts. Emitted via OSC 133;A ST (start of prompt) and paired with OSC 133;B ST (end of prompt), this category enables the "jump to previous/next prompt" commands and intelligent selection boundaries. The terminal uses this mark to distinguish command input lines from output in the scrollback buffer.

Success

MarkCategory::Success indicates a command completed without errors. Shells emit OSC 133;D;0 ST to signal exit code 0, prompting the terminal to render the corresponding scrollbar mark in green. This visual cue allows users to quickly scan their command history for successful operations.

Error

MarkCategory::Error marks commands that failed with a non-zero exit code. When the shell emits OSC 133;D;<non-zero> ST, the terminal parses this as an error state and renders the mark in red. This category provides immediate visual feedback for failed commands across the scrollback buffer.

Warning

MarkCategory::Warning highlights non-critical issues or specific exit conditions that require attention but do not constitute complete failures. While less commonly used than Error, this category enables yellow/orange visualization for intermediate states, accessible through specific OSC 133 sequence parameters.

How Categories Are Parsed and Stored

When a shell emits FTCS (Final Term Command Sequences) style OSC sequences, the terminal's parsing pipeline converts them into structured data.

The adaptDispatch layer in src/terminal/adapter/adaptDispatch.cpp handles initial sequence recognition. This component maps incoming OSC 133 sequences—such as FTCS_PROMPT and FTCS_COMMAND_FINISHED—to their corresponding MarkCategory values. It populates a ScrollbarData struct with the category and optional metadata like exit codes or colors.

The TextBuffer implementation in src/buffer/out/textBuffer.cpp then attaches this ScrollbarData object to the specific row in the buffer. This attachment makes the category information available for UI rendering and navigation features.

Finally, src/cascadia/TerminalCore/Terminal.cpp consumes these categories during rendering decisions, applying the appropriate colors to scrollbar thumbs and enabling context-aware selection behaviors based on the mark type.

Practical Implementation Examples

Shells emit specific OSC 133 sequences to trigger these categories. The following examples demonstrate the VT sequences recognized by Windows Terminal:

// Mark the start of a prompt (category: Prompt)
fmt::format(FMT_COMPILE(L"\x1b]133;A\x07"));   // OSC 133 ; A ST

// Mark successful command completion (category: Success)
fmt::format(FMT_COMPILE(L"\x1b]133;D;0\x07")); // OSC 133 ; D ; 0 ST

// Mark failed command completion (category: Error)
fmt::format(FMT_COMPILE(L"\x1b]133;D;1\x07")); // OSC 133 ; D ; 1 ST

These sequences integrate with PowerShell, bash, and other compatible shells to automatically categorize command output without manual user intervention.

Summary

• Windows Terminal recognizes five VT sequence categories defined in src/buffer/out/Marks.hpp: Default, Prompt, Success, Warning, and Error.
• OSC 133;A marks prompt lines, while OSC 133;D;<exit_code> marks command completion with status-based categorization.
• The adaptDispatch parser maps sequences to MarkCategory values, which TextBuffer stores in ScrollbarData attached to buffer rows.
• Categories drive visual feedback through colored scrollbar marks and enable navigation features like jumping between prompts.

Frequently Asked Questions

What is the difference between Error and Warning categories in Windows Terminal?

Error (MarkCategory::Error) indicates command failure through non-zero exit codes and renders in red, while Warning (MarkCategory::Warning) represents intermediate states requiring attention and renders in yellow/orange. Most shell integrations map non-zero exits to Error, reserving Warning for specific application-defined conditions.

How do I emit a Success mark from my shell script?

Emit the VT sequence OSC 133;D;0 ST (hex: \x1b]133;D;0\x07) at command completion to mark the exit code as 0. Windows Terminal interprets this as MarkCategory::Success and displays a green indicator in the scrollbar.

Where does Windows Terminal store VT sequence category information?

The terminal stores categories in the ScrollbarData struct defined in src/buffer/out/Marks.hpp, which is attached to individual buffer rows by src/buffer/out/textBuffer.cpp. This data persists with the scrollback buffer and drives UI rendering and navigation features.

Do all shell integration features require explicit category markers?

No. While explicit categories like Success and Error enhance visualization, the Prompt category is essential for jump-to-mark functionality. Uncategorized marks use MarkCategory::Default and remain invisible unless manually colored, functioning as silent bookmarks in the buffer.

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