Skip to main content
This page is for contributors working on the AgentUse Desktop app. For normal installation and usage, see macOS Desktop App.

​
Requirements

Desktop development requires:
  • Node.js 22 or later
  • Bun and pnpm
  • Xcode, including its command-line tools
Xcode is required because the build compiles the native SwiftUI Settings helper and uses Apple’s asset-catalog compiler for the app icon.

​
Run from source

From the repository root, install workspace dependencies, build the CLI and Web UI, then start Electron:
The Desktop process attaches to a registered agentuse serve daemon when one is already running. Otherwise it starts the compiled local CLI on a loopback port. The browser dashboard remains available at the URL shown in the menu. Set AGENTUSE_CLI_PATH to test against a specific CLI build:

​
Install a local build

For routine testing, install and launch one canonical app copy:
The installer builds in temporary staging, gracefully terminates running AgentUse Desktop copies, replaces ~/Applications/AgentUse.app, and launches that copy. Avoid opening apps/desktop/dist/*/AgentUse.app directly; using one canonical installation prevents Launch Services from retaining several copies with the same bundle identifier.

​
Package the app

Create a package for the current Mac architecture:
For an unsigned development package:
The Settings helper builds for the current architecture by default. For a universal arm64 and x86_64 package, include both architectures in the nested SwiftUI helper:
The package includes the AgentUse runtime, dashboard, built-in skills, and required metadata. Source, tests, prior Desktop builds, and workspace caches are excluded.

​
Sign and notarize a release

For a manual release, store notarization credentials in the login Keychain so the app-specific password does not enter shell history:
notarytool prompts securely for the app-specific password. electron-builder uses the Developer ID Application identity installed in the login Keychain. For CI, configure repository Actions secrets named MAC_CSC_LINK and MAC_CSC_KEY_PASSWORD, plus APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID. The certificate value is the base64-encoded Developer ID Application .p12. Keep all signing credentials in CI secrets. Hardened runtime is enabled, and the packaged native Settings helper is placed under Contents/Frameworks before notarization.

​
Prepare an updater-enabled release

The root package and Desktop app share one release version. Use the repository release script to prepare that version; do not edit the Desktop version separately:
Push the prepared tag to the public repository. After the portable release gate passes, GitHub Actions builds on native Apple Silicon and Intel runners. Each package is signed, notarized, stapled, and verified before it is preserved as a workflow artifact. The publishing job merges their update metadata and uploads two DMGs, two Mac ZIPs, four blockmaps, and one latest-mac.yml to the release. Every artifact filename includes arm64 or x64, and the merged metadata lists both architectures so electron-updater selects the matching ZIP. Confirm the completed GitHub Release contains that nine-file set. Test the feed from an older signed build on each architecture: confirm that the update downloads in the background, choose Later in the native prompt, install it from Settings → About, and confirm the new version launches. Repeat with Restart Now, then repeat a check while offline and confirm the app continues working while the About tab reports the failure.