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, set the electron-builder signing variables CSC_LINK and CSC_KEY_PASSWORD, plus APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID. 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:
Build the Mac release with the signing and notarization credentials above. The local build uses --publish never: creating packages must not upload or publish anything automatically. Before uploading, verify that the release output contains the signed and notarized DMG, the Mac ZIP, their blockmaps, and latest-mac.yml. Confirm that latest-mac.yml references both primary artifacts with the prepared version, and that the packaged app contains an app-update.yml feed pointing to the public agentuse/agentuse GitHub Releases repository. After the normal GitHub release exists, manually upload all of those Mac assets to that same public release. Test the completed feed from an older signed build: 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.