> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmonocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install monocle on macOS or Linux.

## Requirements

Before installing monocle, make sure you have:

* A coding agent: [Claude Code](https://claude.com/claude-code), [OpenCode](https://opencode.ai), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google/gemini-cli), or [Pi](https://pi.dev)
* A terminal with 256-color or true color support
* A [Nerd Font](https://www.nerdfonts.com/) for file icons (optional but recommended)

## Homebrew (recommended)

The simplest way to install monocle on macOS or Linux:

```bash theme={"dark"}
brew install --cask josephschmitt/tap/monocle
```

<Note>
  monocle is distributed as a Homebrew **cask**, not a formula — note the
  `--cask` flag.
</Note>

### Upgrading from a formula install

Earlier releases shipped monocle as a Homebrew **formula**
(`brew install josephschmitt/tap/monocle`). It's now a **cask**. If you
installed the old formula, uninstall it before installing the cask —
otherwise Homebrew reports a conflict between the two:

```bash theme={"dark"}
brew uninstall monocle        # remove the old formula
brew install --cask josephschmitt/tap/monocle
```

<Accordion title="Why a cask and not a formula?">
  Homebrew **formulae** are intended to build software from source (or install
  official precompiled "bottles" from homebrew-core). monocle's old formula did
  neither — it just downloaded the prebuilt release binary and dropped it in
  `bin`. Homebrew's `brew audit` rules increasingly discourage that pattern for
  third-party taps, and [GoReleaser deprecated formula generation for
  prebuilt binaries in v2.10](https://goreleaser.com/deprecations#brews) in
  favor of **casks**, which are the modern home for any prebuilt artifact you
  download rather than compile — including CLI tools. Switching keeps monocle's
  release tooling on a supported path. (Because the release binaries aren't
  code-signed/notarized, the cask also strips the macOS quarantine attribute on
  install so Gatekeeper doesn't block the binary.)
</Accordion>

## Pre-built binaries

Download and install a pre-built binary for your platform from [GitHub Releases](https://github.com/josephschmitt/monocle/releases/latest).

<CodeGroup>
  ```bash macOS (Apple Silicon) theme={"dark"}
  curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_darwin_arm64.tar.gz
  tar xzf monocle.tar.gz
  sudo mv monocle /usr/local/bin/
  ```

  ```bash macOS (Intel) theme={"dark"}
  curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_darwin_amd64.tar.gz
  tar xzf monocle.tar.gz
  sudo mv monocle /usr/local/bin/
  ```

  ```bash Linux (x86_64) theme={"dark"}
  curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_linux_amd64.tar.gz
  tar xzf monocle.tar.gz
  sudo mv monocle /usr/local/bin/
  ```

  ```bash Linux (ARM64) theme={"dark"}
  curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_linux_arm64.tar.gz
  tar xzf monocle.tar.gz
  sudo mv monocle /usr/local/bin/
  ```
</CodeGroup>

## Verify the installation

After installing, confirm monocle is available:

```bash theme={"dark"}
monocle --version
```

## Uninstall

To remove monocle and its agent registrations:

```bash theme={"dark"}
monocle unregister all
brew uninstall --cask monocle
```

If you installed from source, run `make uninstall` from the repo directory.

## Next steps

Once monocle is installed, follow the [quick start guide](/quickstart) to register it with your agent and begin reviewing code.