# AXTerminator — AI Agent Installation Guide

> This file is for AI agents installing AXTerminator as an MCP server.
> Fetch this URL: https://raw.githubusercontent.com/MikkoParkkola/axterminator/main/llms.txt

## What This Is

AXTerminator is an MCP server that gives you (the AI agent) the ability to see and control macOS applications via the Accessibility API. 19-34+ tools depending on features.

## Requirements

- macOS 12+ (Apple Silicon or Intel)
- Rust toolchain (for building from source — RECOMMENDED)
- Accessibility permission granted to the host app

## Check for Existing Installation

Before installing, check if axterminator is already installed:

```bash
# Check if binary exists
which axterminator 2>/dev/null || echo "NOT INSTALLED"

# If installed, check version
axterminator check 2>/dev/null
# Look at the "Version:" line — current release is 0.8.0
```

If already installed at an older version, follow the Upgrade section below.
If not installed, follow Installation.

## Upgrade

```bash
# Option 1: Homebrew (simplest)
brew upgrade axterminator

# Option 2: cargo
cargo install axterminator --features cli --force

# Option 3: Build from source (if cloned previously)
cd /path/to/axterminator-src
git pull origin main
cargo build --release --features cli
cp target/release/axterminator ~/.local/bin/axterminator

# Option 4: Download prebuilt binary (replace existing)
ARCH=$(uname -m)
case "$ARCH" in
  arm64) TARGET="aarch64-apple-darwin" ;;
  x86_64) TARGET="x86_64-apple-darwin" ;;
esac
curl -L --fail -o ~/.local/bin/axterminator \
  "https://github.com/MikkoParkkola/axterminator/releases/latest/download/axterminator-${TARGET}"
chmod +x ~/.local/bin/axterminator
```

After upgrading, verify:
```bash
axterminator check
# Should show the new version
```

**IMPORTANT for upgrades from v0.6.x:**
- Python is no longer required. The binary is fully self-contained.
- If you have `pip install axterminator`, uninstall it: `pip uninstall axterminator`
- MCP config does not need to change — same binary, same `mcp serve` command.
- The PyPI package is deprecated and yanked.

## Installation (Preferred → Fallback)

### Option A: Build from source (RECOMMENDED)

```bash
# 1. Clone
git clone https://github.com/MikkoParkkola/axterminator /tmp/axterminator-src
cd /tmp/axterminator-src

# 2. Build
cargo build --release --features cli

# 3. Install binary
cp target/release/axterminator ~/.local/bin/axterminator
chmod +x ~/.local/bin/axterminator

# 4. Verify
~/.local/bin/axterminator check
# Expected output: "Accessibility: OK" and a version string
# If output says "Accessibility: DISABLED", the host app needs permission — see PERMISSIONS below

# 5. Verify MCP handshake
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | ~/.local/bin/axterminator mcp serve 2>/dev/null | head -1
# Expected: JSON response containing "serverInfo" and "capabilities"
```

### Option B: Homebrew

```bash
brew tap MikkoParkkola/tap
brew install axterminator

# Verify
axterminator check
```

### Option C: Download prebuilt binary

```bash
# Detect architecture
ARCH=$(uname -m)
case "$ARCH" in
  arm64) TARGET="aarch64-apple-darwin" ;;
  x86_64) TARGET="x86_64-apple-darwin" ;;
  *) echo "Unsupported: $ARCH"; exit 1 ;;
esac

# Download latest release
curl -L --fail -o ~/.local/bin/axterminator \
  "https://github.com/MikkoParkkola/axterminator/releases/latest/download/axterminator-${TARGET}"
chmod +x ~/.local/bin/axterminator

# Verify
~/.local/bin/axterminator check
```

The prebuilt binary is fully self-contained -- no runtime dependencies required.

## PERMISSIONS

The host application (Terminal, iTerm2, Ghostty, Claude Desktop, etc.) must have Accessibility permission:

1. Open: System Settings → Privacy & Security → Accessibility
2. Click the + button
3. Add the terminal application or AI host app
4. Ensure the toggle is ON
5. Restart the terminal / host app

Verification:
```bash
axterminator check
# Must print: "Accessibility: OK"
```

## MCP Configuration

### Claude Code / Claude Desktop

File: `~/.claude/settings.json` (or project `.mcp.json`)

```json
{
  "mcpServers": {
    "axterminator": {
      "command": "BINARY_PATH",
      "args": ["mcp", "serve"]
    }
  }
}
```

Replace `BINARY_PATH` with the actual path (e.g., `~/.local/bin/axterminator` or the full path from `which axterminator`).

### Codex

File: `~/.codex/config.toml`

```toml
[mcp_servers.axterminator]
command = "BINARY_PATH"
args = ["mcp", "serve"]
```

### Cursor / Windsurf / Continue.dev

File: `.cursor/mcp.json` (or equivalent)

```json
{
  "mcpServers": {
    "axterminator": {
      "command": "BINARY_PATH",
      "args": ["mcp", "serve"]
    }
  }
}
```

### Generic MCP client (stdio transport)

```bash
BINARY_PATH mcp serve
# Reads JSON-RPC from stdin, writes to stdout, logs to stderr
```

### HTTP transport (optional)

```bash
BINARY_PATH mcp serve --http 8741 --localhost-only
# Or with auth:
BINARY_PATH mcp serve --http 8741 --token YOUR_SECRET_TOKEN
```

## Available Tools (34+)

After connecting, call `tools/list` to get the full schema. Core tools:

- `ax_is_accessible` — check permissions
- `ax_connect` — connect to an app by name, bundle ID, or PID
- `ax_find` — find UI element by text, role, or XPath query
- `ax_click` — click an element (background or focus mode)
- `ax_click_at` — click at screen coordinates
- `ax_type` — type text into an element
- `ax_set_value` / `ax_get_value` — get/set element values
- `ax_screenshot` — capture app or element screenshot (base64 PNG)
- `ax_get_tree` — dump accessibility tree
- `ax_get_attributes` — get all attributes of an element
- `ax_list_windows` — list app windows with bounds
- `ax_list_apps` — list running applications
- `ax_wait_idle` — wait for app to become idle
- `ax_scroll` — scroll an element
- `ax_drag` — drag between coordinates
- `ax_key_press` — send keyboard shortcuts
- `ax_assert` — assert element state
- `ax_find_visual` — visual element detection (requires VLM)
- `ax_visual_diff` — visual regression testing (compare screenshots against baseline)
- `ax_a11y_audit` — WCAG accessibility compliance audit
- `ax_clipboard` — read/write system clipboard
- `ax_run_script` — execute AppleScript/JXA scripts
- `ax_undo` — undo last N actions (Cmd+Z)
- `ax_session_info` — server session state
- `ax_analyze` — detect UI patterns, infer app state, suggest actions
- `ax_query` — natural language UI questions
- `ax_record` — interaction recording for test generation
- `ax_workflow_create` / `ax_workflow_step` / `ax_workflow_status` — durable multi-step workflows
- `ax_track_workflow` — cross-app pattern detection
- `ax_test_run` — black-box test execution
- `ax_app_profile` — Electron app metadata

Optional feature tools: `ax_listen`, `ax_speak`, `ax_audio_devices` (audio), `ax_camera_capture`, `ax_gesture_detect` (camera), `ax_list_spaces`, `ax_create_space` (spaces).

## Query Syntax

```
# Simple text — matches ANY of: title, description, value, label, identifier
ax_find query="Save"

# Role filter
ax_find query="role:AXButton"

# Combined (AND)
ax_find query="role:AXButton title:Save"

# XPath-like
ax_find query="//AXButton[@AXTitle='Save']"

# By description (useful for Calculator-style apps)
ax_find query="description:equals"
```

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Accessibility: DISABLED` | No permission | See PERMISSIONS section |
| `Element not found` for short labels like "1" | App uses AXDescription not AXTitle | Use `description:1` or check tree with `ax_get_tree` |
| `Application not found` | App not running or wrong name | Use bundle ID: `ax_connect app="com.apple.calculator"` |
| Old version (missing tools) | Outdated binary | See Upgrade section above |
| `pip install axterminator` fails | PyPI package yanked | Use Rust binary (Options A-C). Python package is deprecated. |

## Feature Flags (build-time)

```bash
# Core only (default — 27 tools)
cargo build --release --features cli

# With audio capture + TTS (30 tools)
cargo build --release --features cli,audio

# With camera + gesture detection (30 tools)
cargo build --release --features cli,camera

# With virtual desktop isolation (32 tools)
cargo build --release --features cli,spaces

# Everything (34+ tools)
cargo build --release --features cli,audio,camera,watch,spaces,http-transport
```

## Version

0.8.0