### Pilotty Quick Start Commands

Source: https://github.com/msmps/pilotty/blob/main/README.md

Basic commands to get started with Pilotty, including spawning applications, capturing screen state, and sending input.

```bash
# Spawn a TUI application
pilotty spawn htop

# Take a snapshot of the terminal
pilotty snapshot

# Type text
pilotty type "hello world"

# Send keys
pilotty key Enter
pilotty key Ctrl+C

# Click at specific coordinates (row, col)
pilotty click 10 5

# List active sessions
pilotty list-sessions

# Stop the daemon
pilotty stop
```

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

### Install pilotty CLI

Source: https://github.com/msmps/pilotty/blob/main/npm/README.md

Global installation of the pilotty package via npm.

```bash
npm install -g pilotty
```

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

### Creating Sessions

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/session-management.md

Examples for spawning default and named sessions.

```bash
pilotty spawn htop
# Creates session named "default"

pilotty snapshot
# Snapshots the "default" session
```

```bash
pilotty spawn --name monitoring htop
pilotty spawn --name editor vim file.txt
pilotty spawn --name git lazygit
```

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

### Quick Start Workflow

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Basic sequence for launching a TUI application, interacting with it, and terminating the session.

```bash
pilotty spawn vim file.txt        # Start TUI app in managed session
pilotty wait-for "file.txt"       # Wait for app to be ready
pilotty snapshot                  # Get screen state with UI elements
pilotty key i                     # Enter insert mode
pilotty type "Hello, World!"      # Type text
pilotty key Escape                # Exit insert mode
pilotty kill                      # End session
```

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

### View Plain Text Snapshot

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Example output when using the --format text flag.

```text
---
--- Terminal 80x24 | Cursor: (5, 10) ---
bash-3.2$ [_]
```

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

### Complete Workflow Example

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

A comprehensive bash script demonstrating spawning an application, analyzing its initial state, interacting with UI elements (toggling), and verifying changes.

```bash
#!/bin/bash
SESSION="form"

# 1. Spawn application
pilotty spawn --name $SESSION dialog --checklist "Options:" 15 50 4 \
    "opt1" "Feature A" on \
    "opt2" "Feature B" off \
    "opt3" "Feature C" on \
    "opt4" "Feature D" off

sleep 0.5

# 2. Analyze initial state
echo "Initial state:"
pilotty snapshot -s $SESSION | jq '.elements[] | select(.kind == "toggle") | {text, checked}'

# 3. Find unchecked toggles
UNCHECKED=$(pilotty snapshot -s $SESSION | jq '[.elements[] | select(.kind == "toggle" and .checked == false)] | length')
echo "Unchecked toggles: $UNCHECKED"

# 4. Navigate and toggle opt2
pilotty key -s $SESSION Down   # Move to opt2
pilotty key -s $SESSION Space  # Toggle it

# 5. Verify change via content_hash
HASH1=$(pilotty snapshot -s $SESSION | jq -r '.content_hash')
echo "Hash after toggle: $HASH1"

# 6. Confirm and check final state
pilotty key -s $SESSION Enter
sleep 0.3

echo "Final state:"
pilotty snapshot -s $SESSION | jq '.elements[] | select(.kind == "toggle") | {text, checked}'

# 7. Cleanup
pilotty kill -s $SESSION

```

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

### POST /spawn

Source: https://context7.com/msmps/pilotty/llms.txt

Starts a terminal application in a background PTY session.

```APIDOC
## POST /spawn

### Description
Starts a terminal application in a background PTY session. The daemon starts automatically on the first command.

### Method
POST

### Endpoint
pilotty spawn [command]

### Parameters
#### Query Parameters
- **--name** (string) - Optional - Creates a named session for managing multiple applications.
- **--cwd** (string) - Optional - Specifies the working directory for the command.

### Response
#### Success Response (200)
- **session_id** (string) - Unique identifier for the session.
- **name** (string) - Name of the session.
- **command** (string) - The command executed.
```

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

### Button Element Detection Example

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Example JSON output for a detected button element, showing its kind, position, text, and confidence.

```json
{
  "kind": "button",
  "row": 10,
  "col": 5,
  "width": 6,
  "text": "[Save]",
  "confidence": 0.8
}
```

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

### Troubleshooting Key Recognition

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Provides examples for distinguishing between named keys and plain text input in pilotty.

```bash
# Check if it's a named key or text
pilotty key Enter     # Named key
```

```bash
pilotty type "hello"  # Text input
```

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

### Input Element Detection Example

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Example JSON output for a detected input element, detailing its kind, position, text, and confidence.

```json
{
  "kind": "input",
  "row": 8,
  "col": 12,
  "width": 10,
  "text": "__________",
  "confidence": 0.6
}
```

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

### Toggle Element Detection Example

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Example JSON output for a detected toggle element, including its kind, position, text, confidence, and checked state.

```json
{
  "kind": "toggle",
  "row": 5,
  "col": 2,
  "width": 3,
  "text": "[x]",
  "confidence": 1.0,
  "checked": true
}
```

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

### Run Application in Specific Directory

Source: https://github.com/msmps/pilotty/blob/main/README.md

Starts an application within a specified working directory. This is useful for managing project-specific configurations or dependencies.

```bash
# Run app in a specific directory (useful for project-specific configs)
pilotty spawn --cwd /path/to/project --name myapp bun src/index.tsx
```

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

### Snapshot Output Format

Source: https://github.com/msmps/pilotty/blob/main/npm/README.md

Example of the structured JSON data returned by the snapshot command.

```json
{
  "snapshot_id": 42,
  "size": { "cols": 80, "rows": 24 },
  "cursor": { "row": 5, "col": 10, "visible": true },
  "text": "... plain text content ..."
}
```

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

### Handle Spawn Failed Error

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Example JSON error response for a failed spawn operation, suggesting to check command existence and PATH.

```json
{
  "code": "SPAWN_FAILED",
  "message": "Failed to spawn process: command not found",
  "suggestion": "Check that the command exists and is in PATH"
}
```

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

### GET /snapshot

Source: https://context7.com/msmps/pilotty/llms.txt

Captures the current state of the terminal screen, including text, cursor position, and UI elements.

```APIDOC
## GET /snapshot

### Description
Returns structured JSON data about the terminal screen including text content, cursor position, detected UI elements, and a content hash for change detection.

### Method
GET

### Endpoint
pilotty snapshot

### Parameters
#### Query Parameters
- **--format** (string) - Optional - Output format (compact, text).
- **-s** (string) - Optional - Target specific session name.
- **--await-change** (integer) - Optional - Wait for screen to change based on provided content hash.
- **--settle** (integer) - Optional - Wait for screen to stabilize after change (ms).
- **-t** (integer) - Optional - Timeout in milliseconds.

### Response
#### Success Response (200)
- **snapshot_id** (integer) - ID of the snapshot.
- **size** (object) - Terminal dimensions (cols, rows).
- **cursor** (object) - Cursor position and visibility.
- **text** (string) - Terminal text content.
- **elements** (array) - Detected UI elements (buttons, toggles).
- **content_hash** (integer) - Hash for change detection.
```

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

### Content Hash for Change Detection

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Example JSON snippet showing the content_hash field, used for detecting screen changes between snapshots.

```json
{
  "content_hash": 12345678901234567890,
  ...
}
```

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

### Spawn TUI Applications

Source: https://context7.com/msmps/pilotty/llms.txt

Starts terminal applications in background PTY sessions. Use --name for session identification and --cwd for directory context.

```bash
# Spawn a basic TUI application (creates "default" session)
pilotty spawn htop

# Spawn with a custom session name (--name MUST come before the command)
pilotty spawn --name editor vim file.txt

# Spawn in a specific working directory
pilotty spawn --cwd /path/to/project --name myapp bun src/index.tsx

# Spawn multiple isolated sessions
pilotty spawn --name monitoring htop
pilotty spawn --name git lazygit
pilotty spawn --name preview watch -n1 python main.py

# Output on success:
# {"session_id": "abc123", "name": "editor", "command": "vim file.txt"}
```

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

### Build from Source

Source: https://github.com/msmps/pilotty/blob/main/npm/README.md

Steps to clone and build the project using Cargo.

```bash
git clone https://github.com/msmps/pilotty
cd pilotty
cargo build --release
./target/release/pilotty --help
```

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

### Monitor with Htop

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Spawning and waiting for a monitoring tool to display.

```bash
# 1. Spawn htop
pilotty spawn --name monitor htop

# 2. Wait for display
pilotty wait-for -s monitor "CPU"
```

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

### Automate Vim Workflow

Source: https://github.com/msmps/pilotty/blob/main/README.md

Demonstrates spawning a process, waiting for content, interacting via keyboard, and verifying session state.

```bash
# 1. Spawn the application
pilotty spawn vim myfile.txt

# 2. Wait for it to be ready
pilotty wait-for "myfile.txt"

# 3. Take a snapshot to understand the screen and capture hash
HASH=$(pilotty snapshot | jq '.content_hash')

# 4. Navigate using keyboard commands
pilotty key i                    # Enter insert mode
pilotty type "Hello, World!"
pilotty key Escape

# 5. Wait for screen to update, then save (no manual sleep needed!)
pilotty snapshot --await-change $HASH --settle 50
pilotty key "Escape : w q Enter"  # vim :wq sequence

# 6. Verify vim exited
pilotty list-sessions
```

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

### Wait for Application Readiness Before Action

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Spawns an application and waits for a specific readiness string before proceeding to take a snapshot.

```bash
pilotty spawn my-app
pilotty wait-for "Ready"    # Ensure app is ready
pilotty snapshot            # Then snapshot
```

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

### Nano Text Editor Basic Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates basic key presses for common operations in the nano text editor.

```bash
pilotty key Ctrl+O    # Save
```

```bash
pilotty key Ctrl+X    # Exit
```

```bash
pilotty key Ctrl+K    # Cut line
```

```bash
pilotty key Ctrl+U    # Paste
```

```bash
pilotty key Ctrl+W    # Search
```

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

### Navigation Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Standard keyboard-first navigation and interaction commands.

```bash
# 1. Take snapshot to see the screen
pilotty snapshot --format text

# 2. Navigate using keyboard
pilotty key Tab           # Move to next element
pilotty key Enter         # Activate/select
pilotty key Escape        # Cancel/back
pilotty key Up            # Move up in list/menu
pilotty key Space         # Toggle checkbox

# 3. Type text when needed
pilotty type "search term"
pilotty key Enter

# 4. Click at coordinates for mouse-enabled TUIs
pilotty click 5 10        # Click at row 5, col 10
```

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

### Detecting Screen Changes with Content Hash

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Bash script demonstrating how to use pilotty and jq to compare content hashes and detect screen changes.

```bash
HASH1=$(pilotty snapshot | jq -r '.content_hash')
pilotty key Tab
HASH2=$(pilotty snapshot | jq -r '.content_hash')
[ "$HASH1" != "$HASH2" ] && echo "Screen changed"
```

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

### Get First Focused TUI Element

Source: https://context7.com/msmps/pilotty/llms.txt

Retrieve the first TUI element that currently has focus. This is useful for interacting with the active element.

```bash
pilotty snapshot | jq '.elements[] | select(.focused == true)'
```

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

### Get First Toggle Element

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Retrieves the first UI element identified as a 'toggle'. This is helpful for interacting with the initial toggle in a list.

```bash
pilotty snapshot | jq '[.elements[] | select(.kind == "toggle")][0]'
```

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

### Htop Key Bindings

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates common key presses for interacting with the htop process viewer.

```bash
pilotty key F1        # Help
```

```bash
pilotty key F2        # Setup
```

```bash
pilotty key F5        # Tree view
```

```bash
pilotty key F9        # Kill process
```

```bash
pilotty key F10       # Quit
```

```bash
pilotty key q         # Also quit
```

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

### Basic Pilotty Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Basic commands for scrolling and capturing snapshots of a TUI application.

```bash
pilotty scroll -s myapp up 10
pilotty snapshot -s myapp --format text
```

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

### Send Keystroke Commands to Session

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Sends keystroke commands to a target session. Examples include triggering menu actions or quitting applications.

```bash
pilotty key -s monitor F9    # Kill menu
```

```bash
pilotty key -s monitor q     # Quit
```

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

### Multi-Session TUI Orchestration

Source: https://context7.com/msmps/pilotty/llms.txt

Demonstrates parallel management of multiple TUI applications (htop, vim, lazygit) using independent named sessions. Includes spawning, waiting for readiness, and basic interaction.

```bash
#!/bin/bash

# 1. Start multiple apps with named sessions
pilotty spawn --name cpu htop
pilotty spawn --name editor vim /tmp/notes.txt
pilotty spawn --name git lazygit

# 2. Wait for each to be ready
pilotty wait-for -s cpu "CPU"
pilotty wait-for -s editor "notes.txt"
pilotty wait-for -s git "Status"

# 3. Interact with each independently
# Check CPU usage
pilotty snapshot -s cpu --format text
```

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

### AI TUI Streaming Response Handling

Source: https://context7.com/msmps/pilotty/llms.txt

Example for interacting with AI applications that stream responses. Uses longer `settle` and `timeout` values to accommodate gradual output and potential pauses.

```bash
#!/bin/bash
SESSION="ai"

# 1. Spawn the AI app
pilotty spawn --name "$SESSION" opencode

# 2. Wait for the prompt to be ready
pilotty wait-for -s "$SESSION" "Ask anything" -t 15000

# 3. Capture baseline hash
HASH=$(pilotty snapshot -s "$SESSION" | jq -r '.content_hash')

# 4. Type prompt and submit
pilotty type -s "$SESSION" "explain the architecture of this codebase"
pilotty key -s "$SESSION" Enter

# 5. Wait for streaming response to complete
#    - settle=3000: Wait 3s of no changes (AI pauses between chunks)
#    - timeout=60000: Allow up to 60s for long responses
pilotty snapshot -s "$SESSION" --await-change "$HASH" --settle 3000 -t 60000 --format text

# 6. If response is long and scrolled, scroll up to see full output
pilotty scroll -s "$SESSION" up 20
pilotty snapshot -s "$SESSION" --format text

# 7. Clean up
pilotty kill -s "$SESSION"
```

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

### Element Interaction

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Using snapshot elements to understand UI structure and keyboard commands for interaction.

```bash
# 1. Get snapshot to understand UI structure
pilotty snapshot | jq '.elements'
# Output shows toggles (checked/unchecked) and buttons with positions

# 2. Navigate and interact with keyboard (reliable approach)
pilotty key Tab          # Move to next element
pilotty key Space        # Toggle checkbox
pilotty key Enter        # Activate button

# 3. Verify state changed
pilotty snapshot | jq '.elements[] | select(.kind == "toggle")'
```

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

### Best Practices

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Recommended practices for using the Pilotty API, focusing on element understanding and interaction.

```APIDOC
## Best Practices

### 1. Elements for Understanding, Keyboard for Interaction

Elements tell you WHAT is on screen. Use keyboard to interact:

```bash
# See what's on screen
pilotty snapshot | jq '.elements[] | {kind, text, row, col, checked}'

# Navigate with keyboard
pilotty key Tab    # Move between elements
pilotty key Space  # Toggle checkboxes
pilotty key Enter  # Activate buttons
```

### 2. Check Confidence Levels

Higher confidence means more reliable detection:

```bash
# Filter to high-confidence elements only
pilotty snapshot | jq '.elements[] | select(.confidence >= 0.8)'
```

### 3. Find Elements by Content or Position

(Further details on finding elements by content or position would go here if provided in the source text.)
```

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

### Spawn TUI Dialog and Interact

Source: https://github.com/msmps/pilotty/blob/main/README.md

Automates spawning a dialog, waiting for it to render, and interacting with it using keyboard commands. Use `pilotty wait-for` to ensure UI elements are ready before interaction.

```bash
# 1. Spawn a TUI with dialog elements
pilotty spawn dialog --yesno "Continue?" 10 40

# 2. Wait for dialog to render
pilotty wait-for "Continue"

# 3. Get snapshot with elements (for context)
pilotty snapshot | jq '.elements'
# Shows detected buttons, helps understand UI structure

# 4. Navigate and interact with keyboard (reliable approach)
pilotty key Tab      # Move to next element
pilotty key Enter    # Activate selected element
```

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

### Spawn Multiple Applications in Sessions

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Spawns multiple applications, each in its own named session. The `--name` flag must precede the command.

```bash
pilotty spawn --name monitoring htop
```

```bash
pilotty spawn --name editor vim file.txt
```

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

### Wait for Screen Changes

Source: https://github.com/msmps/pilotty/blob/main/README.md

Use the --await-change flag to synchronize automation with screen updates instead of using static sleep timers.

```bash
# Capture baseline hash
HASH=$(pilotty snapshot | jq '.content_hash')

# Perform action
pilotty key Enter

# Wait for screen to change (blocks until hash differs)
pilotty snapshot --await-change $HASH

# Or wait for screen to stabilize (useful for apps that render progressively)
pilotty snapshot --await-change $HASH --settle 100  # Wait 100ms after last change
```

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

### Execute Pilotty Workflow Templates

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Run the provided shell scripts from the templates directory to perform specific workflow tasks.

```bash
./templates/vim-workflow.sh /tmp/myfile.txt "File content here"
./templates/dialog-interaction.sh
./templates/multi-session.sh
./templates/element-detection.sh
```

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

### Go to Top of File in Vim

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates the key sequence to navigate to the top of the file in Vim.

```bash
pilotty key "Escape g g"
```

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

### Interact with Vim

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Common key sequences for switching modes and executing commands in Vim.

```bash
pilotty key i         # Insert mode (use pilotty type for text)
pilotty key Escape    # Normal mode
pilotty key Ctrl+C    # Also exits insert mode
pilotty type ":wq"    # Command (then Enter)
pilotty key Enter
```

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

### List Active Sessions with Pilotty

Source: https://context7.com/msmps/pilotty/llms.txt

View all currently active Pilotty sessions by running the 'list-sessions' command.

```bash
pilotty list-sessions
```

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

### Nano Text Editor Sequence Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates key sequences for advanced operations in nano, such as saving with a default filename or exiting without saving.

```bash
pilotty key "Ctrl+O Enter"    # Save with default filename
```

```bash
pilotty key "Ctrl+X n"        # Exit without saving (answer 'n' to save prompt)
```

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

### Pilotty Command Usage

Source: https://github.com/msmps/pilotty/blob/main/npm/README.md

Common commands for spawning sessions, interacting with TUIs, and managing the daemon.

```bash
# Spawn a TUI application
pilotty spawn htop

# Spawn in a specific working directory
pilotty spawn --cwd /path/to/project bun src/app.tsx

# Take a snapshot of the terminal
pilotty snapshot

# Type text
pilotty type "hello world"

# Send keys
pilotty key Enter
pilotty key Ctrl+C

# Send key sequences (space-separated)
pilotty key "Ctrl+X m"            # Emacs chord
pilotty key "Escape : w q Enter"  # vim :wq

# Wait for screen to change (no more guessing sleep durations!)
HASH=$(pilotty snapshot | jq '.content_hash')
pilotty key Enter
pilotty snapshot --await-change $HASH --settle 50

# Click at specific coordinates (row, col)
pilotty click 10 5

# List active sessions
pilotty list-sessions

# Stop the daemon
pilotty stop
```

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

### Terminal Automation Instructions for AI Agents

Source: https://github.com/msmps/pilotty/blob/main/README.md

Provides markdown instructions for AI agents on how to use Pilotty for terminal automation. It outlines the core workflow and commands.

```markdown
## Terminal Automation

Use `pilotty` for TUI automation. Run `pilotty --help` for all commands.

Core workflow:
1. `pilotty spawn <command>` - Start a TUI application
2. `pilotty snapshot` - Get screen state with cursor position
3. `pilotty key Tab` / `pilotty type "text"` - Navigate and interact
4. Re-snapshot after screen changes
```

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

### Listing Sessions

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/session-management.md

Retrieve a list of active sessions and their associated commands.

```bash
pilotty list-sessions
```

```json
{
  "sessions": [
    { "id": "abc123", "name": "monitoring", "command": "htop" },
    { "id": "def456", "name": "editor", "command": "vim file.txt" },
    { "id": "ghi789", "name": "git", "command": "lazygit" }
  ]
}
```

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

### Less/More Paging and Navigation

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates key presses for navigating and searching within pagers like less and more.

```bash
pilotty key Space     # Page down
```

```bash
pilotty key b         # Page up
```

```bash
pilotty key q         # Quit
```

```bash
pilotty key /         # Search (then type pattern)
```

```bash
pilotty key n         # Next match
```

```bash
pilotty key N         # Previous match
```

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

### Tmux Basic Key Bindings

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates the default tmux prefix key and common commands executed after the prefix.

```bash
pilotty key Ctrl+B    # Prefix key
```

```bash
# Then send the command key:
pilotty key c         # New window
```

```bash
pilotty key n         # Next window
```

```bash
pilotty key p         # Previous window
```

```bash
pilotty key d         # Detach
```

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

### Run Multiple Applications in Named Sessions

Source: https://github.com/msmps/pilotty/blob/main/README.md

Launches multiple applications in separate, named sessions. The `--name` flag must precede the command. This allows for isolated environments for different tasks.

```bash
# Run multiple apps (--name must come before the command)
pilotty spawn --name monitoring htop
pilotty spawn --name editor vim file.txt
```

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

### Troubleshooting Timing Issues with TUIs

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Illustrates how to handle timing issues in TUIs by using pilotty wait-for to pause execution until a specific event occurs.

```bash
pilotty key F9        # Opens menu
```

```bash
pilotty wait-for "SIGTERM"  # Wait for menu
```

```bash
pilotty key Enter     # Then select
```

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

### Reliable Action with Snapshot and Await Change

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Recommended pattern for reliable command execution: capture a hash, perform an action, then wait for the state to change. This avoids fragile `sleep` commands.

```bash
# The pattern: capture hash, act, await change
HASH=$(pilotty snapshot | jq '.content_hash')
pilotty key Enter
pilotty snapshot --await-change $HASH --settle 50
```

```bash
# This replaces fragile patterns like:
# pilotty key Enter && sleep 1 && pilotty snapshot  # BAD: guessing
```

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

### Execute key sequences

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Send multiple keys in order for complex interactions like editor commands or navigation.

```bash
# Emacs-style chords
pilotty key "Ctrl+X Ctrl+S"       # Save file
pilotty key "Ctrl+X Ctrl+C"       # Exit Emacs
pilotty key "Ctrl+X m"            # Compose mail

# vim command sequences
pilotty key "Escape : w q Enter"  # Save and quit
pilotty key "Escape : q ! Enter"  # Quit without saving
pilotty key "g g d G"             # Delete entire file

# Navigation sequences
pilotty key "Tab Tab Enter"       # Tab twice then Enter
pilotty key "Down Down Space"     # Move down twice and select
```

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

### Configure Environment Variables

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Set environment variables to define default session names, socket directories, and logging levels.

```bash
PILOTTY_SESSION="mysession"       # Default session name
PILOTTY_SOCKET_DIR="/tmp/pilotty" # Override socket directory
RUST_LOG="debug"                  # Enable debug logging
```

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

### Execute Key Sequences

Source: https://github.com/msmps/pilotty/blob/main/README.md

Sends multiple keys in order, supporting chords and sequences with optional inter-key delays.

```bash
# Emacs-style chords
pilotty key "Ctrl+X Ctrl+S"       # Save in Emacs
pilotty key "Ctrl+X m"            # Compose mail in Emacs

# vim command sequences
pilotty key "Escape : w q Enter"  # Save and quit vim
pilotty key "g g d G"             # Delete entire file in vim

# With inter-key delay (useful for slow TUIs)
pilotty key "Tab Tab Enter" --delay 100   # Navigate with 100ms between keys
```

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

### Target Specific Session for Snapshot and Key Input

Source: https://github.com/msmps/pilotty/blob/main/README.md

Captures a snapshot or sends keyboard input to a specific, named session. Use the `-s` or `--session` flag followed by the session name.

```bash
# Target specific session
pilotty snapshot -s monitoring
pilotty key -s editor Ctrl+S
```

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

### Managing Sessions

Source: https://context7.com/msmps/pilotty/llms.txt

Commands for listing, killing, and configuring terminal sessions.

```bash
pilotty list-sessions

pilotty kill -s editor

pilotty kill

pilotty stop

pilotty daemon

export PILOTTY_SESSION=editor
pilotty snapshot
```

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

### Session Lifecycle Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/session-management.md

Commands for spawning new sessions and manually terminating them.

```bash
pilotty spawn --name myapp my-command arg1 arg2
```

```bash
pilotty kill -s myapp
```

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

### View Raw Screen Output

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Use this command to view the raw text output of the screen snapshot. This is helpful for troubleshooting when no elements are detected.

```bash
pilotty snapshot --format text
```

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

### Send basic key inputs

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Use these commands to send single keys or sequences to default or specific sessions.

```bash
pilotty key <key>                 # Send single key to default session
pilotty key -s myapp <key>        # Send to specific session
pilotty key "key1 key2 key3"      # Send key sequence (space-separated)
pilotty key "key1 key2" --delay 50  # Sequence with 50ms delay between keys
```

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

### Navigate Git with Pilotty

Source: https://context7.com/msmps/pilotty/llms.txt

Control navigation within a Git TUI application using Pilotty. Use 'j' to move down and 'Enter' to select an item.

```bash
pilotty key -s git j      # Move down
pilotty key -s git Enter  # Select
```

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

### List All Active Sessions

Source: https://github.com/msmps/pilotty/blob/main/README.md

Displays a list of all currently running Pilotty sessions. This is useful for managing multiple terminal applications.

```bash
# List all sessions
pilotty list-sessions
```

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

### Type Prompt and Submit in AI TUI

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Simulates typing a prompt into the AI TUI and submitting it with the Enter key.

```bash
pilotty type -s ai "explain the architecture of this codebase"
```

```bash
pilotty key -s ai Enter
```

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

### Editor and Preview Pattern

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/session-management.md

Workflow for editing code in one session while monitoring output in another.

```bash
# Start editor (--name before command)
pilotty spawn --name editor vim main.py

# Start file watcher
pilotty spawn --name preview watch -n1 python main.py

# Edit
pilotty key -s editor i
pilotty type -s editor "print('hello')"
pilotty key -s editor Escape
pilotty type -s editor ":w"
pilotty key -s editor Enter

# Check preview
pilotty snapshot -s preview --format text
```

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

### Parsing UI Elements

Source: https://context7.com/msmps/pilotty/llms.txt

Extracts structured UI element data from snapshots using jq.

```bash
pilotty snapshot | jq '.elements'

pilotty snapshot | jq '.elements[] | select(.kind == "toggle")'
pilotty snapshot | jq '.elements[] | select(.kind == "button")'
pilotty snapshot | jq '.elements[] | select(.kind == "input")'
```

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

### Session Management

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Commands to spawn, kill, and list managed PTY sessions.

```APIDOC
## Session Management

### Description
Manage the lifecycle of terminal sessions.

### Commands
- `pilotty spawn <command>`: Start a TUI app in a background PTY.
- `pilotty spawn --name <name> <command>`: Start a session with a custom name.
- `pilotty kill`: Kill the default session.
- `pilotty kill -s <name>`: Kill a specific session.
- `pilotty list-sessions`: List all active sessions.
- `pilotty shutdown`: Stop the daemon and all sessions.
```

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

### Screen Capture and Synchronization

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Methods for retrieving terminal state and waiting for screen updates.

```bash
pilotty snapshot                  # Full JSON with text content and elements
pilotty snapshot --format compact # JSON without text field
pilotty snapshot --format text    # Plain text with cursor indicator
pilotty snapshot -s myapp         # Snapshot specific session

# Wait for screen to change (eliminates need for sleep!)
HASH=$(pilotty snapshot | jq '.content_hash')
pilotty key Enter
pilotty snapshot --await-change $HASH           # Block until screen changes
pilotty snapshot --await-change $HASH --settle 50  # Wait for 50ms stability
```

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

### Environment Variables

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Environment variables that can be used to configure Pilotty.

```APIDOC
## Environment Variables

Environment variables that can be used to configure Pilotty.

- **PILOTTY_SESSION** (string): Default session name.
- **PILOTTY_SOCKET_DIR** (string): Override socket directory.
- **RUST_LOG** (string): Enable debug logging.
```

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

### Navigating and Interacting with Terminal Elements

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Bash commands for interacting with terminal UI elements using pilotty keys.

```bash
# Navigate with keyboard
pilotty key Tab    # Move between elements
pilotty key Space  # Toggle checkboxes
pilotty key Enter  # Activate buttons
```

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

### Interact with Dialog/Whiptail

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Standard key mappings for navigating dialog-based interfaces.

```bash
pilotty key Tab       # Move between buttons
pilotty key Enter     # Activate button
pilotty key Space     # Toggle checkbox
pilotty key Escape    # Cancel dialog
```

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

### Pilotty Screen Capture Commands

Source: https://github.com/msmps/pilotty/blob/main/README.md

Commands for capturing the terminal screen state in various formats and with options to wait for changes.

```bash
pilotty snapshot                  # Full JSON with text
pilotty snapshot --format compact # JSON without text field
pilotty snapshot --format text    # Plain text with cursor indicator

# Wait for screen to change before returning (no more manual sleep!)
pilotty snapshot --await-change $HASH           # Block until hash differs
pilotty snapshot --await-change $HASH --settle 100  # Then wait for stability
```

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

### Spawn AI TUI Application

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

Launches an AI-powered TUI application, such as opencode. The `--name` flag is required before the command.

```bash
pilotty spawn --name ai opencode
```

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

### Wait for Screen Changes

Source: https://github.com/msmps/pilotty/blob/main/README.md

Utilize `--await-change` and `--settle` flags for robust TUI automation by waiting for screen updates.

```APIDOC
## Wait for Screen Changes

### Description
The `--await-change` flag allows automation scripts to wait for the terminal screen to change after an action, eliminating the need for arbitrary `sleep` commands and preventing race conditions. The `--settle` flag further refines this by waiting for the screen to stabilize.

### Method
`pilotty snapshot --await-change <HASH> [--settle <MS>] [-t <MS>]`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--await-change <HASH>` (string) - Required. Block until `content_hash` differs from this value.
- `--settle <MS>` (integer) - Optional. After change detected, wait for screen to be stable for this many ms.
- `-t, --timeout <MS>` (integer) - Optional. Maximum wait time in milliseconds. Default is 30000.

### Request Example
```bash
# Capture baseline hash
HASH=$(pilotty snapshot | jq '.content_hash')

# Perform action
pilotty key Enter

# Wait for screen to change
pilotty snapshot --await-change $HASH

# Wait for screen to stabilize
pilotty snapshot --await-change $HASH --settle 100  # Wait 100ms after last change
```

### Benefits
- Prevents flaky automation due to race conditions.
- Avoids slow scripts due to conservative sleep values.
- Works regardless of the target application's speed.
- `--settle` handles applications that render progressively.
```

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

### Complete Dialog Checklist Interaction

Source: https://context7.com/msmps/pilotty/llms.txt

Automates interaction with a `dialog` checklist, including spawning, waiting, navigating, toggling options, and confirming. Demonstrates element detection and state verification.

```bash
#!/bin/bash
SESSION="dialog-demo"

# 1. Spawn dialog checklist (--name before command)
pilotty spawn --name "$SESSION" dialog --checklist "Select features:" 12 50 4 \
    "notifications" "Push notifications" on \
    "darkmode" "Dark mode theme" off \
    "autosave" "Auto-save documents" on \
    "telemetry" "Usage analytics" off

# 2. Wait for dialog to render and stabilize
pilotty snapshot -s "$SESSION" --settle 200

# 3. Get snapshot and examine toggle elements
SNAP=$(pilotty snapshot -s "$SESSION")
echo "$SNAP" | jq '.elements[] | select(.kind == "toggle") | {text, checked}'
# Output shows initial toggle states

# 4. Capture hash for change detection
HASH=$(echo "$SNAP" | jq '.content_hash')

# 5. Navigate to "darkmode" and toggle it
pilotty key -s "$SESSION" Down      # Move to second option
pilotty key -s "$SESSION" Space     # Toggle it on

# 6. Wait for change and verify new state
pilotty snapshot -s "$SESSION" --await-change $HASH | \
  jq '.elements[] | select(.kind == "toggle") | {text, checked}'
# Shows darkmode is now checked

# 7. Confirm selection
pilotty key -s "$SESSION" Enter

# 8. Clean up
pilotty kill -s "$SESSION"
```

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

### Save and Quit in Vim

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates the key sequence to save the current buffer and exit Vim.

```bash
pilotty key "Escape : w q Enter"
```

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

### Readline/Bash Navigation and Editing

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates key presses for common line editing and navigation commands in bash and other readline-based applications.

```bash
pilotty key Ctrl+A    # Beginning of line
```

```bash
pilotty key Ctrl+E    # End of line
```

```bash
pilotty key Ctrl+U    # Clear line
```

```bash
pilotty key Ctrl+R    # Reverse search
```

```bash
pilotty key Ctrl+L    # Clear screen
```

```bash
pilotty key Up        # Previous history
```

```bash
pilotty key Down      # Next history
```

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

### Awaiting Screen Changes

Source: https://context7.com/msmps/pilotty/llms.txt

Uses content hashes to detect screen updates, providing a reliable alternative to sleep commands.

```bash
HASH=$(pilotty snapshot | jq '.content_hash')
pilotty key Enter
pilotty snapshot --await-change $HASH

HASH=$(pilotty snapshot | jq '.content_hash')
pilotty key Tab
pilotty snapshot --await-change $HASH --settle 50

HASH=$(pilotty snapshot -s ai | jq -r '.content_hash')
pilotty type -s ai "explain this code"
pilotty key -s ai Enter
pilotty snapshot -s ai --await-change "$HASH" --settle 3000 -t 60000

SNAP1=$(pilotty snapshot)
HASH1=$(echo "$SNAP1" | jq -r '.content_hash')
pilotty key Tab
SNAP2=$(pilotty snapshot)
HASH2=$(echo "$SNAP2" | jq -r '.content_hash')
if [ "$HASH1" != "$HASH2" ]; then
  echo "Screen content changed"
fi
```

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

### Pilotty Session Management Commands

Source: https://github.com/msmps/pilotty/blob/main/README.md

Commands for managing terminal sessions, including spawning, killing, listing, and stopping.

```bash
pilotty spawn <command>           # Spawn a TUI app (e.g., pilotty spawn vim file.txt)
pilotty spawn --name myapp <cmd>  # Spawn with a custom session name
pilotty spawn --cwd /path cmd     # Spawn in a specific working directory
pilotty kill                      # Kill default session
pilotty kill -s myapp             # Kill specific session
pilotty list-sessions             # List all active sessions
pilotty stop                      # Stop the daemon and all sessions
pilotty daemon                    # Manually start daemon (usually auto-starts)
pilotty examples                  # Show end-to-end workflow example
```

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

### Tmux Sequence Commands

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Simulates common tmux commands by combining the prefix key with a command key.

```bash
pilotty key "Ctrl+B c"    # Prefix + new window
```

```bash
pilotty key "Ctrl+B n"    # Prefix + next window
```

```bash
pilotty key "Ctrl+B d"    # Prefix + detach
```

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

### Snapshotting and Filtering Elements

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/element-detection.md

Bash script to capture a pilotty snapshot and filter elements by kind, text, row, col, and checked state using jq.

```bash
# See what's on screen
pilotty snapshot | jq '.elements[] | {kind, text, row, col, checked}'
```

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

### Send Keyboard Sequences

Source: https://github.com/msmps/pilotty/blob/main/README.md

Use the key command to send specific key combinations or sequences with optional delays.

```bash
pilotty key "Ctrl+X m"            # Emacs chord: Ctrl+X then m
pilotty key "Escape : w q Enter"  # vim :wq sequence
pilotty key "a b c" --delay 50    # Send a, b, c with 50ms delay between
```

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

### Case Insensitivity of Named Keys

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/references/key-input.md

Demonstrates that named keys like 'Enter' are case-insensitive in pilotty.

```bash
# Named keys are case-insensitive: Enter, ENTER, enter all work
```

```bash
# Letter keys with Ctrl/Alt are case-insensitive: Ctrl+c = Ctrl+C
```

```bash
# Plain letters: Use pilotty type for text, not pilotty key
```

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

### Manual Change Detection

Source: https://github.com/msmps/pilotty/blob/main/README.md

Demonstrates how to manually poll the `content_hash` for detecting changes without using `--await-change`.

```APIDOC
## Manual Change Detection

### Description
This section illustrates how to manually detect changes in the terminal screen by polling the `content_hash` value.

### Method
`pilotty snapshot` (repeatedly, with manual comparison)

### Request Example
```bash
# Get initial snapshot
SNAP1=$(pilotty snapshot)
HASH1=$(echo "$SNAP1" | jq -r '.content_hash')

# Perform some action
pilotty key Tab

# Get subsequent snapshot and compare hashes (manual process)
SNAP2=$(pilotty snapshot)
HASH2=$(echo "$SNAP2" | jq -r '.content_hash')

if [ "$HASH1" != "$HASH2" ]; then
  echo "Screen has changed!"
else
  echo "Screen has not changed."
fi
```
```

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

### Global Options

Source: https://github.com/msmps/pilotty/blob/main/skills/pilotty/SKILL.md

These options can be used with most Pilotty commands to modify their behavior.

```APIDOC
## Global Options

These options can be used with most Pilotty commands to modify their behavior.

### Options

- **-s, --session <name>** (string) - Target specific session (default: "default")
- **--format <fmt>** (string) - Snapshot format: full, compact, text
- **-t, --timeout <ms>** (number) - Timeout for wait-for and await-change (default: 30000)
- **-r, --regex** (boolean) - Treat wait-for pattern as regex
- **--name <name>** (string) - Session name for spawn command
- **--delay <ms>** (number) - Delay between keys in a sequence (default: 0, max: 10000)
- **--await-change <hash>** (string) - Block snapshot until content_hash differs
- **--settle <ms>** (number) - Wait for screen to be stable for this many ms (default: 0)
```

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

### Snapshot Output Structure

Source: https://github.com/msmps/pilotty/blob/main/README.md

Details the JSON structure returned by the `pilotty snapshot` command.

```APIDOC
## Snapshot Output Structure

### Description
The `snapshot` command returns structured JSON data representing the terminal screen's current state.

### Response Body Example
```json
{
  "snapshot_id": 42,
  "size": { "cols": 80, "rows": 24 },
  "cursor": { "row": 5, "col": 10, "visible": true },
  "text": "Options: [x] Enable  [ ] Debug\nActions: [OK] [Cancel]",
  "elements": [
    { "kind": "toggle", "row": 0, "col": 9, "width": 3, "text": "[x]", "confidence": 1.0, "checked": true },
    { "kind": "toggle", "row": 0, "col": 22, "width": 3, "text": "[ ]", "confidence": 1.0, "checked": false },
    { "kind": "button", "row": 1, "col": 9, "width": 4, "text": "[OK]", "confidence": 0.8 },
    { "kind": "button", "row": 1, "col": 14, "width": 8, "text": "[Cancel]", "confidence": 0.8 }
  ],
  "content_hash": 12345678901234567890
}
```

### Fields
- `snapshot_id` (integer): Unique identifier for the snapshot.
- `size` (object): Terminal dimensions.
  - `cols` (integer): Number of columns.
  - `rows` (integer): Number of rows.
- `cursor` (object): Cursor position and visibility.
  - `row` (integer): Cursor row (0-based).
  - `col` (integer): Cursor column (0-based).
  - `visible` (boolean): Whether the cursor is visible.
- `text` (string): The raw text content of the terminal screen.
- `elements` (array): Detected interactive UI elements.
  - `kind` (string): Type of element (`button`, `input`, `toggle`).
  - `row` (integer): Row position (0-based).
  - `col` (integer): Column position (0-based).
  - `width` (integer): Width in terminal cells.
  - `text` (string): Text content of the element.
  - `confidence` (number): Detection confidence (0.0-1.0).
  - `focused` (boolean, optional): Whether the element has focus.
  - `checked` (boolean, optional): Toggle state (only for toggles).
- `content_hash` (string): A hash of the terminal content, used for change detection.
```