docs.rs failed to build axterminator-0.8.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

AXTerminator

MCP server that gives AI agents the ability to see and control macOS applications.

Deploy · MCP Tools · CLI · Query Syntax · Troubleshooting · Wiki · Known Limitations

Up to 30 MCP tools (19 core + optional audio, camera, spaces). Background interaction via the macOS Accessibility API. 379us per element access. Audio capture, camera input, virtual desktop isolation. Your AI agent connects and your Mac becomes an extension of it.

Deploy

git clone https://github.com/MikkoParkkola/axterminator
cd axterminator
cargo build --release --features cli

Grant accessibility permissions: System Settings > Privacy & Security > Accessibility (add your terminal app).

Connect your AI agent

Add to MCP config (Claude Code, OpenCode, Cursor):

{
  "mcpServers": {
    "axterminator": {
      "command": "/path/to/axterminator",
      "args": ["mcp", "serve"]
    }
  }
}

For Codex (~/.codex/config.toml):

[mcp_servers.axterminator]
command = "/path/to/axterminator"
args = ["mcp", "serve"]

Replace /path/to/axterminator with the actual binary path (run which axterminator or use the full build output path).

Done. Your agent has 19 core tools (up to 30 with all feature flags) to control any macOS app.

MCP Tools

Category	Tools	What the agent can do
GUI	`ax_connect`, `ax_find`, `ax_click`, `ax_click_at`, `ax_type`, `ax_set_value`, `ax_get_value`, `ax_scroll`, `ax_drag`, `ax_key_press`	Connect to apps, find elements, interact
Observe	`ax_is_accessible`, `ax_screenshot`, `ax_get_tree`, `ax_get_attributes`, `ax_list_windows`, `ax_list_apps`, `ax_wait_idle`	Check permissions, see UI state, screenshots
Verify	`ax_assert`, `ax_find_visual`	Assert element state, AI vision fallback
Audio	`ax_listen`, `ax_speak`, `ax_audio_devices`	Capture mic/system audio, text-to-speech
Camera	`ax_camera_capture`, `ax_gesture_detect`, `ax_gesture_listen`	Camera frames, gesture recognition
Spaces	`ax_list_spaces`, `ax_create_space`, `ax_move_to_space`, `ax_switch_space`, `ax_destroy_space`	Virtual desktop isolation

Resources

Agents can browse app state without tool calls:

Resource	What
`axterminator://apps`	Running applications
`axterminator://app/{name}/tree`	Live element hierarchy
`axterminator://app/{name}/screenshot`	Current screenshot
`axterminator://app/{name}/state`	Focused element, window title
`axterminator://system/displays`	Monitor layout

Security

Destructive actions require confirmation via elicitation. HTTP transport requires bearer token auth. The AI has hands, not root.

CLI

axterminator apps                        # List accessible apps
axterminator find "Save" --app Safari    # Find element
axterminator click "Save" --app Safari   # Click it
axterminator screenshot --app Safari     # Capture screenshot
axterminator tree --app Finder           # Element hierarchy
axterminator mcp serve --http 8080 --token secret  # HTTP transport

Query Syntax

# Simple text — matches ANY of: title, description, value, label, identifier
axterminator find "Save" --app Safari

# By role
axterminator find "role:AXButton" --app Safari

# Combined role + attribute (AND)
axterminator find "role:AXButton title:Save" --app Safari

# By description (useful for apps like Calculator)
axterminator find "description:equals" --app Calculator

# By value
axterminator find "value:42" --app Calculator

# XPath-like
axterminator find "//AXButton[@AXTitle='Save']" --app Safari

How It Works

AXTerminator uses an undocumented behavior of Apple's Accessibility API: AXUIElementPerformAction() works on unfocused windows. Your agent clicks buttons in one app while you work in another. Neither notices.

379us per element access (Criterion, M1 MacBook Pro). Appium needs 500ms for the same thing.

7-strategy self-healing locators survive UI changes: data_testid, aria_label, identifier, title, xpath, position, visual_vlm.

Known Limitations

Operation	Background?	Notes
Click, press, read values, screenshots	Yes	Core operations work without focus
Text input	Partial	Some apps need focused text field
Drag, system dialogs	No	Require cursor control / always grab focus
Gesture recognition	Yes	Verified: thumbs_up at 88.8% confidence
Speech transcription	Yes	Verified: on-device, requires Dictation enabled

Troubleshooting

Symptom	Cause	Fix
`Accessibility: DISABLED`	No permission granted	System Settings > Privacy & Security > Accessibility
`Element not found` for short labels	App uses `AXDescription` not `AXTitle`	Try `description:label` or inspect with `axterminator tree`
`Application not found`	Wrong name or app not running	Use bundle ID: `--bundle-id com.apple.calculator`

AI agents: Fetch llms.txt for machine-readable installation instructions.

Feature Flags

Build with optional capabilities:

cargo build --release --features "cli,audio,camera,spaces"

Flag	What
`cli`	CLI + MCP server (default)
`audio`	Microphone/system audio, speech
`camera`	Camera capture, gesture detection
`spaces`	Virtual desktop management
`http-transport`	HTTP MCP transport with auth

Community

Wiki -- Full documentation
Discussions -- Questions, ideas, show-and-tell
Issues -- Bugs

Acknowledgements

Inspired by Terminator by mediar-ai, which pioneered accessible desktop GUI automation on Windows.

For AI Agents

Machine-readable installation guide: llms.txt

Your agent can fetch this URL to get step-by-step installation, MCP config for every host, and troubleshooting.

License

MIT OR Apache-2.0

axterminator 0.8.0