AXedocs
Install

Contributing

Build AXe from source, find your way around the Swift package, and keep commands, help, docs and the skill in step.

Prerequisites#

RequirementNotes
macOS 14+AXe is macOS-only.
Xcode 26 or 27For CoreSimulator, CoreDevice and the simulator frameworks.
XcodeGenGenerates the project for the bundled IDBKit frameworks.
A booted simulatorFor end-to-end tests and manual checks.

Build#

shell
git clone https://github.com/cameroncooke/AXe.git
cd AXe
make build
TargetWhat it does
make buildRebuilds the IDBKit frameworks only when stale, then swift build.
make testUnit tests.
make release-checkThe quick release checks in one run.
make e2eThe whole Playground suite on dedicated iPhone, iPad and iPhone Duo simulators.
make e2e-devicesThe opt-in suite on connected iPhones and iPads.
make bench-quickA quick A/B timing of direct commands against a baseline payload.
make cleanRemove build output.

AXE_BUILD_ARCHS defaults to "arm64 x86_64"; set arm64 for faster local builds.

AXe keeps its own copy of the IDB frameworks it uses, FBControlCore and FBSimulatorControl, in Packages/IDBKit; edit them directly. Building does not clone IDB.

build_products is rebuilt

scripts/build.sh removes build_products and build_derived_data whenever it rebuilds stale frameworks. Do not keep anything there that must survive.

Project layout#

PathPurpose
Sources/AXe/main.swiftEntry point and command registration.
Sources/AXe/Commands/One file per command; the source of truth for options and help.
Sources/AXe/Agent/Agent mode: captures, refs, admission checks and the agent batch.
Sources/AXe/Device/Physical device support: CoreDevice readiness, services and the device broker.
Sources/AXe/Utilities/HID input, accessibility reads, orientation and batch parsing.
Sources/AXe/Resources/The bundled skill that axe init installs, and licences.
Sources/AXeCore/Shared core, including the runtime snapshot model.
Packages/IDBKit/The bundled IDB frameworks.
Skills/CLI/axe/The AXe skill and its references, served by the plugin marketplace.
schemas/JSON Schemas for command and agent results.
AxePlaygroundApp/The Playground app the end-to-end suites drive.
benchmarks/Task benchmarks against accepted baselines and other tools.
Tests/Unit and end-to-end tests.

Changing a command#

  1. Edit or add the command under Sources/AXe/Commands, and register a new one in main.swift.
  2. Keep --help accurate: a short description, examples and one line per option.
  3. Validate inputs before sending anything, and fail with a typed error code.
  4. Add tests.
  5. Update README.md and the skill in Skills/CLI/axe/ in the same change.
  6. Add a CHANGELOG.md entry under ## [Unreleased].

Performance#

An ordinary simulator interaction must be as fast as in the latest release, on every input route, including selected and agent modes. An iPhone Duo interaction must be as fast as the same interaction on an ordinary simulator. Compare against the release binary on the same machine and simulator.

Before a pull request#

shell
make build
make test
make release-check

Run the end-to-end suites that your change affects; see Testing.