Contributing
Build AXe from source, find your way around the Swift package, and keep commands, help, docs and the skill in step.
Prerequisites
| Requirement | Notes |
|---|---|
| macOS 14+ | AXe is macOS-only. |
| Xcode 26 or 27 | For CoreSimulator, CoreDevice and the simulator frameworks. |
| XcodeGen | Generates the project for the bundled IDBKit frameworks. |
| A booted simulator | For end-to-end tests and manual checks. |
Build
git clone https://github.com/cameroncooke/AXe.git
cd AXe
make build| Target | What it does |
|---|---|
make build | Rebuilds the IDBKit frameworks only when stale, then swift build. |
make test | Unit tests. |
make release-check | The quick release checks in one run. |
make e2e | The whole Playground suite on dedicated iPhone, iPad and iPhone Duo simulators. |
make e2e-devices | The opt-in suite on connected iPhones and iPads. |
make bench-quick | A quick A/B timing of direct commands against a baseline payload. |
make clean | Remove 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.
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
| Path | Purpose |
|---|---|
Sources/AXe/main.swift | Entry 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
- Edit or add the command under
Sources/AXe/Commands, and register a new one inmain.swift. - Keep
--helpaccurate: a short description, examples and one line per option. - Validate inputs before sending anything, and fail with a typed error code.
- Add tests.
- Update
README.mdand the skill inSkills/CLI/axe/in the same change. - Add a
CHANGELOG.mdentry 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
make build
make test
make release-checkRun the end-to-end suites that your change affects; see Testing.