# Where Is the VT Parser Located in the Windows Terminal Codebase?

> Find the VT parser in the microsoft terminal codebase. It's located in src/terminal/parser and centers on the StateMachine class implementing the ANSI VT-100 state machine.

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

---

**The VT parser resides in the `src/terminal/parser` directory and is centered around the `StateMachine` class that implements the ANSI/VT-100 state machine.**

The Windows Terminal codebase contains a sophisticated Virtual Terminal (VT) parser that handles both incoming console input and outgoing rendered output. This subsystem implements the complete ANSI/VT-100 state machine to decode escape sequences, control sequences, and specialized command strings. Understanding the VT parser location and architecture is essential for developers contributing to terminal emulation or building custom console applications on Windows.

## VT Parser Location and Core Architecture

The VT parser is located in **`src/terminal/parser`** within the Windows Terminal repository. At the heart of this subsystem is the **`StateMachine`** class, which tracks the current parsing state and transitions between states according to the VT protocol specifications.

### The StateMachine Class

The `StateMachine` class (defined in [`src/terminal/parser/stateMachine.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/stateMachine.hpp) and implemented in [`src/terminal/parser/stateMachine.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/stateMachine.cpp)) maintains the current **`VTStates`** enum value (Ground, Escape, CsiEntry, DcsEntry, etc.). As characters arrive via `ProcessCharacter()` or `ProcessString()`, the state machine updates its internal buffers and transitions between states until a complete sequence is recognized.

### Engine Implementations

The parser uses the **Strategy pattern** to separate parsing logic from action execution. The `StateMachine` delegates actual handling to classes implementing the **`IStateMachineEngine`** interface:

- **`InputStateMachineEngine`** (`src/terminal/parser/InputStateMachineEngine.hpp/cpp`): Handles inbound VT sequences from console input.
- **`OutputStateMachineEngine`** (`src/terminal/parser/OutputStateMachineEngine.hpp/cpp`): Processes outbound sequences for terminal rendering.

## Key VT Parser Implementation Files

The VT parser consists of several tightly coupled components distributed across the `src/terminal/parser` directory:

| Component | File Path | Purpose |
|-----------|-----------|---------|
| State machine core | [`src/terminal/parser/stateMachine.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/stateMachine.hpp)<br>[`src/terminal/parser/stateMachine.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/stateMachine.cpp) | Declares and implements the finite-state machine tracking `VTStates` and driving callbacks. |
| Input engine | [`src/terminal/parser/InputStateMachineEngine.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/InputStateMachineEngine.hpp)<br>[`src/terminal/parser/InputStateMachineEngine.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/InputStateMachineEngine.cpp) | Implements `IStateMachineEngine` for handling input-side VT sequences (CSI, DCS). |
| Output engine | [`src/terminal/parser/OutputStateMachineEngine.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/OutputStateMachineEngine.hpp)<br>[`src/terminal/parser/OutputStateMachineEngine.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/OutputStateMachineEngine.cpp) | Implements `IStateMachineEngine` for generating VT output used by the renderer. |
| Engine interface | [`src/terminal/parser/IStateMachineEngine.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/IStateMachineEngine.hpp) | Abstract callbacks that the state machine invokes when sequences are recognized. |
| Dispatch types | [`src/terminal/adapter/DispatchTypes.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/DispatchTypes.hpp) | Defines `VTID`, `VTParameter`, `VTParameters`, and helper classes used by the parser. |
| Tracing utilities | [`src/terminal/parser/tracing.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/tracing.hpp)<br>[`src/terminal/parser/tracing.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/tracing.cpp) | Logging helpers that emit detailed parsing state for debugging. |
| Unit tests | [`src/terminal/parser/ut_parser/StateMachineTest.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/ut_parser/StateMachineTest.cpp) | Comprehensive tests covering full VT state machine behavior. |

## How the VT Parser Processes Sequences

Understanding the VT parser location requires examining how it transforms raw byte streams into structured terminal commands.

### State Transitions and Character Processing

The `StateMachine` processes input through `ProcessCharacter()` or `ProcessString()`. It maintains the current state as a `VTStates` enum value (Ground, Escape, CsiEntry, CsiParam, DcsEntry, etc.). As each character arrives:

1. The state machine looks up the transition table for the current state.
2. It accumulates parameters into `VTParameters` structures.
3. It builds the command identifier as a `VTID` object.
4. Upon reaching a terminal state, it invokes the appropriate callback on the bound `IStateMachineEngine`.

### Sequence Dispatching

When a complete sequence is recognized, the `StateMachine` delegates to virtual methods on the engine:

- `ActionCsiDispatch()` for Control Sequence Introducer sequences (e.g., `ESC[31m`)
- `ActionDcsDispatch()` for Device Control String sequences
- `ActionEscDispatch()` for simple escape sequences
- `ActionPrint()` for printable characters

The concrete engines (`InputStateMachineEngine` or `OutputStateMachineEngine`) implement these methods to perform actual terminal operations.

## Working with the VT Parser: Code Examples

The VT parser in Windows Terminal can be instantiated and configured programmatically for custom terminal applications.

### Creating a VT Parser for Input

The following example demonstrates creating a custom input parser by implementing `IStateMachineEngine`:

```cpp
#include "stateMachine.hpp"
#include "InputStateMachineEngine.hpp"
#include "DispatchTypes.hpp"

using namespace Microsoft::Console::VirtualTerminal;

// Implement a minimal engine that logs parsed IDs.
class MyEngine final : public IStateMachineEngine
{
public:
    bool ActionCsiDispatch(const VTID id, const VTParameters parameters) noexcept override
    {
        // Handle CSI 'm' (SGR - set graphic rendition).
        if (id == VTID(L'm'))
        {
            // parameters is a span of VTParameter values.
            // Apply colors, styles, etc.
        }
        return true; // Sequence was consumed.
    }

    // Implement other pure virtual methods with no-ops.
    // ...
};

int main()
{
    auto engine = std::make_unique<MyEngine>();
    StateMachine vtParser{ std::move(engine) };

    // Feed a string containing an SGR sequence (ESC[31m → set red foreground).
    vtParser.ProcessString(L"\x1b[31mHello\x1b[0m");

    // At this point MyEngine::ActionCsiDispatch has been called twice.
}

```

### Using the Output Engine

The output engine generates VT sequences for rendering:

```cpp
#include "stateMachine.hpp"
#include "OutputStateMachineEngine.hpp"
#include "DispatchTypes.hpp"

using namespace Microsoft::Console::VirtualTerminal;

int main()
{
    // The output engine forwards actions to a lambda you provide.
    auto dispatch = std::make_unique<OutputStateMachineEngine::Dispatch>();
    dispatch->ActionCsiDispatch = [](const VTID id, const VTParameters params) {
        // Convert the VTID and parameters to an actual escape string.
        // Example: VTID(L'm') with params {31} → "\x1b[31m"
    };

    StateMachine vtParser{ std::move(dispatch) };
    vtParser.ProcessString(L"\x1b[42m"); // triggers the lambda above.
}

```

### Toggling Parser Modes

The VT parser supports runtime configuration of parsing modes:

```cpp
vtParser.SetParserMode(StateMachine::Mode::Ansi, true);  // enable ANSI extensions
vtParser.SetParserMode(StateMachine::Mode::AcceptC1, false); // ignore C1 control chars

```

## Summary

The Windows Terminal VT parser is a sophisticated subsystem located in `src/terminal/parser` that implements the complete ANSI/VT-100 state machine. Key takeaways include:

- The **`StateMachine`** class in `stateMachine.hpp/cpp` forms the core parsing engine, maintaining `VTStates` and processing input via `ProcessCharacter()` and `ProcessString()`.
- Concrete implementations **`InputStateMachineEngine`** and **`OutputStateMachineEngine`** handle input and output sequences respectively, inheriting from **`IStateMachineEngine`**.
- Supporting types like **`VTID`**, **`VTParameter`**, and **`VTParameters`** are defined in [`src/terminal/adapter/DispatchTypes.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/DispatchTypes.hpp).
- The parser supports runtime mode switching via `SetParserMode()` and sequence injection via `InjectSequence()`.

## Frequently Asked Questions

### Where exactly is the VT parser code located in Windows Terminal?

The VT parser source code is located in the **`src/terminal/parser`** directory of the Windows Terminal repository. The main entry point is the `StateMachine` class implemented in [`stateMachine.hpp`](https://github.com/microsoft/terminal/blob/main/stateMachine.hpp) and [`stateMachine.cpp`](https://github.com/microsoft/terminal/blob/main/stateMachine.cpp), with additional engine implementations in `InputStateMachineEngine` and `OutputStateMachineEngine`.

### What is the difference between the input and output VT engines?

The **`InputStateMachineEngine`** processes incoming VT sequences from console input, converting escape sequences into internal actions and events. The **`OutputStateMachineEngine`** handles the opposite direction, generating VT escape sequences for terminal output and rendering. Both implement the `IStateMachineEngine` interface but operate on different data flows within the terminal architecture.

### How does the VT parser handle different sequence types like CSI and DCS?

The `StateMachine` tracks the current parsing state using the `VTStates` enum. When it encounters sequence introducers like `ESC[` (CSI) or `ESC P` (DCS), it transitions to the appropriate state (CsiEntry or DcsEntry). Upon completion, it invokes the corresponding virtual method on the engine—`ActionCsiDispatch()` for CSI sequences or `ActionDcsDispatch()` for DCS sequences—passing the parsed `VTID` and `VTParameters`.

### Can the VT parser be used independently of Windows Terminal?

While the VT parser is designed specifically for Windows Terminal's architecture, the modular design using the `IStateMachineEngine` interface allows for custom implementations. Developers can instantiate the `StateMachine` with custom engines by implementing the pure virtual methods in `IStateMachineEngine`, making it possible to reuse the parsing logic in other C++ projects that require ANSI/VT-100 sequence processing.