### Start Vagrant VM

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README-VAGRANT.md

Navigate to the vagrant directory and start the virtual machine. The initial setup may take around 20 minutes.

```bash
cd vagrant
vagrant up  # First time will take ~20 minutes
```

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

### Development Setup Commands

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Commands for setting up the development environment, checking code, running examples, and formatting.

```bash
cargo check
```

```bash
cd terminator/examples
cargo run --example basic
```

```bash
cargo test
```

```bash
cargo fmt
```

```bash
cargo clippy
```

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

### Start the Vagrant VM

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README.md

Use this command to initiate the virtual machine. Ensure Vagrant and VirtualBox are installed.

```bash
vagrant up
```

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

### Setup Node.js Bindings

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Install and build the Node.js bindings for Terminator.

```bash
cd ../terminator-nodejs
npm install
npm run build
```

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

### Start Terminator AI Summarizer for Example Workflow

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Initiate the AI summarizer with AI mode enabled and a specified model, preparing for the example workflow.

```bash
# If installed with short name
ai-summarizer --ai-mode --model "gemma3:8b"
```

```bash
# If installed with full name
terminator-ai-summarizer --ai-mode --model "gemma3:8b"
```

```bash
# If built from source
./target/release/examples/terminator-ai-summarizer --ai-mode --model "gemma3:8b"
```

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

### Install Dependencies

Source: https://github.com/mediar-ai/terminator/blob/main/examples/mcp-client-elicitation/README.md

Run this command to install project dependencies.

```bash
npm install
```

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

### Setup Python Bindings

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Install the Python bindings for Terminator in editable mode.

```bash
cd packages/terminator-python
pip install -e .
```

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

### Install @mediar-ai/kv

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Install the package using npm.

```bash
npm install @mediar-ai/kv
```

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

### Start Development VM with Script

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Use the provided batch script to quickly start the development virtual machine. Navigate to the script's directory first.

```cmd
cd C:\Users\louis\Documents\terminator\vagrant
start-dev-vm.cmd
```

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

### Install AI Summarizer CLI

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Install the terminator-ai-summarizer as a command-line interface tool. You can install it with a custom name or the default example name, and optionally create a shell alias for convenience.

```bash
# Install with custom short name 'ai-summarizer'
cargo install --path terminator-mcp-agent --bin ai-summarizer

# Or install the full example name
cargo install --path terminator-mcp-agent --example terminator-ai-summarizer --force

# Or create an alias for a shorter command
echo 'alias ais="terminator-ai-summarizer"' >> ~/.bashrc  # Linux/macOS
```

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

### Original Example: Desktop Automation Script

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

An example script using the 'node' engine to interact with desktop elements, locate buttons, and perform clicks.

```yaml
tool_name: execute_sequence
arguments:
  steps:
    - tool_name: run_command
      arguments:
        engine: "node"
        script: |
          // Access desktop automation APIs
          const elements = await desktop.locator('role:button').all();
          log(`Found ${elements.length} buttons`);
          
          // Interact with UI elements
          for (const element of elements) {
            const name = await element.name();
            if (name.includes('Submit')) {
              await element.click();
              break;
            }
          }
          
          return {
            buttons_found: elements.length,
            action: 'clicked_submit'
          };
```

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

### Install Terminator CLI on Windows

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Run the CLI directly using npx or bunx without global installation, or install it globally using npm.

```bash
npx @mediar-ai/cli --help
bunx @mediar-ai/cli --help

npm install -g @mediar-ai/cli
```

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

### Install Terminator CLI on Windows

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Install the npm wrapper for the Terminator CLI on Windows. This is the recommended installation method for Windows users.

```bash
npm install -g @mediar-ai/cli
```

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

### Start Development VM Manually

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Manually start the development virtual machine using Vagrant commands. This involves changing to the Vagrant directory and running 'vagrant up'.

```cmd
cd C:\Users\louis\Documents\terminator\vagrant
vagrant up
```

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

### Workflow File Example

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

An example workflow file demonstrating a sequence of tools, including navigation, clicking elements, and running JavaScript for data extraction.

```yaml
tool_name: execute_sequence
arguments:
  steps:
    - tool_name: navigate_browser
      arguments:
        url: "https://example.com"
    - tool_name: click_element
      arguments:
        selector: "role:Button && name:Submit"
    - tool_name: get_applications_and_windows_list
      id: get_apps
    - tool_name: run_command
      engine: javascript
      id: extract_pid
      run: |
        const apps = get_apps_result[0]?.applications || [];
        const focused = apps.find(app => app.is_focused);
        return { pid: focused?.pid || 0 };
    - tool_name: get_window_tree
      arguments:
        pid: "{{extract_pid.pid}}"
      id: capture_result
  output_parser:
    ui_tree_source_step_id: capture_result
    javascript_code: |
      // Extract all checkbox names
      const results = [];
      
      function findElementsRecursively(element) {
          if (element.attributes && element.attributes.role === 'CheckBox') {
              const item = {
                  name: element.attributes.name || ''
              };
              results.push(item);
          }
          
          if (element.children) {
              for (const child of element.children) {
                  findElementsRecursively(child);
              }
          }
      }
      
      findElementsRecursively(tree);
      return results;
```

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

### Install Vagrant Prerequisites

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Run this PowerShell script as Administrator to install Scoop, VirtualBox, and Vagrant. Ensure you are in the correct directory.

```powershell
cd C:\Users\louis\Documents\terminator\vagrant
PowerShell -ExecutionPolicy Bypass -File setup-vagrant.ps1
```

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

### Install Terminator AI Summarizer CLI

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Install the AI summarizer as a global CLI tool using Cargo. This is the recommended installation method for easy access.

```bash
cargo install --git https://github.com/mediar-ai/terminator --bin ai-summarizer terminator-mcp-agent
```

```bash
git clone https://github.com/mediar-ai/terminator.git
cd terminator
cargo install --path terminator-mcp-agent --bin ai-summarizer
```

```bash
cargo install --git https://github.com/mediar-ai/terminator --example terminator-ai-summarizer terminator-mcp-agent
```

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

### Install @mediar-ai/workflow and Zod

Source: https://github.com/mediar-ai/terminator/blob/main/packages/workflow/README.md

Install the workflow SDK and Zod for schema validation using npm.

```bash
npm install @mediar-ai/workflow zod
```

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

### Run Double Click Demo Example

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-workflow-recorder/README.md

Execute the double click demo using Cargo. This command will build and run the example, showcasing double click detection with position and UI element logging, as well as timing and distance filtering.

```bash
cargo run --example double_click_demo
```

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

### Verify Vagrant and VirtualBox Installation

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Check if Vagrant and VirtualBox are installed correctly by verifying their versions.

```cmd
vagrant --version
VBoxManage --version
```

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

### Rust Doc Comment Example

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Demonstrates how to document public APIs in Rust, including arguments, usage examples, and platform-specific notes. Ensure all public APIs are documented.

```rust
/// Locates an element on the desktop using the specified selector.
///
/// # Arguments
///
/// * `selector` - A selector string (e.g., "name:Button", "id:submit")
///
/// # Examples
///
/// ```rust
/// let button = desktop.locator("name:Save").await?;
/// button.click().await?;
/// ```
///
/// # Platform Notes
///
/// On Windows, uses UIAutomation. On macOS, uses Accessibility APIs.
pub async fn locator(&self, selector: &str) -> Result<Element> {
    // implementation
}
```

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

### Quick Start: Create and Run a Simple Workflow

Source: https://github.com/mediar-ai/terminator/blob/main/packages/workflow/README.md

Defines input schema, creates two steps (open app, type greeting), builds a workflow, and runs it with input.

```typescript
import { createStep, createWorkflow, z } from '@mediar-ai/workflow';

// Define input schema
const InputSchema = z.object({
  userName: z.string().default('World'),
});

// Create steps
const openApp = createStep({
  id: 'open-app',
  name: 'Open Notepad',
  execute: async ({ desktop }) => {
    desktop.openApplication('notepad');
    await desktop.delay(2000);
  },
});

const typeGreeting = createStep({
  id: 'type-greeting',
  name: 'Type Greeting',
  execute: async ({ desktop, input }) => {
    const textbox = await desktop.locator('role:Edit').first(2000);
    await textbox.typeText(`Hello, ${input.userName}!`);
  },
});

// Create workflow
const workflow = createWorkflow({
  name: 'Simple Demo',
  input: InputSchema,
})
  .step(openApp)
  .step(typeGreeting)
  .build();

// Run it
workflow.run({ userName: 'Alice' });

```

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

### Build Summarizer from Source

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Compile the terminator-ai-summarizer example from source. This requires building the terminator-mcp-agent dependency first.

```bash
# Build the MCP agent (dependency)
cargo build --release --bin terminator-mcp-agent

# Build the summarizer
cargo build --example terminator-ai-summarizer --release
```

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

### Python SDK - Basic Usage

Source: https://github.com/mediar-ai/terminator/blob/main/llms.txt

A concise example of how to use the Python SDK for basic desktop automation tasks, including locating elements and performing actions.

```APIDOC
## Python SDK Usage

```python
from terminator import Desktop

desktop = Desktop()
locator = desktop.locator("process:notepad >> role:Edit")
element = locator.first(timeout_ms=5000)
element.type_text("Hello")
element.click()
```
```

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

### Start MCP Client with Local Agent Build

Source: https://github.com/mediar-ai/terminator/blob/main/examples/mcp-client-elicitation/README.md

Starts the MCP client in stdio mode using a local build of the terminator-mcp-agent.

```bash
LOCAL_BUILD=1 npm run start:stdio
```

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

### Install Terminator CLI from Source on macOS/Linux

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Compile and install the Terminator CLI from source on macOS and Linux systems using Cargo.

```bash
cargo install --path crates/terminator-cli
```

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

### Install Terminator CLI

Source: https://github.com/mediar-ai/terminator/blob/main/CLAUDE.md

Install the Terminator CLI globally or run it directly using npx. Use the CLI for release management to ensure version synchronization.

```bash
npx @mediar-ai/cli --help  # Run without install
npm i -g @mediar-ai/cli    # Or install globally
```

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

### Basic KV Operations and Atomic Locking

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Demonstrates setting, getting, and deleting values. Includes an example of using `set` with `nx` and `ex` options for atomic locking to prevent race conditions.

```typescript
import { kv } from '@mediar-ai/kv';

async function main() {
  // Set a value
  await kv.set('user:123', 'Alice');

  // Get a value
  const user = await kv.get('user:123');
  console.log(user); // 'Alice'

  // Atomic Lock (useful for preventing race conditions)
  const acquired = await kv.set('lock:resource:A', 'locked', { nx: true, ex: 60 });
  
  if (acquired) {
    try {
      console.log('Lock acquired, doing work...');
    } finally {
      await kv.del('lock:resource:A');
    }
  } else {
    console.log('Could not acquire lock.');
  }
}
```

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

### Build Terminator AI Summarizer from Source

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Build the AI summarizer example from local source code. This involves cloning the repository and building the necessary components.

```bash
git clone https://github.com/mediar-ai/terminator.git
cd terminator
```

```bash
cargo build --release --bin terminator-mcp-agent
```

```bash
cargo build --example terminator-ai-summarizer --release
```

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

### Install sccache via Cargo

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Install sccache, a distributed compilation cache, using Cargo. This is an optional step to speed up build times.

```bash
cargo install sccache
```

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

### Verify sccache installation

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Verify that sccache is installed and accessible by checking its version and showing cache statistics.

```bash
sccache --version
```

```bash
sccache --show-stats
```

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

### WindowManager Example Usage

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Demonstrates how to use the WindowManager to find a window, bring it to the front, and manage window states for automation workflows. Requires updating the window cache before querying.

```javascript
const { WindowManager } = require('terminator.js');

const wm = new WindowManager();

// Get topmost Chrome window
await wm.updateWindowCache();
const chromeWindow = await wm.getTopmostWindowForProcess('chrome');
if (chromeWindow) {
  console.log(`Chrome: ${chromeWindow.title} (hwnd: ${chromeWindow.hwnd})`);

  // Bring to front
  await wm.bringWindowToFront(chromeWindow.hwnd);
}

// Workflow pattern: capture state, do work, restore
await wm.captureInitialState();
try {
  // ... perform automation
} finally {
  await wm.restoreAllWindows();
}
```

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

### Troubleshoot MCP Startup

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README-VAGRANT.md

PowerShell commands to check if the MCP process is running, manually start it, and view startup logs.

```powershell
# Check if MCP is running
Get-Process terminator* -ErrorAction SilentlyContinue

# Manually start MCP
C:\Users\vagrant\terminator\target\release\terminator-mcp-agent.exe -t http --host 0.0.0.0 -p 8080

# Check logs
Get-Content C:\MCP\logs\mcp-startup.log
```

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

### Basic KV Operations

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Demonstrates the basic usage of setting, getting, and deleting keys, as well as performing atomic locks.

```APIDOC
## Basic KV Operations

### Description
This section covers the fundamental operations for interacting with the Key-Value store, including setting values, retrieving them, deleting them, and implementing atomic locks to prevent race conditions.

### Methods
- `set(key, value, { ex?, nx?, xx? })`: Sets a key-value pair. Supports optional expiration time in seconds (`ex`) and conditional setting (`nx` for not exists, `xx` for already exists).
- `get(key)`: Retrieves the string value associated with a given key.
- `del(key)`: Removes a key and its associated value from the store.
- `expire(key, seconds)`: Sets an expiration time in seconds for an existing key.
- `incr(key)`: Increments an integer value associated with a key. Returns the new value.

### Examples
```typescript
import { kv } from '@mediar-ai/kv';

// Set a value
await kv.set('user:123', 'Alice');

// Get a value
const user = await kv.get('user:123');
console.log(user); // 'Alice'

// Atomic Lock (useful for preventing race conditions)
// Set a lock with a 60-second expiry if the key does not already exist
const acquired = await kv.set('lock:resource:A', 'locked', { nx: true, ex: 60 });

if (acquired) {
  try {
    console.log('Lock acquired, doing work...');
  } finally {
    await kv.del('lock:resource:A'); // Release the lock
  }
} else {
  console.log('Could not acquire lock.');
}

// Increment a counter
await kv.incr('counter:requests');
```
```

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

### Terminator CLI Desktop API Examples (JavaScript)

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Illustrates how to use desktop automation APIs within JavaScript scripts executed by the CLI. Includes element discovery, interaction, property access, and utility functions.

```javascript
// Element discovery
const elements = await desktop.locator('role:Button && name:Submit').all();
const element = await desktop.locator('#button-id').first();

// Element interaction
await element.click();
await element.type('Hello World');
await element.setToggled(true);

// Property access
const name = await element.name();
const bounds = await element.bounds();
const isEnabled = await element.enabled();

// Utilities
log('Debug message');  // Logging
await sleep(1000);     // Delay in milliseconds
```

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

### MCP Agent Setup

Source: https://github.com/mediar-ai/terminator/blob/main/llms.txt

Instructions for setting up the MCP agent for Terminator, including one-liner commands and configuration for different environments.

```APIDOC
## MCP Agent Setup

### Claude Code
```bash
claude mcp add terminator "npx -y terminator-mcp-agent@latest"
```

### Cursor, VS Code, Windsurf Configuration
```json
{
  "mcpServers": {
    "terminator-mcp-agent": {
      "command": "npx",
      "args": ["-y", "terminator-mcp-agent@latest"]
    }
  }
}
```

### Agent Features
The MCP agent exposes desktop automation as MCP tools. It supports stdio and HTTP transport modes. HTTP mode includes `/health`, `/status`, and `/mcp` endpoints with configurable concurrency (`MCP_MAX_CONCURRENT` env var).
```

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

### Project Structure

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Overview of the directory structure for the terminator-mcp-agent's AI summarizer example.

```tree
terminator-mcp-agent/examples/terminator-ai-summarizer/
├── src/
│   ├── main.rs      # Main application logic
│   ├── utils.rs     # CLI arguments & logging
│   ├── client.rs    # MCP client integration
│   └── ollama.rs    # Ollama API integration
└── README.md        # This file
```

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

### Window Management

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Provides methods for interacting with the current desktop window, including getting its properties, minimizing, maximizing, and setting transparency.

```APIDOC
## Window Management

### Description
Control and query the properties of the current desktop window.

### Methods
- `getCurrentWindow()`: Returns the current window object.
- `minimizeWindow()`: Minimizes the current window.
- `maximizeWindow()`: Maximizes the current window.
- `setTransparency(level)`: Sets the transparency level of the window (0-100).

### Usage
```javascript
// Get current window
const window = await desktop.getCurrentWindow();
console.log('Window:', window.name());

// Minimize/maximize
window.minimizeWindow();
window.maximizeWindow();

// Set transparency
window.setTransparency(80); // 80% opaque
```
```

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

### Initialize Terminator.js in Engine Mode

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Example of how to initialize Terminator.js within an engine mode context for JavaScript.

```javascript
{
  "engine": "javascript",
  "run": `
    const { Desktop } = require('terminator.js');
    const desktop = new Desktop();
    // Your automation code here
  `
}
```

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

### Basic Workflow Recording in Rust

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-workflow-recorder/README.md

Starts, performs a workflow, stops, and saves the recorded data. Ensure to handle potential errors during these operations.

```rust
use terminator_workflow_recorder::{WorkflowRecorder, WorkflowRecorderConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = WorkflowRecorderConfig::default();
    let mut recorder = WorkflowRecorder::new("My Workflow".to_string(), config);

    recorder.start().await?;

    // ... perform your workflow ...

    recorder.stop().await?;
    recorder.save("workflow.json")?;

    Ok(())
}
```

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

### Direct Workflow YAML Example

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Defines a simple workflow with a single step to navigate to a URL. Supports `stop_on_error` flag.

```yaml
steps:
  - tool_name: navigate_browser
    arguments:
      url: "https://example.com"
stop_on_error: true
```

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

### Workflow: Conditional Logic with run_command (Node.js)

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Example of using the `run_command` tool with the Node.js engine to perform conditional UI interactions based on element state.

```yaml
# Conditional logic based on UI state
- tool_name: run_command
  arguments:
    engine: "node"
    script: |
      const submitButton = await desktop.locator('role:Button && name:Submit').first();
      const isEnabled = await submitButton.enabled();
      
      if (isEnabled) {
        await submitButton.click();
        return { action: 'submitted' };
      } else {
        log('Submit button is disabled, checking form validation...');
        return { action: 'validation_needed' };
      }
```

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

### Get All Application UI Trees

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Retrieve the UI trees for all currently running applications. This operation can be resource-intensive.

```javascript
// Get all app trees (expensive)
const allTrees = await desktop.getAllApplicationsTree();
console.log(`Found ${allTrees.length} applications`);
```

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

### Start Interactive MCP Chat

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Initiate an interactive chat session with an MCP server. Uses the local server by default.

```bash
terminator mcp chat
```

```bash
terminator mcp chat --url https://your-server.com/mcp
```

```bash
terminator mcp chat --command "node my-mcp-server.js"
```

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

### Permanent sccache setup for Bash/Zsh

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Permanently enable sccache by adding the RUSTC_WRAPPER export to your shell profile file.

```bash
# Bash/Zsh
export RUSTC_WRAPPER=sccache
```

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

### Compile Terminator CLI from Source on macOS/Linux

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Compile the release binary from the workspace root. Optionally, install it globally using cargo.

```bash
cargo build --release --bin terminator

cargo install --path crates/terminator-cli
```

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

### Start MCP Client in stdio Mode

Source: https://github.com/mediar-ai/terminator/blob/main/examples/mcp-client-elicitation/README.md

Launches the MCP client in stdio mode, spawning the agent as a child process and connecting via stdio transport for interactive tool usage.

```bash
npm run start:stdio
```

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

### Example Elicitation Interaction

Source: https://github.com/mediar-ai/terminator/blob/main/examples/mcp-client-elicitation/README.md

Simulates an interactive elicitation flow where the client prompts the user to fill in required fields based on a server request and collects the data.

```text
============================================================
ELICITATION REQUEST
============================================================

Message: What is the business purpose of this workflow?

Please fill in the following fields (or type 'cancel' to cancel, 'decline' to decline):

  What is the business purpose of this automation?: Automate invoice processing
  Target application name (optional): Excel
  Expected outcome or success criteria (optional): All invoices processed

----------------------------------------
Collected data: {
  "business_purpose": "Automate invoice processing",
  "target_app": "Excel",
  "expected_outcome": "All invoices processed"
}

Submit this data? (yes/no): yes

```

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

### Tool Call Wrapper JSON Example

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Wraps a workflow step within an `execute_sequence` tool call. This format is used for more complex orchestration.

```json
{
  "tool_name": "execute_sequence",
  "arguments": {
    "steps": [
      {
        "tool_name": "navigate_browser",
        "arguments": {
          "url": "https://example.com"
        }
      }
    ]
  }
}
```

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

### Example Usage of Selector Class

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Demonstrates how to scope selectors to a specific process and window, and then locate an element using the typed selector API. Requires the desktop object to be available.

```typescript
// Scope to process and window
const selector = Selector.process("notepad")
  .chain(Selector.window("Untitled"))
  .chain(Selector.role("Edit"));

// Find element using typed selector
const editor = await desktop.locator(selector).first(5000);
```

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

### Optimize Large UI Trees

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/README.md

Configure performance settings for handling large UI trees by limiting depth, specifying a starting selector, or choosing a compact output format. These options help manage complexity and improve extraction speed.

```bash
# Limit depth for large trees
tree_max_depth: 30

# Get subtree from specific element
tree_from_selector: "role:List"

# Start from focused element
tree_from_selector: "true"

# Readable format (default) or "verbose_json" for full data
tree_output_format: "compact_yaml"
```

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

### MCP Agent Setup for IDEs

Source: https://github.com/mediar-ai/terminator/blob/main/llms.txt

Configure the MCP agent for IDEs like Cursor, VS Code, and Windsurf by adding the agent details to the MCP configuration file. This specifies the command and arguments for running the agent.

```json
{
  "mcpServers": {
    "terminator-mcp-agent": {
      "command": "npx",
      "args": ["-y", "terminator-mcp-agent@latest"]
    }
  }
}
```

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

### Start MCP Client in HTTP Mode

Source: https://github.com/mediar-ai/terminator/blob/main/examples/mcp-client-elicitation/README.md

Connects the MCP client to a pre-existing terminator-mcp-agent running in HTTP mode. Optionally specify a port.

```bash
npm run start:http [port]
```

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

### Instantiate Desktop Class

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Shows how to create a new instance of the Desktop class, optionally configuring background app usage, app activation, and logging level.

```javascript
new Desktop(useBackgroundApps?: boolean, activateApp?: boolean, logLevel?: string)
```

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

### Clone Terminator Repository

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/README.md

Clone the Terminator repository to start local development. Navigate to the agent's directory and install Node.js dependencies.

```sh
# 1. Clone the entire Terminator repository
git clone https://github.com/mediar-ai/terminator

# 2. Navigate to the agent's directory
cd terminator/terminator-mcp-agent

# 3. Install Node.js dependencies
npm install

# 4. Build the Rust binary and Node.js wrapper
npm run build

# 5. To use your local build in your MCP client, link it globally
npm install --global .
```

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

### Get UI Subtree from Specific Element

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Obtain the UI tree for a subtree starting from a specific UI element, with an option to limit the depth of the traversal. This is useful for inspecting only a portion of the UI.

```javascript
// Get subtree from specific element
const dialog = await desktop.locator('role:Dialog && name:Settings').first(5000);
const dialogTree = dialog.getTree(3);  // Limit to 3 levels deep
console.log(`Dialog has ${dialogTree.children.length} immediate children`);
```

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

### Manual Client Initialization

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Illustrates creating custom client instances for different backends (Redis, File, Memory) using the `createClient` function with specific configuration URLs or backend types.

```typescript
import { createClient } from '@mediar-ai/kv';

// Redis
const redisKv = createClient({ url: 'redis://user:pass@host:6379' });

// File (Persistent local JSON file)
const fileKv = createClient({ url: 'file://./data/workflow-state.json' });

// Memory (Ephemeral, good for tests)
const memKv = createClient({ backend: 'memory' });
```

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

### Client Initialization

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Provides details on how to configure and create KV client instances, including automatic detection and manual initialization.

```APIDOC
## Client Initialization

### Description
This section explains how to initialize the KV client, covering both automatic configuration via environment variables and manual setup with specific options.

### Automatic Configuration
The client automatically detects the backend configuration based on environment variables. If no variables are set, it defaults to a file-based store.

#### Environment Variables
- `KV_URL` or `REDIS_URL`: Specifies the connection URL for the backend.
  - **Redis**: `redis://localhost:6379` or `redis://user:pass@host:port`
  - **File**: `file://./path/to/your/db.json`
  - **Memory**: `memory://` (for ephemeral storage)

### Manual Initialization
You can create a custom client instance using the `createClient` function, providing configuration options.

#### `createClient(options)`

- `options.url` (string): The connection URL for the backend (e.g., `redis://...`, `file://...`).
- `options.backend` (string): Explicitly specify the backend ('redis', 'file', 'memory').

#### Examples
```typescript
import { createClient } from '@mediar-ai/kv';

// Initialize with Redis using a URL
const redisKv = createClient({
  url: 'redis://user:pass@host:6379'
});

// Initialize with a file-based store
const fileKv = createClient({
  url: 'file://./data/workflow-state.json'
});

// Initialize with an in-memory store
const memKv = createClient({
  backend: 'memory'
});
```
```

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

### Build MCP on Host

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README-VAGRANT.md

Build the MCP release binary on the host machine. This is recommended for performance.

```bash
cd /c/Users/louis/Documents/terminator
cargo build --release
```

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

### Install Terminator MCP Agent Automatically

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/README.md

Run this command to automatically install and configure the Terminator MCP agent. It will prompt you to select your MCP client.

```bash
npx -y terminator-mcp-agent@latest --add-to-app
```

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

### Basic Automation with Desktop

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Demonstrates basic automation tasks using the Desktop class, such as locating and interacting with UI elements, and opening URLs.

```APIDOC
## Usage Examples

### Basic Automation
```javascript
const { Desktop } = require('terminator.js');

const desktop = new Desktop();

// Find and click a button (timeout required)
const buttonLocator = desktop.locator('role:button|Save');
const button = await buttonLocator.first(5000);  // 5 second timeout
await button.click();

// Type into a text field
const inputLocator = desktop.locator('role:textfield');
const input = await inputLocator.first(5000);
await input.typeText('Hello World', { clearBeforeTyping: true });

// Open a URL
desktop.openUrl('https://example.com', 'Chrome');
```
```

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

### Display CLI Help

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Shows all available commands and options for the Terminator CLI.

```bash
terminator --help
```

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

### Desktop Class Constructor

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Initializes the Desktop class, which is the main entry point for desktop automation. Optional parameters can configure background app usage, initial app activation, and logging level.

```APIDOC
## new Desktop()

### Description
Initializes the Desktop class for desktop automation.

### Parameters
- **useBackgroundApps** (boolean) - Optional - Whether to allow automation of background applications.
- **activateApp** (boolean) - Optional - Whether to activate the application when interacting with it.
- **logLevel** (string) - Optional - Sets the logging level for the Terminator.js instance.
```

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

### Workflow: Dynamic Discovery with run_command (JavaScript)

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Shows how to dynamically discover and interact with UI elements using `run_command` and JavaScript, such as finding and clicking download buttons.

```yaml
# Dynamic element discovery and interaction
- tool_name: run_command
  arguments:
    engine: "javascript"
    script: |
      // Find all buttons containing specific text
      const buttons = await desktop.locator('role:button').all();
      const targets = [];
      
      for (const button of buttons) {
        const name = await button.name();
        if (name.toLowerCase().includes('download')) {
          targets.push(name);
          await button.click();
          await sleep(1000);
        }
      }
      
      return { downloaded_items: targets };
```

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

### Install Terminator MCP Agent with Claude

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/README.md

Use this command to install the Terminator MCP agent via Claude. It adds the agent to your user's MCP client configuration.

```bash
claude mcp add terminator "npx -y terminator-mcp-agent@latest" -s user
```

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

### Tree Extraction

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Retrieve the UI element tree starting from a specific element.

```APIDOC
## Tree Extraction

- `getTree(maxDepth?: number): UINode` - Get UI tree starting from this element (default depth: 100)
```

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

### Run Workflow with Server Connection Options

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Execute a workflow with different options for connecting to the MCP server, including local, specific versions, HTTP, and custom commands.

```bash
terminator mcp run workflow.yml
```

```bash
terminator mcp run workflow.yml --command "npx -y terminator-mcp-agent@0.9.0"
```

```bash
terminator mcp run workflow.yml --url http://localhost:3000/mcp
```

```bash
terminator mcp run workflow.yml --command "python my_mcp_server.py"
```

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

### Resume Suspended Vagrant VM

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Start a previously suspended Vagrant VM, restoring it to its saved state.

```bash
vagrant resume
```

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

### Quick RDP Connection to Vagrant VM

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README.md

Automatically launches the default RDP client with the correct connection details for the VM.

```bash
vagrant rdp
```

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

### Range Controls (Sliders)

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Methods for getting and setting the value of range controls like sliders and progress bars.

```APIDOC
## Range Controls (Sliders)

- `getRangeValue(): number` - Get current slider/progress value
- `setRangeValue(value: number): void` - Set slider value
```

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

### Basic Automation with Desktop Class

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Illustrates basic UI automation tasks using the Desktop class, including locating and clicking elements, typing text into fields, and opening URLs.

```javascript
const { Desktop } = require('terminator.js');

const desktop = new Desktop();

// Find and click a button (timeout required)
const buttonLocator = desktop.locator('role:button|Save');
const button = await buttonLocator.first(5000);  // 5 second timeout
await button.click();

// Type into a text field
const inputLocator = desktop.locator('role:textfield');
const input = await inputLocator.first(5000);
await input.typeText('Hello World', { clearBeforeTyping: true });

// Open a URL
desktop.openUrl('https://example.com', 'Chrome');
```

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

### Start Chrome with Remote Debugging

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/README-VAGRANT.md

Launch Chrome with the remote debugging port enabled and specify the extension directory for development.

```powershell
chrome.exe --remote-debugging-port=9222 --load-extension="C:\Users\vagrant\terminator\browser-extension"
```

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

### Python SDK Basic Usage

Source: https://github.com/mediar-ai/terminator/blob/main/llms.txt

Utilize the Python SDK for straightforward desktop automation. Remember to specify the `timeout_ms` parameter when locating elements.

```python
from terminator import Desktop

desktop = Desktop()
locator = desktop.locator("process:notepad >> role:Edit")
element = locator.first(timeout_ms=5000)
element.type_text("Hello")
element.click()
```

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

### Permanent sccache setup for PowerShell

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Permanently enable sccache for PowerShell by setting the RUSTC_WRAPPER environment variable in your PowerShell profile.

```powershell
# PowerShell
$env:RUSTC_WRAPPER = "sccache"
```

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

### Workflow: Bulk Operations with run_command (JavaScript)

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Demonstrates using `run_command` with JavaScript to perform bulk operations on multiple UI elements, such as toggling checkboxes.

```yaml
# Bulk operations on multiple elements
- tool_name: run_command
  arguments:
    engine: "javascript"
    script: |
      const checkboxes = await desktop.locator('role:checkbox').all();
      let enabledCount = 0;
      
      for (const checkbox of checkboxes) {
        await checkbox.setToggled(true);
        enabledCount++;
        await sleep(50); // Small delay between operations
      }
      
      return { total_enabled: enabledCount };
```

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

### Setup sccache for current session

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

Temporarily enable sccache for the current terminal session by setting the RUSTC_WRAPPER environment variable.

```bash
export RUSTC_WRAPPER=sccache
```

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

### Manage Windows with Terminator.js

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Control application windows by getting the current window, minimizing, maximizing, or setting its transparency level.

```javascript
// Get current window
const window = await desktop.getCurrentWindow();
console.log('Window:', window.name());

// Minimize/maximize
window.minimizeWindow();
window.maximizeWindow();

// Set transparency
window.setTransparency(80); // 80% opaque
```

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

### List Operations (Queues)

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Shows how to use `lpush` to add elements to the beginning of a list and `rpop` to remove and retrieve an element from the end, simulating a queue.

```typescript
await kv.lpush('queue:invoices', 'inv_001', 'inv_002');
const nextItem = await kv.rpop('queue:invoices');
```

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

### Get All Applications Tree

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Retrieves the UI trees for all running applications. This method returns a promise that resolves to an array of UINodes.

```javascript
desktop.getAllApplicationsTree(): Promise<Array<UINode>>
```

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

### List Operations (Queues)

Source: https://github.com/mediar-ai/terminator/blob/main/packages/kv/README.md

Shows how to use list operations for implementing queue-like behavior.

```APIDOC
## List Operations (Queues)

### Description
This section details how to use list operations to manage queues, allowing for adding elements to the beginning or end and removing them from either end.

### Methods
- `lpush(key, ...elements)`: Prepends one or more elements to the beginning of a list.
- `rpush(key, ...elements)`: Appends one or more elements to the end of a list.
- `lpop(key)`: Removes and returns the first element from a list.
- `rpop(key)`: Removes and returns the last element from a list.

### Examples
```typescript
// Add items to the beginning of a queue
await kv.lpush('queue:invoices', 'inv_001', 'inv_002');

// Remove and get the last item from the queue
const nextItem = await kv.rpop('queue:invoices');
console.log(nextItem); // 'inv_002' (if 'inv_001' and 'inv_002' were pushed)
```
```

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

### Re-provision Vagrant VM

Source: https://github.com/mediar-ai/terminator/blob/main/vagrant/QUICK-START.md

Run the provisioning scripts again on the Vagrant VM to update installed tools or configurations without destroying the VM.

```bash
vagrant provision
```

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

### Using Tool Results in Subsequent Steps

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/README.md

Demonstrates how to capture results from previous tool executions (like DOM content or element validation) and utilize them as input for subsequent steps, such as running custom scripts.

```yaml
steps:
  # Capture browser DOM
  - id: capture_dom
    tool_name: execute_browser_script
    arguments:
      selector: "role:Window"
      script: "return document.documentElement.innerHTML;"

  # Validate an element exists
  - id: check_button
    tool_name: validate_element
    arguments:
      selector: "role:Button && name:Submit"

  # Use both results in script
  - tool_name: run_command
    arguments:
      engine: javascript
      run: |
        // All tool results are auto-injected as variables
        const dom = capture_dom_result?.content || '';
        const buttonExists = check_button_status === 'success';

        if (buttonExists) {
          const button = check_button_result[0]?.element;
          console.log(`Submit button at: ${button?.bounds?.x}, ${button?.bounds?.y}`);
        }

        return { dom_length: dom.length, has_button: buttonExists };
```

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

### CLI Usage

Source: https://github.com/mediar-ai/terminator/blob/main/llms.txt

Demonstrates how to use the Mediar AI CLI for version management, synchronization, release, and running workflows.

```APIDOC
## CLI Usage

### General Help
```bash
npx @mediar-ai/cli --help
```

### Version Management
```bash
terminator patch | minor | major
terminator sync
terminator release
```

### Running Workflows
```bash
terminator mcp run workflow.yml
terminator mcp run workflow.yml --start-from "step_5" --end-at "step_8"
terminator mcp run workflow.yml --dry-run
```

### Workflow File Formats
Workflow files can be YAML or JSON, supporting conditional jumps between steps and engine-mode code execution (JavaScript or Python).
```

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

### Monitor Interface Definition

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Describes a display monitor, including its dimensions, position, scale factor, and primary status. Useful for multi-monitor setups.

```typescript
interface Monitor {
  id: string
  name: string
  isPrimary: boolean
  width: number
  height: number
  x: number
  y: number
  scaleFactor: number
}
```

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

### Desktop Class - Window & Tree Management

Source: https://github.com/mediar-ai/terminator/blob/main/docs/TERMINATOR_JS_API.md

Methods for managing windows and retrieving UI element trees for automation.

```APIDOC
## Desktop Window & Tree Management

### Methods
- **getCurrentWindow(): Promise<Element>** - Gets the currently focused window element.
- **getCurrentApplication(): Promise<Element>** - Gets the currently focused application element.
- **getCurrentBrowserWindow(): Promise<Element>** - Gets the currently focused browser window element.
- **activateBrowserWindowByTitle(title: string): void** - Activates a browser window based on its title.
- **getWindowTree(process: string, title?: string, config?: TreeBuildConfig): UINode** - Retrieves the UI element tree for a specific window identified by process and optionally title, using provided configuration.
- **getWindowTreeResult(process: string, title?: string, config?: TreeBuildConfig): WindowTreeResult** - **Recommended:** Retrieves the full result of a window tree, including formatted output and `indexToBounds` mapping.
- **getWindowTreeResultAsync(process: string, title?: string, config?: TreeBuildConfig): Promise<WindowTreeResult>** - Async version of `getWindowTreeResult`, supporting `treeFromSelector`.
```

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

### Run Terminator AI Summarizer - Basic Mode

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Execute the AI summarizer in basic mode to capture UI context and copy it to the clipboard. This mode does not use AI.

```bash
# If installed with short name
ai-summarizer
```

```bash
# If installed with full name
terminator-ai-summarizer
```

```bash
# If built from source
./target/release/examples/terminator-ai-summarizer
```

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

### Run All Tests and Checks

Source: https://github.com/mediar-ai/terminator/blob/main/CONTRIBUTING.md

A single command to format code, lint with clippy, and run all tests before submitting changes.

```bash
cargo fmt && cargo clippy && cargo test
```

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

### Launch Chromium with Extension

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/browser-extension/README.md

Use this command to launch Chromium with the extension loaded, specifying the absolute path to the browser extension folder.

```sh
chromium --load-extension=/absolute/path/to/browser-extension
```

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

### Run with Debug Logs

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/examples/terminator-ai-summarizer/README.md

Enable debug logging for the terminator-ai-summarizer by setting the LOG_LEVEL environment variable. This can be done when running the globally installed version or a locally built executable.

```bash
# If installed globally
LOG_LEVEL=debug terminator-ai-summarizer --ai-mode

# If built from source
LOG_LEVEL=debug ./target/release/examples/terminator-ai-summarizer --ai-mode
```

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

### Add Terminator MCP Agent via Claude CLI

Source: https://github.com/mediar-ai/terminator/blob/main/README.md

Use this command to add the Terminator MCP agent when using Claude. Ensure Claude is installed and configured.

```bash
claude mcp add terminator "npx -y terminator-mcp-agent@latest"
```

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

### Successful Data Extraction Output Parser

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-mcp-agent/docs/WORKFLOW_OUTPUT_STRUCTURE.md

Example JavaScript code for an output parser that successfully extracts and formats data, returning a success status and a list of items.

```javascript
// Output parser code
const items = tree.findAll('[data-testid="invoice"]');
return {
  success: items.length > 0,
  message: `Found ${items.length} invoices`,
  data: items.map(item => ({
    id: item.getAttribute('data-id'),
    amount: item.querySelector('.amount')?.text,
    date: item.querySelector('.date')?.text
  }))
};
```

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

### Execute MCP Tool with Custom Server

Source: https://github.com/mediar-ai/terminator/blob/main/crates/terminator-cli/README.md

Execute an MCP tool and specify a different MCP server URL.

```bash
terminator mcp exec --url http://localhost:3000/mcp validate_element '{"selector": "#button"}'
```