### Example: Explain missing command installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/prompts/auto-fix.md

An example of an 'explain' action for a situation where a command ('claude') is not installed. The explanation details why an auto-fix isn't possible and provides installation instructions.

```json
{"action": "explain", "title": "claude is not installed", "explanation": "The `claude` command isn't on PATH (Anthropic Claude Code CLI).\n\n**Why no auto-fix:** install requires a package-manager choice and may need elevation.\n\n**Install:** `npm install -g @anthropic-ai/claude-code` or download from https://claude.com/code. Restart the shell after."}
```

--------------------------------

### WT Agent Startup and Installation Flow

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/wt-agent-hooks/README.md

Illustrates the startup process of the wta binary and the subsequent installation of CLIs like Claude, Copilot, and Gemini. It shows the resolution and installation steps for each CLI.

```text
              wta startup
                   │
   ┌───────────────┼───────────────┐
   ▼               ▼               ▼
install_for_  install_for_  install_for_
  claude       copilot        gemini
   │               │               │
resolve         resolve         resolve
claude/         copilot/        gemini-extension/
   │               │               │
   ▼               ▼               ▼
 claude          copilot         gemini
 plugin          plugin          extensions
 marketplace     marketplace     install
 add ...         add ...         <bundle>
   │               │
   ▼               ▼
 claude          copilot
 plugin          plugin
 install         install
 wt-agent-hooks  wt-agent-hooks
 @wt-local       @wt-local
```

--------------------------------

### Start Profile in Specific Directory

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Starts the default profile in the specified starting directory. Supports long and short argument forms, and both forward and backward slashes for paths.

```sh
wt new-tab --startingDirectory "c:/Users/Foo/dev/MyProject"
wt --startingDirectory "c:/Users/Foo/dev/MyProject"
wt -d "c:/Users/Foo/dev/MyProject"
# Windows-style paths work too
wt -d "c:\\Users\\Foo\\dev\\MyProject"
```

--------------------------------

### Manual Plugin Installation for Testing

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/wt-agent-hooks/README.md

Provides commands for manually installing agent hook plugins for Claude, Copilot, and Gemini for testing purposes without using the `wta` startup process.

```powershell
# Claude
claude plugin marketplace add .\wta\wt-agent-hooks\claude
claude plugin install wt-agent-hooks@wt-local

# Copilot
copilot plugin marketplace add .\wta\wt-agent-hooks\copilot
copilot plugin install wt-agent-hooks@wt-local

# Gemini
gemini extensions install .\wta\wt-agent-hooks\gemini-extension
```

--------------------------------

### Install and Verify Dependencies

Source: https://github.com/microsoft/intelligent-terminal/blob/main/test/e2e/README.md

Installs necessary dependencies and imports the Intelligent Terminal module. The -Check flag can be used to verify only.

```powershell
pwsh -File test/e2e/bootstrap.ps1          # install deps, import module
pwsh -File test/e2e/bootstrap.ps1 -Check   # verify only
```

--------------------------------

### Install Gemini CLI

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Installs the Google Gemini CLI globally using npm. This is a prerequisite for using Gemini with Intelligent Terminal.

```powershell
npm install -g @google/gemini-cli
```

--------------------------------

### Native commands for installing agent hooks (for reference)

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

These are the underlying native commands invoked by `wta hooks install`. You typically do not need to run these directly.

```bash
copilot plugin marketplace add <bundle>\copilot
copilot plugin install wt-agent-hooks@wt-local
```

```bash
claude plugin marketplace add <bundle>\claude
claude plugin install wt-agent-hooks@wt-local
```

```bash
codex plugin marketplace add <bundle>\codex
codex plugin add wt-agent-hooks@wt-local
```

```bash
gemini extensions install <bundle>\gemini-extension --consent --skip-settings
```

--------------------------------

### Check WinGet Installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Run this command in PowerShell or Command Prompt to check if winget is already installed. If a version number is displayed, winget is ready to use.

```powershell
winget --version
```

--------------------------------

### Start Headless MCP Mode

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/PLAN.md

Starts the wta tool in headless mode, responding to Microsoft Component Protocol (MCP) tool discovery.

```bash
wta --mcp
```

--------------------------------

### Profile List Structure Example

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

An example of how the profiles list could be structured to include separators and folders for menu organization. This approach was considered but not pursued due to complexity.

```json
"profiles": {
  "defaults": {},
  "list":
  [
    { "name": "cmd" },
    { "name": "powershell" },
    { "type": "separator" },
    {
      "type": "folder" ,
      "profiles": [
        { "name": "ubuntu" }
      ]
    }
  ]
}
```

--------------------------------

### Agent Hook Bridge Install Path

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/security-model.md

Details the installation process for agent hooks, starting from the Settings UI or WTA setup and leading to persistent CLI hook registration via plugin managers.

```text
Settings UI / WTA setup / wta hooks install
  -> agent_hooks_installer::ensure_installed()
  -> resolve wt-agent-hooks bundle
  -> Claude / Copilot plugin manager or Gemini extension manager
  -> persistent CLI hook registration
```

--------------------------------

### Install Gemini Extension

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/wt-agent-hooks/gemini-extension/README.md

Installs the wt-agent-hooks Gemini extension. This command is used for manual installation, for example, during fresh-clone testing.

```bash
gemini extensions install <repo>\wta\wt-agent-hooks\gemini-extension
```

--------------------------------

### Example Theme Configuration

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/drafts/

This JSON snippet demonstrates how to define multiple themes, including their names and specific UI element properties for window, tab, and tabRow.

```json
{
    "theme": "My Boxy Theme",
    "themes": [
        {
            "name": "My Boxy Theme",
            "window":{
              "applicationTheme": "dark"
            },
            "tab": {
              "radius": 0,
              "padding": 5,
              "background": "terminalBackground",
              "textColor": "key:SystemAccentColorLight3",
              "icon": "outline",
              "closeButton": "hidden"
            },
            "tabRow":{
              "background": "accent",
              "shadows": false
            }
        },
        {
            "name": "My small light theme",
            "window":{
              "applicationTheme": "light"
            },
            "tab": {
              "background": "#80ff0000",
              "height": 8,
              "icon": "hidden",
              "closeButton": "hover"
            },
            "tabRow":{
              "background": "#ffffffff",
              "acrylicOpacity": 50
            }
        }
    ]
}
```

--------------------------------

### Keybinding Example

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Shows a keybinding configuration that maps a keyboard shortcut to a specific Action ID.

```json
{ "keys": "ctrl+alt+x", "id": "Terminal.OpenDefaultSettings" }
```

--------------------------------

### Cygwin Profile Configuration

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/user-docs/ThirdPartyToolProfiles.md

Define a Cygwin profile with its specific bash executable, login flag, icon, and a starting directory within the Cygwin installation.

```json
{
    "name": "Cygwin",
    "commandline": "C:\\Cygwin\\bin\\bash --login -i",
    "icon": "C:\\Cygwin\\Cygwin.ico",
    "startingDirectory": "C:\\Cygwin\\bin"
}
```

--------------------------------

### MSYS2 Profile Configuration

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/user-docs/ThirdPartyToolProfiles.md

Define a profile for MSYS2, including the shell command with specific arguments, icon path, and a user-specific starting directory within the MSYS2 installation.

```json
{
    "name": "MSYS2",
    "commandline": "C:\\msys64\\msys2_shell.cmd -defterm -no-start -mingw64",
    "icon": "C:\\msys64\\msys2.ico",
    "startingDirectory": "C:\\msys64\\home\\user"
}
```

--------------------------------

### Quake Mode Settings Example

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

This JSON snippet illustrates potential configuration options for Quake Mode, including focus behavior, profile selection, and docking side.

```json
{
    "quakeMode": {
        "hideOnFocusLost": true,
        "useFocusMode": false,
        "profile": "my quake mode profile" ,
        "quakeModeDockSide": "bottom"
    }
}
```

--------------------------------

### AgentProfile Struct with Setup Metadata

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/agent-oobe-design.md

Adds human-readable install and authentication hint fields to the AgentProfile struct in Rust. These fields provide guidance to the user when an agent is not found or not authenticated.

```rust
pub struct AgentProfile {
    // ... existing fields ...

    /// Human-readable install instruction shown when binary not found.
    pub install_hint: &'static str,
    /// Command the user should run to authenticate (empty if N/A).
    pub auth_hint: &'static str,
}
```

--------------------------------

### Load Configuration from File

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

The `--file` or `-f` argument allows loading a configuration file to specify a list of commands for startup. The first command in the file creates the window, and subsequent commands add to that window.

```bash
wt --file configuration-file.conf
```

```bash
wt -f configuration-file.conf
```

--------------------------------

### Install WinGet via Sideload

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

If the Microsoft Store installation is not possible, you can sideload the latest release of App Installer from GitHub. This command installs the .msixbundle package.

```powershell
Add-AppxPackage -Path .\Microsoft.DesktopAppInstaller_*.msixbundle
```

--------------------------------

### Example Commandline with Split Pane and New Tab

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

This commandline demonstrates splitting a pane and then opening a new tab. The behavior assumes an implicit 'new-tab' command if not explicitly provided first.

```sh
wt.exe split-pane -V ; new-tab
```

--------------------------------

### Verify Gemini CLI Installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Verifies the installation of the Gemini CLI by checking its version. Ensure this command runs successfully after installation.

```powershell
gemini --version
```

--------------------------------

### Full JSON File Example with Profiles and Color Scheme

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/Proto extensions-spec.md

An example of a complete JSON file that includes modifications to existing profiles, creation of a new profile, and definition of a new color scheme.

```js
{
  "profiles": [
    {
      "updates": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
      "fontSize": 16,
      "fontWeight": "thin"
    },
    {
      "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}",
      "name": "Cool Profile",
      "commandline": "powershell.exe",
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "scrollbarState": "hidden"
    }
  ],
  "schemes": [
    {
        "name": "Postmodern Tango Light",

        "cursorColor": "#FFFFFF",
        "selectionBackground": "#FFFFFF",

        "background": '#61D6D6',
        "foreground": '#E74856',

        "black" : "#0C0C0C",
        "blue" : "#0037DA",
        "cyan" : "#3A96DD",
        "green" : "#13A10E",
        "purple" : "#881798",
        "red" : "#C50F1F",
        "white" : "#CCCCCC",
        "yellow" : "#C19C00",
        "brightBlack" : "#767676",
        "brightBlue" : "#3B78FF",
        "brightCyan" : "#61D6D6",
        "brightGreen" : "#16C60C",
        "brightPurple" : "#B4009E",
        "brightRed" : "#E74856",
        "brightWhite" : "#F2F2F2",
        "brightYellow" : "#F9F1A5"
    }
  ]
}
```

--------------------------------

### Verify OpenAI Codex Installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Verifies the installation of the OpenAI Codex CLI by checking its version. Ensure this command runs successfully after installation.

```powershell
codex --version
```

--------------------------------

### Prepopulate Suggestions UI with Current Commandline

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Use this action to open the Suggestions UI filtered by the user's current commandline input. Requires shell integration to be enabled.

```json
{ "command": { "action":"suggestions", "source": "commandHistory", "useCommandline": true } }
```

--------------------------------

### Verify Claude Code Installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Verifies the installation of the Claude Code CLI by checking its version. Ensure this command runs successfully after installation.

```powershell
claude --version
```

--------------------------------

### Run Command in New Pane and Monitor

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/SKILLS.md

Demonstrates a workflow to split a pane, run a build command, wait for it to finish, and then check the status and capture output. Assumes pane IDs are sequential.

```bash
# 1. Split a pane for the build
wta split-pane -v -c "cargo build 2>&1"
# Response: "Created pane 5"

# 2. Wait for it to finish
wta wait-for -t 5 --timeout 120

# 3. Check the result
wta pane-status -t 5
wta capture-pane -t 5 -l 30
```

--------------------------------

### Verify Agent CLI Hooks Installation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Run this command to check if the agent CLI hooks are successfully installed. Look for 'installed' status for your selected agent.

```powershell
wta hooks status
```

--------------------------------

### Ansi-Color.cmd Usage Example

Source: https://github.com/microsoft/intelligent-terminal/blob/main/src/tools/ansi-color/README.md

Demonstrates the basic command-line usage of the ansi-color.cmd script, including how to specify flags and definition files.

```plain
Usage: ansi-color.cmd [flags] [<definition_file>]

   This file echoes a bunch of color codes to the terminal to demonstrate
   how they will render. The `Data Segment` portion of the file defines the
   table layout and allows the user to configure whatever matrix of ANSI
   Escape Sequence control characters they wish. This can also be read from
   an external definition file using the same structure.

   Flags:
     /H  :  This message
     /A  :  Display the ANSI Escape Sequence control characters
     /R  :  Show cell R1C1 reference addressing instead of cell text
     /U  :  Enable UTF-8 support

   The script itself only has one external dependency on CHCP if you want
   to show Unicode text. This just sets the Command Prompt codepage to 65001
   and will restore it when the script successfully completes.
   
```

--------------------------------

### Install MSIX Package

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/building-installer.md

Use this PowerShell script to install the MSIX package on a target machine. It handles uninstallation of previous versions, certificate import, and MSIX installation.

```powershell
# Extract the ZIP, then run (no admin needed if cert is already trusted):
powershell -ExecutionPolicy Bypass -File .\Install-Msix.ps1
```

--------------------------------

### Build and Run WTA

Source: https://github.com/microsoft/intelligent-terminal/blob/main/tools/wta/README.md

Instructions for building the WTA tool and running it. It includes options for auto-discovering the pipe or setting environment variables manually.

```bash
cd wta
cargo build

# Option 1: Auto-discover pipe (run inside Windows Terminal)
target/debug/wta.exe

# Option 2: Set env vars for the session
eval "$(target/debug/wta.exe set-env)"
target/debug/wta.exe
```

--------------------------------

### Agent Install and Auth Hints Table

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/agent-oobe-design.md

Provides specific install and authentication hint strings for various agents (copilot, claude, codex, gemini). This data is used to populate the install_hint and auth_hint fields in the AgentProfile.

```markdown
| Agent | `install_hint` |
|---|---|
| copilot | `"Install: npm install -g @githubnext/github-copilot-cli\n  Info: https://github.com/github/copilot-cli"` | `"Run: gh auth login\n or: copilot auth"` |
| claude | `"Install: npm install -g @anthropic/claude-cli\n  Info: https://claude.ai/cli"` | `""` |
| codex | `"Install: npm install -g @openai/codex\n  Info: https://github.com/openai/codex"` | `""` |
| gemini | `"Install: npm install -g @google/gemini-cli\n  Info: https://github.com/google-gemini/gemini-cli"` | `""` |
```

--------------------------------

### Open Settings UI with Format and Page Args

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Opens the Settings UI using the 'openSettings' action with 'ui' format and 'settings' page. This approach separates format and page for more granular control.

```json
{
  "command": { "action": "openSettings", "format": "ui", "page": "settings" }
}
```

--------------------------------

### Install agent hooks using wta

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Run these commands to install agent hooks for session management. Ensure the agent CLI is installed and on PATH, and that you are using a new terminal window.

```powershell
wta hooks install --cli copilot
```

```powershell
wta hooks install --cli claude
```

```powershell
wta hooks install --cli codex
```

```powershell
wta hooks install --cli gemini
```

--------------------------------

### Install GitHub Copilot CLI with winget

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/installing-dependencies.md

Install the GitHub Copilot CLI using winget. This is the default agent for Intelligent Terminal and is automatically installed by the first-run experience if not already present.

```powershell
winget install --id GitHub.Copilot --exact --silent \
  --source winget \
  --accept-source-agreements --accept-package-agreements \
  --disable-interactivity
```

--------------------------------

### Setup Build Environment and Formatting in PowerShell

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/building.md

Imports the OpenConsole PowerShell module, sets up the MSBuild development environment, and retrieves the clang-format executable. This is required for Visual Studio code formatting setup.

```powershell
Import-Module .\tools\OpenConsole.psm1
Set-MsBuildDevEnvironment
Get-Format
```

--------------------------------

### Functions for Namespace and Name-Based GUID Generation

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Exposes functions for generators to retrieve their namespace GUID and to generate a UUIDv5 GUID within their namespace for a given name key. These are convenience functions.

```c++
GUID GetNamespaceGuid(IDynamicProfileGenerator& generator);
GUID GetGuidForName(IDynamicProfileGenerator& generator, std::wstring& name);
```

--------------------------------

### CLI Session Launch and Registration Steps

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/wta-launched-cli-session-binding.md

Outlines the sequence of actions taken when a CLI session is launched by Windows Terminal, including UUID generation, command construction, tab creation, and session registration with the master process.

```text
1. id  = (a,b) generate a v4 UUID  |  (c) the resume key
2. cmd = <cli> ... <new_session_id_flag> <id>          (flag from agent_registry)
3. TabCreationResult = COM create_tab / split_pane(cmd)   -> pane GUID + Pid
4. register the session with wta-master   { id, cli, cwd, pane_guid }
       -> master upserts a SessionInfo with
            pane_session_id = pane_guid,
            cli_source      = cli,
            origin          = Unknown,        (Class B — unchanged)
            status          = Idle
```

--------------------------------

### Keybindings with Single Argument

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/

Examples of how keybindings will be defined using the new argument system for actions like new tab, switch tab, resize pane, and move focus.

```json
{ "keys": ["ctrl+shift+1"], "command": "newTabProfile", "args": { "profileIndex":0 } },
{ "keys": ["ctrl+shift+2"], "command": "newTabProfile", "args": { "profileIndex":1 } },
// etc...

{ "keys": ["alt+1"], "command": "switchToTab", "args": { "index":0 } },
{ "keys": ["alt+2"], "command": "switchToTab", "args": { "index":1 } },
// etc...

{ "keys": ["alt+shift+down"], "command": "resizePane", "args": { "direction":"down" } },
{ "keys": ["alt+shift+up"], "command": "resizePane", "args": { "direction":"up" } },
// etc...

{ "keys": ["alt+down"], "command": "moveFocus", "args": { "direction":"down" } },
{ "keys": ["alt+up"], "command": "moveFocus", "args": { "direction":"up" } }
```

--------------------------------

### Define Setup State Structure

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/agent-oobe-design.md

Defines the structure to hold the state of the setup wizard, including the agent ID, a list of setup checks, the currently selected item, and whether an action is in progress.

```rust
pub struct SetupState {
    pub agent_id: String,
    pub checks: Vec<SetupCheck>,
    pub selected_index: usize,
    pub action_in_progress: bool,
}

```

--------------------------------

### CLI Usage Examples for `wtcli send-event`

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/llm-agent-event-integration.md

Demonstrates how to use the `wtcli send-event` command with different options for specifying event type, parameters, and target pane.

```bash
# Simple lifecycle event
wtcli send-event -e agent.started '{"agent":"copilot-cli","version":"1.2.0"}'

# Task completion with exit code
wtcli send-event -p 3 -e agent.task.completed '{"task_id":"abc","exit_code":0,"summary":"Built successfully"}'

# Minimal — just the event type (pane auto-resolved from active pane)
wtcli send-event -e agent.idle
```

--------------------------------

### Define Individual Setup Check Structure

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/agent-oobe-design.md

Defines the structure for a single setup check, including its label, status, help text, and an optional associated action. This is used to represent each step in the setup process.

```rust
pub struct SetupCheck {
    pub label: String,
    pub status: CheckStatus,
    pub help_text: String,
    pub action: Option<SetupAction>,
}

```

--------------------------------

### UX Mockup: Agent Not Installed Message

Source: https://github.com/microsoft/intelligent-terminal/blob/main/doc/specs/agent-oobe-design.md

Displays a user-friendly error message when an AI agent is not installed or not found on the system's PATH. It includes the agent's name, installation instructions, and a link to more information.

```text
Error: 'GitHub Copilot' is not installed or not on your PATH.

  Install: npm install -g @githubnext/github-copilot-cli
     Info: https://github.com/github/copilot-cli

  After installing, restart your terminal and try again.
```