Skip to main content
AgentUse for Mac keeps scheduled agents, approvals, and active runs available from the menu bar without leaving a Terminal window open. It can start quietly at login, opens the operations dashboard in its own window, and includes the complete AgentUse runtime, so Node.js and a separate CLI installation are not required. The app and CLI use the same projects and session history, letting you move between Desktop and Terminal without duplicate setup or configuration.

​
Install

Download the signed DMG from the latest GitHub release, open it, and move AgentUse to Applications. Open AgentUse from Applications to start setup.

​
First launch

The Desktop setup screen has two independent options:
  • Launch AgentUse at login starts the app quietly in the menu bar so schedules, approvals, and background runs remain available. It is selected by default but is not added to macOS Login Items until you select Continue.
  • Add CLI launcher creates ~/.local/bin/agentuse, pointing to the CLI bundled inside AgentUse.app. It is optional and never blocks Continue.
After Continue, Desktop joins the same onboarding flow as the Web UI: create a project, run the credential-free sample, connect a runtime provider, and hand the first agent to your coding assistant. Desktop reads provider status from the same bundled runtime that will run the agent. If login is required, the coding agent stops and asks you to run it in Terminal rather than passing credentials or OAuth details through coding-agent chat. After you copy the first-agent prompt, onboarding stays on the current screen and checks for the new agent. When it appears, select Open agent to review and run it. If creation takes too long, you can copy the prompt again or check for the agent manually.

​
Command line launcher

The optional launcher makes the bundled CLI available at:
~/.local/bin must be on your shell’s PATH before a bare agentuse command can resolve to it. Desktop does not edit shell configuration automatically. Settings lists every executable named agentuse found on the login-shell PATH, in resolution order. The first path is the command the shell runs when you enter agentuse. You can add or replace the launcher at ~/.local/bin/agentuse even when npm, pnpm, Bun, Yarn, Homebrew, or another installation exists elsewhere. Desktop never modifies those other installations. Use Add, Replace, or Remove in Settings to manage only the bundled launcher. If a different installation appears first, either call the displayed launcher path directly or change your shell’s PATH order.

​
Global shortcut

The global shortcut is off by default so AgentUse does not take over a key combination used by macOS or another app. Record one in Settings to show or hide the Dashboard from anywhere. Open Settings → General and select the shortcut button to record a different combination. Hyper shortcuts are supported: the star in ✦ A represents Control+Option+Command+Shift (⌃⌥⌘⇧), including Caps Lock mappings that emit those modifiers. Select Clear to disable the shortcut. If macOS or another app already owns a combination, AgentUse keeps the previous working shortcut and asks you to choose another.

​
How it behaves

Launching AgentUse opens the dashboard. Closing the window hides it without stopping the backend, so schedules, approvals, and active runs remain available. Use the AgentUse menu-bar icon to:
  • show the AgentUse dashboard
  • open Settings
  • quit AgentUse
Settings shows whether the local server is running, lets you start or stop a server owned by the desktop app, configures launch at login and the CLI launcher, controls native approval and session-completion notifications, and displays the current server log. The Settings window uses native SwiftUI controls while the dashboard remains the existing web interface. A server started outside the app is identified as external and is never stopped by the desktop controls. If that external server restarts, Desktop keeps its port available and reconnects instead of starting a competing server. Use Start Server explicitly if the external server has been retired and you want Desktop to replace it. Login launches start in the background so the menu-bar status and approvals are available without opening the dashboard window. The dashboard gear opens Dashboard preferences for theme, Home layout, session list style, and reloading the dashboard. Select Open Mac Settings… there for server, login, shortcut, CLI, native notification, and log controls.

​
Updates

AgentUse checks quietly for updates without interrupting startup and downloads available updates in the background. When an update is ready, choose Restart Now in the native prompt or Later to keep working. You can also open Settings → About to check manually or restart and install a downloaded update. AgentUse never installs an update without an explicit restart decision. Closing the Dashboard, using Command+Q, or choosing Quit from the Dock hides the app without stopping its backend. Only Quit AgentUse from the menu-bar item fully exits the app and stops a backend it started. A backend that was already running when the app launched is left alone. Only one desktop app instance can run at a time. When the app owns the running server, choosing Quit AgentUse from the menu-bar item asks for confirmation and explains that the server will stop with the app. Choose Keep AgentUse Running and hide the Dashboard window instead when schedules and approvals should remain available in the background. The desktop window accepts only the loopback dashboard origin. Links to normal http or https sites open in the default browser; other external navigation is blocked. Electron renderer access to Node.js is disabled and context isolation is enabled.

​
Troubleshooting

If the window does not load, open Settings from the menu-bar item and check the server status and Logs tab. You can also use the CLI independently:
See Operations Dashboard for dashboard behavior and CLI Commands for the full serve reference.

Developing AgentUse for Mac

Run the Desktop app from source, install local builds, and create signed releases.