Ansible Piloteer

Ansible Piloteer is an interactive, AI-powered debugger and execution wrapper for Ansible playbooks. It transforms Ansible's "black box" execution into a transparent, controllable process with a TUI (Text User Interface) for step-through debugging, live state inspection, and runtime failure recovery.

🚀 Features

• Interactive TUI:
  • Dashboard: View live task status, progress bars, and execution statistics.
  • Analysis Mode:
    • Deep inspection of JSON facts and task results.
    • Search: Interactive search with highlighting (try /).
    • Deep Navigation: Recursive expand/collapse (Shift+h/Shift+l/Left/Right/Enter/Space).
    • Detail View: Inspect long values in a popup (w).
  • Host Targeting: List hosts, filter history, and inspect facts per host (H to list, f for facts).
• Data Query & Transformation:
  • Interactive REPL: Query session data with JMESPath expressions.
  • Aggregation Functions: count(), sum(), avg(), min(), max() for data analysis.
  • Custom Functions: group_by(), unique() for advanced data manipulation.
  • Query Templates: Pre-built queries for common use cases (failed tasks, changed hosts, etc.).
  • Multiple Formats: Output as JSON, YAML, or pretty-printed JSON.
• AI-Powered Debugging:
  • Ask Pilot: Analyze failures using LLMs (OpenAI, Local LLMs) to get plain-English explanations.
  • Auto-Fix: Automatically apply AI-suggested variable fixes with a single keystroke.
  • Retry: Re-run failed tasks with modified variables.
  • Modify Variables: Inject new variables or override existing ones at runtime (extra_vars precedence).
  • Continue: Skip failures and proceed with execution.
• Session Persistence:
  • Save/Load: Snapshot your session (Ctrl+s) and replay it later (--replay).
  • Reporting: Export detailed Markdown reports of your debugging session (Ctrl+e).
• Distributed Tracing:
  • OpenZipkin Integration: Deep observability into playbook execution with distributed tracing.
  • Performance Monitoring: Track execution times, identify bottlenecks, and visualize execution flow.
  • Configurable Sampling: Control trace volume with probabilistic sampling.
• Deep Execution Analysis:
  • Play Recap: View aggregated execution statistics.
  • Clipboard: Copy data with y|<???>y for multi-line copy i.e. 8y copy 8 lines to the clipboard.
• AI Chat:
  • Interactive Chat: C <shift>+c to toggle chat sidebar.
  • Model Selection: /model to switch between models (e.g., standard vs pro).
  • Navigation: PageUp / PageDown / <Mouse scroll> to scroll history.
  • Search: / to search chat history.
  • Folding: Collapse long messages with Space| Enter.
• Antigravity IDE Integration:
  • Shared Auth: Auto-detects Google ADC (Application Default Credentials) for seamless authentication within the IDE.
  • Token Sync: Automatically reports Piloteer's AI token usage to the Antigravity dashboard.
  • MCP Server: Built-in support for the Model Context Protocol (MCP) allowing AI assistants to invoke Piloteer tools.
• Architecture: Built with a high-performance Rust CLI and a custom Ansible Strategy Plugin (Python).

🛠️ Architecture

The system consists of two main components communicating via Unix Domain Sockets or TCP:

1. Piloteer CLI (Rust): The user-facing TUI and process controller. It manages the Ansible process and renders the UI.
2. Ansible Strategy Plugin (Python): A custom execution strategy that hooks into Ansible internals to capture state, pause execution, and apply runtime modifications.

📦 Installation & Setup

Prerequisites

• Rust: Stable toolchain (cargo).
• Python: 3.8+ with Ansible installed.

Build

Clone the repository and build the Rust CLI:

cargo build --release

Environment Setup

The Piloteer requires a specific environment to load its custom Ansible plugin.

1. Activate your Python environment (if using venv):

   source venv/bin/activate

2. Set Ansible Strategy Path: Point Ansible to the ansible_plugin directory in this repo.

   export ANSIBLE_STRATEGY_PLUGINS=$(pwd)/ansible_plugin/strategies

3. Configure Strategy: Tell Ansible to use the piloteer strategy.

   export ANSIBLE_STRATEGY=piloteer

⚙️ Configuration

Piloteer can be configured via config.toml, environment variables, or CLI arguments.

Authentication (Optional)

To use the hosted AI features with Google Login:

# Default (Google / Gemini Free Tier compatible)
# Note: For Gemini API, using an API Key is recommended over OAuth default flow.
# export PILOTEER_GOOGLE_API_KEY="..."
ansible-piloteer auth login

# Custom Credentials (Recommended for production/billing)
export PILOTEER_GOOGLE_CLIENT_ID="your-client-id"
export PILOTEER_GOOGLE_CLIENT_SECRET="your-client-secret"
ansible-piloteer auth login

# IDE / ADC Authentication (Antigravity compatible)
# This reads Application Default Credentials directly from ~/.config/gcloud
ansible-piloteer auth adc

List stored credentials:

ansible-piloteer auth list

Environment Variables

Variable	Description	Default
Core
ANSIBLE_STRATEGY	Must be set to 'piloteer'	None
ANSIBLE_STRATEGY_PLUGINS	Path to ansible_plugin/strategies	None
PILOTEER_HEADLESS	Run without TUI (for CI/CD)	false
PILOTEER_SOCKET	Path to IPC socket or host:port	/tmp/piloteer.sock
AI Features
OPENAI_API_KEY	API Key for OpenAI (or compatible providers)	None
PILOTEER_MODEL	LLM Model to use	gpt-4-turbo-preview
PILOTEER_BASE_URL	Base URL for LLM API (for Local LLMs)	https://api.openai.com/v1
PILOTEER_QUOTA_TOKENS	Token usage limit	None
PILOTEER_QUOTA_USD	Cost limit in USD	None
Distributed Mode
PILOTEER_SECRET	Shared secret for TCP authentication	None
Tracing
PILOTEER_ZIPKIN_ENDPOINT	Zipkin server URL (e.g., http://localhost:9411)	None
PILOTEER_ZIPKIN_SERVICE_NAME	Service name in traces	ansible-piloteer
PILOTEER_ZIPKIN_SAMPLE_RATE	Sampling rate (0.0-1.0)	1.0
OAuth
PILOTEER_GOOGLE_CLIENT_ID	Google OAuth client ID	None
PILOTEER_GOOGLE_CLIENT_SECRET	Google OAuth client secret	None
Antigravity
ANTIGRAVITY_SESSION	Indicates execution within Antigravity IDE	None
ANTIGRAVITY_WORKSPACE	Path to current IDE workspace	None

🏃 Usage

Local Execution

To run a playbook with Piloteer:

# Start the Piloteer CLI, which wraps the ansible-playbook command
./target/release/ansible-piloteer playbook.yml -i inventory.ini -e "env=prod"

# Run in CI/Headless mode with Auto-Analyze
PILOTEER_HEADLESS=1 ./target/release/ansible-piloteer playbook.yml --auto-analyze

# Start MCP Stdio Server (for IDE integration)
./target/release/ansible-piloteer mcp

🧪 Testing

The project includes comprehensive unit and integration tests:

# Run all tests
cargo test

# Run specific test suite
cargo test unreachable
cargo test report_generation

# Run with output
cargo test -- --nocapture

Test Coverage:

• Unit tests: Configuration, AI parsing, execution details
• Integration tests: IPC communication, session persistence, unreachable hosts, report generation
• Total: 21 tests covering critical workflows

Distributed Execution

To run Piloteer as a remote debugger (e.g. for a container or remote host):

# On the Controller (TUI)
./target/release/ansible-piloteer run --bind 0.0.0.0:9000 --secret mytoken

# On the Executor (Ansible)
export ANSIBLE_STRATEGY=piloteer
export PILOTEER_SOCKET=192.168.1.50:9000
export PILOTEER_SECRET=mytoken
ansible-playbook playbook.yml

See docs/distributed_mode.md for details.

Reporting

Generate an execution report after the run:

./target/release/ansible-piloteer playbook.yml --report report.md
# or
./target/release/ansible-piloteer playbook.yml --report report.json

(Note: Currently, during development, you may need to run the components manually or use a helper script like run_poc.sh)

Interactive Controls

When a task fails, the Piloteer enters Debug Mode:

• r: Retry the failed task.
• e: Edit/Inject Variable (Currently simulates injecting should_fail=false).
• a: Ask Pilot (Send failure context to AI for analysis).
• f: Apply Fix (Apply the variable fix suggested by AI).
• c: Continue (Accept failure and move to next task).
• q: Quit the application.

TUI Controls

• General Navigation:

  • Tab / Shift+Tab: Cycle between Dashboard, Analysis, and Metrics views.
  • PageUp / PageDown: Scroll the active view (Logs, Inspector, or Analysis).
  • q / Esc: Quit.
  • ?: Toggle Help.

• Log View:

  • /: Search logs (or use ::query:: prefix for JMESPath query on session data).
  • n / N: Next / Previous match.
  • l: Toggle log filter (All/Failed/Changed).
  • F: Toggle Follow mode (Auto-scroll).

• Analysis Mode (active when selected via Tab or v):

  • v: Toggle Analysis Mode (Enter/Exit).
  • V (Shift+v): Toggle Visual Mode (for selection).
  • j / k: Navigate Task List or Data Tree.
  • Enter: Toggle expand/collapse.
  • /: Search within the tree.
  • n / N: Next/Prev match.
  • h / l: Collapse/Parent / Expand/Child.
  • y: Copy to Clipboard.

• Session:

  • Ctrl+s: Manually Save Session.

📚 Documentation

User Guides

• Getting Started - Installation and first steps
• Keyboard Shortcuts - Complete shortcut reference
• Troubleshooting - Common issues and solutions

Features

• Interactive Debugging - Debug failed tasks interactively
• Session Persistence - Save, load, and replay sessions
• Reporting - Generate execution reports
• Deep Analysis - Data browser and analysis mode
• Error Handling - Unreachable hosts and error recovery
• Query Guide - JMESPath queries and REPL mode
• Zipkin Tracing - Distributed tracing with OpenZipkin

Advanced Topics

• Distributed Mode - Remote debugging setup
• CI/CD Integration - Headless mode and automation
• Interface Reference - TUI layout and components See docs/interactive_debugging.md for a detailed guide on debugging workflows, docs/deep_analysis.md for details on using the Data Browser, and docs/session_persistence.md for session management.

🧪 Verification

You can verify the interactive debugging capabilities using the included test script:

./verify_debug.sh

This script runs a test playbook (fail_on_var.yml) that conditionally fails, modifies the variable, and successfully retries.

🔮 Roadmap

• Advanced TUI: Full variable editor and breakpoint management.
• History: Request/Response logs for AI interactions.