Installation

Install the agnostic-ai command on macOS, Linux, or Windows. It does not install Claude Code, Codex, or any other coding tool.

npm needs Node 18 or newer. The other methods install a ready-made binary that needs neither Node nor Go. On macOS, you need 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.

The browser interface (agnostic-ai ui) ships inside the binary, so it needs no extra download. See the view reference.

Verify the install

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

If the command is 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, set up your project. If it already has CLAUDE.md, AGENTS.md, or other tool files, also read Import an existing setup.

Upgrade agnostic-ai or pin a project version

Upgrade

Run agnostic-ai upgrade. Package-manager installs upgrade through their package manager. See upgrade and migrate for every option.

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

Then run pnpm exec agnostic-ai upgrade --requires (or your manager's equivalent). It raises requires to that release and keeps its form. Commit the config and dependency changes together. After a pull bumps both, run your package manager's install. See upgrade --requires and Node monorepos for syncing on install.

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

Install with Go or download an archive

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. npm obtains the wrapper and matching platform package from its registry or cache. No install script makes a separate binary download, so --ignore-scripts does not block installation. Offline installs need both packages in the cache or mirror.

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