# Windows Terminal VT Sequence Categories: Shell Integration Marks Explained

> Explore Windows Terminal VT sequence categories Default Prompt Success Warning and Error for shell integration. Learn how OSC 133 enables visual scrollbar marks and navigation.

- Repository: [Microsoft/terminal](https://github.com/microsoft/terminal)
- Tags: deep-dive
- Published: 2026-02-26

---

**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`](https://github.com/microsoft/terminal/blob/main/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`](https://github.com/microsoft/terminal/blob/main/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`](https://github.com/microsoft/terminal/blob/main/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`](https://github.com/microsoft/terminal/blob/main/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:

```cpp
// 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`](https://github.com/microsoft/terminal/blob/main/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`](https://github.com/microsoft/terminal/blob/main/src/buffer/out/Marks.hpp), which is attached to individual buffer rows by [`src/buffer/out/textBuffer.cpp`](https://github.com/microsoft/terminal/blob/main/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.