Skip to content
Agent Switch Agent Switch

Install, update & uninstall

Agent Switch is one npm package. The desktop app comes with it: it downloads on first use, so there is nothing else to install.

Requirements

Section titled “Requirements”
  • Node.js 20 or newer.
  • macOS, Linux or Windows. The desktop app runs on macOS (Apple silicon and Intel), Linux x64 and Windows x64.
  • The tools you want to switch. Install Claude Code, Codex or Antigravity as you normally would. Agent Switch uses their own sign-in and their own binary.

Install the CLI

Section titled “Install the CLI”
Terminal window
npm install -g @event4u/agent-switch

This puts agent-switch on your PATH. The package name is @event4u/agent-switch; the bare name agent-switch on npm belongs to an unrelated project.

To try it without installing anything:

Terminal window
npx @event4u/agent-switch doctor

For daily use, install it globally, so that the shell wrapper and asw always find it.

Start the desktop app

Section titled “Start the desktop app”
Terminal window
agent-switch

With no command, Agent Switch starts the desktop app (same as agent-switch gui). On first use it downloads the app that matches your installed version from the project’s GitHub release, keeps it under ~/.agent-switch/gui/<version>/, and runs it. It never runs an installer.

PlatformWhat is downloaded
macOSthe app bundle (.app.tar.gz, universal)
Linux x64an .AppImage
Windows x64a portable .exe

If a new release is still being built, it takes the newest release that already has the app. With no network, it starts the newest copy it already downloaded. Only one copy runs at a time: if the app is already open, a second one is not started.

Prefer an installer?

Section titled “Prefer an installer?”

Every GitHub release also carries installers: .dmg (macOS), .msi and -setup.exe (Windows), .deb and .rpm (Linux). They are not code-signed yet, so the first launch needs one extra click:

Open System Settings › Privacy & Security, find the message about agent-switch, and click Open Anyway. On macOS 14 and earlier you can also right-click the app in Finder and choose Open. Or remove the quarantine flag in a terminal:

Terminal window
xattr -dr com.apple.quarantine /Applications/agent-switch.app

The app that agent-switch downloads for you does not need this step on macOS. It is not fetched through a browser, so macOS does not quarantine it.

Run it in the background

Section titled “Run it in the background”
Terminal window
agent-switch service install

The background service checks every enabled account’s usage every few minutes. It is what keeps balanced starts and limit warnings working while the desktop app is closed. It starts at login through launchd (macOS), systemd --user (Linux) or Task Scheduler (Windows).

Terminal window
agent-switch service status    # is it running, and when did it last check?
agent-switch service stop      # stop it for now
agent-switch service uninstall # remove it

The desktop app starts at login by default after its first run. You can turn that off in Settings › General.

Update

Section titled “Update”
Terminal window
agent-switch update

This installs the latest version through npm and restarts the background service on it. agent-switch check-update only checks. The desktop app checks for updates on its own and offers Restart now when a new version is ready.

Uninstall

Section titled “Uninstall”

  1. Remove Agent Switch’s data and service.

    Terminal window
    agent-switch uninstall           # lists what will be removed
    agent-switch uninstall --force   # removes it

    It removes:

    • every profile Agent Switch created, including its stored login (for Claude on macOS, the profile’s keychain entry);
    • folder rules, settings and the background service;
    • the app launchers in ~/Applications/Agent Switch macOS.

    Your default Claude Code, Codex and Antigravity installs are not touched.

  2. Remove the shell line. Delete the agent-switch shellenv line from your shell’s startup file (~/.zshrc, ~/.bashrc or ~/.bash_profile, ~/.config/fish/config.fish, or $PROFILE).

  3. Remove the CLI.

    Terminal window
    npm uninstall -g @event4u/agent-switch

  4. If you used an installer, remove the desktop app the way you remove any app on your system.

Build from source

Section titled “Build from source”
Terminal window
git clone https://github.com/event4u-app/agent-switch.git
cd agent-switch
npm ci && npm run build && npm link

Next steps

Section titled “Next steps”
Quick start Add your accounts and turn it on.
The desktop app What every view shows.
Platform matrix What works on which OS and with which tool.