Skip to content
Installation

Installation

Choose the interface you need:

InterfaceAvailability
aims CLIReleased for macOS, Linux and Windows; installation methods below
Aims Usage for macOSSource preview with menu bar, optional Edge Dock and pinned overview

The CLI is one static binary with no runtime to install. It needs Claude Code, Codex, or both; provider CLIs are installed separately.

Install

These commands install the CLI. The Homebrew aims cask includes the CLI’s keepalive wrapper on macOS; it does not install Aims Usage.

macOS and Linux:

brew install --cask doguyilmaz/tap/aims

Shell completion for bash, zsh and fish comes with it. aims upgrade (or brew upgrade --cask doguyilmaz/tap/aims) keeps it current.

Release archives for every platform, with checksums.txt, are on the releases page.

Aims Usage for macOS

The menu bar, Edge Dock and overview ship together in Aims Usage.app. The app includes an aims executable and reads your existing aims configuration and native provider logins. Standalone CLI/package-manager updates remain separate.

Source preview: the signed public app archive, aims-usage cask and production Sparkle feed have not been activated. Build from a checkout containing the app on macOS 14.0.0+ with Swift 6.2.0+ and the Go version declared in go.mod available on PATH:

scripts/build-macos-app.sh
'dist/Aims Usage.app/Contents/Resources/aims' app install --from 'dist/Aims Usage.app'
"$HOME/Applications/Aims Usage.app/Contents/Resources/aims" app open

This copies the verified bundle to ~/Applications without replacing an existing app. It exposes the bundled CLI at ~/.local/bin/aims only when no terminal CLI exists; add that directory to PATH if needed. Existing CLI installations and shell files remain intact. Set up Claude/Codex profiles with aims init; for an existing custom AIMS_HOME, select that same folder in the app’s Settings. Provider CLIs manage their own logins. See Aims Usage for macOS for the complete guide and preview images.

On macOS, the CLI offers aims app, aims app install, aims app open and aims app status --json; the TUI offers m, and init/setup expose --app. Public installation uses the app cask after its release; source previews use --from above. The prepared app cask also installs the CLI dependency, while a direct download already includes a bundled CLI. More → Terminal command… in the app adds that command to ~/.local/bin without overwriting an existing CLI. These app-specific commands/options and doctor checks are absent on Linux/Windows. An absent optional app is informational in doctor and never installed by doctor --fix.

Check it works

aims --version
aims doctor

doctor checks paths, shared folders and integrations without changes or credential access. Use aims doctor --fix for conservative repairs and aims doctor --logins for explicit local login/version inspection. Then go on with the Quick start.

Supported platforms

OSArchitecturesShared folders are linked with
macOSarm64, amd64symlinks
Linuxarm64, amd64symlinks
Windowsamd64symlinks, or junctions and hard links without Developer Mode

Shell completion

Homebrew installs completion for you. Otherwise aims setup --shell adds one guarded line to your shell’s startup file that loads completion together with the shell integration. To load only completion:

source <(aims completion zsh)

Completion knows your tools and profile names, so aims use <Tab> lists your accounts.

Upgrade

aims upgrade

aims works out how it was installed (Homebrew, Scoop, npm or go install) and runs that tool’s upgrade. A copy where the install script puts it (AIMS_BIN_DIR, by default ~/.local/bin) is upgraded by running the script again, which checks the download against the release’s checksums. A copy anywhere else gets the command that installs the newest release. aims upgrade --check only prints what it would run.

aims checks for a new release at most once a day, in the background, and mentions it after a command finishes. It asks GitHub where its “latest release” page points and sends nothing about you. Set AIMS_NO_UPDATE_CHECK=1 to turn this off.

Uninstall

To remove the CLI, use its package manager (brew uninstall --cask doguyilmaz/tap/aims, npm uninstall -g @doguyilmaz/aims) or remove the installed binary. To remove Aims Usage, quit it and move its app bundle to Trash. These steps preserve aims profiles, provider logins, sessions, history and reminders.

aims wipe is an explicit, separate data-removal operation: it logs out and deletes the profiles aims created. Use it only when you also want that account data removed; ordinary uninstallation does not require it. The hub’s ~/.claude and ~/.codex remain, including shared data. Private profile data can be removed by wipe, so preserve anything you need before choosing it.