AX Tools Monorepo

A structured monorepo for macOS accessibility extraction, querying, hit-testing, visualization, action execution, synchronization, selector capture, workflow execution, documentation, and AI-agent operation.

It contains these main deliverables:

• axdump: a Swift CLI that dumps a macOS accessibility tree using AXUIElement
• axviz: a Bun + TypeScript CLI that understands axdump JSON, normalizes it, lints it, diffs it, and renders it into positioned HTML
• axquery: a Bun + TypeScript CLI that runs CSS-like selectors against axdump JSON or a live target via axdump
• axhit: a Swift CLI that resolves the accessibility elements intersecting a given pixel coordinate and returns stable selectors, z-order metadata, and the actual visible topmost hit
• axact: a Swift CLI that performs actions on matched accessibility elements, such as clicking, focusing, or setting values
• axwatch: a Swift CLI that waits for or streams AX notifications so automation can synchronize on real UI changes
• axrec: a Swift CLI that records clicks or focus transitions and turns them into reusable selectors and suggested flow steps
• axflow: a Swift CLI that executes declarative JSON workflows using the same target and locator schema emitted by the rest of the suite
• axtools-operator: an AI-agent skill bundle for using the tools together as one workflow

The repo also includes:

• a GitHub Pages documentation website
• GitHub Actions CI
• Changesets-based release automation

Repository layout

axtools-monorepo/
├─ docs/
├─ packages/
│  ├─ axdump/
│  ├─ axviz/
│  ├─ axquery/
│  ├─ axhit/
│  ├─ axact/
│  ├─ axwatch/
│  ├─ axrec/
│  ├─ axflow/
│  └─ site/
├─ skills/
│  └─ axtools-operator/
└─ .github/workflows/

Build everything

make build-all

On macOS this builds every CLI plus the documentation site. On non-macOS platforms it builds the cross-platform parts and explicitly skips the Swift AX tools.

Test everything

make test-all

Install the CLI tools

make install-all

This installs:

• axviz and axquery to ~/.local/bin/
• axdump, axhit, axact, axwatch, axrec, and axflow to ~/.local/bin/ on macOS

Quick start

make build-all
axdump --frontmost --format json > /tmp/before.json
axviz render /tmp/before.json --out /tmp/before.html
axquery 'AXTextField:focus' --input /tmp/before.json
axhit 640 380 --frontmost --topmost-visible
axact click --frontmost --selector 'AXApplication[AXTitle="Google Chrome"] > AXWindow:nth-of-type(1) > AXButton:nth-of-type(3)'
axwatch wait --frontmost --notifications AXLayoutChanged,AXFocusedUIElementChanged
axdump --frontmost --format json > /tmp/after.json
axviz diff /tmp/before.json /tmp/after.json

GitHub Actions

The repository includes three workflows:

• ci.yml: validates axviz, axquery, the static site, and all Swift AX tools on the correct platforms
• release.yml: uses Changesets to create or update a release PR on pushes to main
• pages.yml: builds and deploys the documentation site to GitHub Pages

Documentation

See docs/ for both user and developer documentation.

Design goals

• keep the Swift tools small and dependency-free
• produce stable, explicit JSON for downstream tooling
• keep extraction, querying, hit-testing, mutation, synchronization, selector capture, and workflow execution as separate responsibilities
• preserve one shared target and selector vocabulary across all actor/watcher/recorder/flow tools
• keep docs source-of-truth in Markdown and emit a static site from it
• make CI and release behavior obvious from the repo root