Install and first launch
Drag XAgents to Applications, open it once past macOS’s first-launch check, and let Set up XAgents confirm everything is ready.
XAgents runs on macOS 14 Sonoma or later. Builds are made for Macs with Apple silicon. You need a Claude account; Codex is optional.
Install
- Open the XAgents-<version>.dmg disk image you downloaded.
- Drag XAgents onto the Applications folder in the window.
- Eject the disk image.
If you open XAgents straight from the disk image, it offers to copy itself to Applications and relaunch. It never overwrites an existing copy.
Open it the first time
This version isn’t signed with an Apple Developer ID yet, so macOS asks you to confirm the first open. You only do this once. Signed releases are coming.
macOS 15 Sequoia and later
- Open XAgents from Applications. macOS says it can’t verify the app. Click Done (or OK).
- Open System Settings › Privacy & Security and scroll to Security.
- Next to “XAgents was blocked…”, click Open Anyway, then confirm with your password or Touch ID.
- Click Open in the dialog that follows.
macOS 14 Sonoma
- In Applications, Control-click (or right-click) XAgents and choose Open.
- Click Open in the dialog. If it doesn’t offer Open, use System Settings › Privacy & Security › Open Anyway as above.
After this, XAgents opens normally from the Dock, Spotlight or Launchpad.
First-launch setup
On first launch you’ll see Set up XAgents. Each row is a check, and each one comes with a fix if something’s missing.
| Check | What it looks for | If something’s missing |
|---|---|---|
| Move to Applications | XAgents isn’t running from the disk image | Copies itself to Applications and relaunches |
| Python | Python 3.11 or later | Opens Terminal with the Homebrew install command, or the python.org download page |
| Claude Code (required) | The claude CLI, its version and whether you’re signed in | Opens Terminal with Anthropic’s official installer, or claude auth login |
| Codex (optional) | The codex CLI and whether you’re signed in | Opens Terminal with the install or codex login command |
| Previous setup | Leftovers from an earlier XAgents version | Back up and update saves a backup first, so Restore previous setup can undo it |
| Background services | The XAgents helpers that coordinate your agents | Set up installs and starts them |
Click Continue when the checks are green. A short tour of the real controls follows, and you can skip it with Esc. You can run the checks again any time from Help › Check Installation….
Optional features
These are all off until you turn them on:
- Your apps first: Settings › Performance
- Warm sessions: Settings › Performance
- Xval Engine: Settings › Xval Engine
- Chief of Staff: Settings › Agent coordination