Installation

Every installer puts the same prebuilt binary on your machine. You don't need Go. macOS needs 13 Ventura or later.

macOS

brew install --cask Chemaclass/tap/agnostic-ai

Homebrew, on macOS or Linux.

Linux

curl -fsSL https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.sh | bash

Also on macOS. Checks the release checksum, then installs to /usr/local/bin when writable, otherwise ~/.local/bin.

Windows

irm https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.ps1 | iex

PowerShell on Windows 10 or 11. Installs to %LOCALAPPDATA%\Programs\agnostic-ai and adds it to PATH. Open a new terminal afterwards.

npm

npm install -g agnostic-ai

Node 18 or newer, on any OS.

Verify the install

agnostic-ai --version
# agnostic-ai version X.Y.Z

Command not found? Open a new terminal, or add the install directory to PATH. To prove the binary came from this repository, see Verify a release.

Next: Getting started, or Migration if you already have CLAUDE.md, AGENTS.md, or other tool files.

Upgrade

Command	Effect
`agnostic-ai upgrade`	Upgrade to the latest release.
`agnostic-ai upgrade --check`	Report the install and older binaries on `PATH`. Changes nothing.
`agnostic-ai upgrade --version vX.Y.Z`	Install one specific release.
`agnostic-ai upgrade --requires`	Pin this project's config and schema to the installed release, then sync.

Package-manager installs upgrade through their package manager. See the upgrade reference.

Pin a version or directory

The install script reads two environment variables:

curl -fsSL https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.sh \
  | AGNOSTIC_AI_VERSION=vX.Y.Z AGNOSTIC_AI_INSTALL_DIR="$HOME/bin" bash

On Windows, download install.ps1 and pass its options:

.\install.ps1 -Version vX.Y.Z -InstallDir C:\tools\agnostic-ai

With npm: npm install -g agnostic-ai@X.Y.Z.

Pin it per project

A JavaScript project can add the CLI as a dev dependency. Then every clone and CI job runs the release in the lockfile:

pnpm add -D agnostic-ai@X.Y.Z    # or npm install -D, yarn add -D, bun add -D

From the project root, run agnostic-ai upgrade --requires with that installed CLI, such as pnpm exec agnostic-ai upgrade --requires. It sets requires and the schema URL to the installed release, then syncs. Commit the config and dependency changes together. After a pull bumps both, run your package manager's install. Until then, commands stop with AAI-005.

Optional extras

Shell completion for Bash, Zsh, Fish, and PowerShell: completion.
The Claude Code plugin adds install, setup, import, and sync commands:

/plugin marketplace add Chemaclass/agnostic-ai
/plugin install agnostic-ai@chemaclass

Other install methods

Method	Instructions
Go	`go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest`, with the Go version from go.mod or newer. Put `$(go env GOPATH)/bin` on `PATH`.
Manual	Download your archive and `checksums.txt` from GitHub Releases, verify the checksum, and put the binary on `PATH`.

Troubleshooting

npm reports a missing platform package

npm skipped the optional dependency that holds the binary. This happens with --omit=optional, and with a lockfile copied from another platform. Reinstall with the optional dependencies included:

npm install -g agnostic-ai --force --include=optional

Drop -g for a project install. --include=optional also overrides an omit=optional left in your npm config. The CLI's error message names the right form for your install.

How the npm package works

agnostic-ai is the only package you install. It's a wrapper, and its optional dependencies are six platform packages in the @agnostic-ai organization. npm installs only the one matching your OS and CPU, such as @agnostic-ai/darwin-arm64. Nothing is downloaded and no install script runs, so --ignore-scripts and npm 11's install-script prompt change nothing.

Set AGNOSTIC_AI_BINARY to an absolute path to run a binary the package does not ship.