---
title: Installation
description: Download and install Claudette on macOS, Linux, or Windows.
---

## Install on macOS (Homebrew)

The recommended path on macOS is [Homebrew](https://brew.sh/), via the Utensils tap:

```bash
brew install --cask utensils/tap/claudette
```

This taps [`utensils/homebrew-tap`](https://github.com/utensils/homebrew-tap) on first run, downloads the Developer ID-signed, Apple-notarized `.dmg` for your architecture (Apple Silicon or Intel), drags `Claudette.app` into `/Applications`, and registers it with Spotlight and Launchpad. Claudette ships its own signed Tauri updater, so `brew upgrade` only refreshes the cask version pointer — in-place updates are handled by the app itself. To uninstall and remove all local data (workspaces, plugins, DB, caches), run `brew uninstall --zap --cask claudette`.

:::note
Claudette lives in a personal tap rather than the main `homebrew-cask` repository until the GitHub project crosses Homebrew's notability threshold (≥75 stars, ≥30 forks, or ≥30 watchers). The cask format and install behavior are identical; only the tap prefix differs. Star or watch [utensils/Claudette](https://github.com/utensils/Claudette) if you'd like to help move it upstream.
:::

## Download

Claudette is also available as a pre-built binary from [GitHub Releases](https://github.com/utensils/Claudette/releases).

| Platform | Architecture | Format |
|----------|-------------|--------|
| macOS | Apple Silicon (aarch64) | `.dmg` |
| macOS | Intel (x86_64) | `.dmg` |
| Linux | x86_64 | `.deb` |
| Linux | aarch64 | `.deb` |
| Windows | x86_64 | `.zip` |
| Windows | ARM64 | `.zip` |

1. Download the appropriate binary for your platform from the [latest release](https://github.com/utensils/Claudette/releases/latest)
2. **macOS**: Open the `.dmg` and drag Claudette to your Applications folder (or use the Homebrew cask above)
3. **Linux**: Install the `.deb` package with `sudo apt install ./Claudette_*.deb`
4. **Windows**: Extract the `.zip` archive and run `claudette.exe`

:::note
Linux `.AppImage` is temporarily unavailable — `linuxdeploy` can't parse the Pi harness sidecar's binary format. Install via `.deb` until AppImage is restored. Tracking: [#825](https://github.com/utensils/Claudette/issues/825).
:::

### Arch Linux (AUR)

Claudette is published to the [Arch User Repository](https://aur.archlinux.org) in three flavours:

| Package | Source | Cadence |
|---------|--------|---------|
| [`claudette-bin`](https://aur.archlinux.org/packages/claudette-bin) | Repackages the upstream `.deb` | Every tagged release |
| [`claudette`](https://aur.archlinux.org/packages/claudette) | Builds from the release tarball | Every tagged release |
| [`claudette-git`](https://aur.archlinux.org/packages/claudette-git) | Builds from `main` HEAD | Track upstream `main` |

Install with your AUR helper of choice — `paru` and `yay` are the common ones:

```bash
# Fastest path: download + repackage the .deb (no compile)
paru -S claudette-bin

# From-source build (pulls rust, bun, webkit2gtk-4.1, etc.)
paru -S claudette

# Bleeding edge — tracks main
paru -S claudette-git
```

The three packages conflict, so install only one. PKGBUILDs live in-tree at [`packaging/aur/`](https://github.com/utensils/Claudette/tree/main/packaging/aur) — file PRs there for packaging fixes.

### Linux: native file dialogs

Claudette's **Browse** buttons (Add Repo, attach files, settings) call into Tauri's dialog plugin, which on Linux routes through `org.freedesktop.portal.FileChooser`. The portal needs a running daemon **and** a backend implementing the FileChooser interface — full desktop environments (GNOME, KDE, Cinnamon, MATE, XFCE with its goodies) pull these in transitively, but minimal installs (Openbox-only, i3, sway with no DE) usually do not.

```bash
# Most desktops on Arch — install one matching your DE:
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-gtk      # GTK-based (XFCE, MATE, Cinnamon)
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-gnome    # GNOME
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-kde      # KDE Plasma
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-hyprland # Hyprland
```

When no portal is detected, Claudette silently hides the Browse buttons and shows a context-appropriate hint — paths in Add Repo / Settings can be pasted into the text input; chat attachments can be drag-and-dropped into the composer. The app stays functional but loses native file pickers. Capability is probed once at startup; install the portal stack and restart Claudette to recover the buttons.

## Prerequisites

Before using Claudette, ensure you have **Claude Code** installed and authenticated:

```bash
# Install Claude Code if you haven't already
# See: https://docs.anthropic.com/en/docs/claude-code

# Authenticate with your Anthropic account
claude /login
```

## macOS permission prompts

After install, macOS may surface a few first-run permission prompts. Each is gated by Apple's TCC (Transparency, Consent, and Control) system and fires the first time Claudette exercises the underlying capability. Two of them — **Local Network** and **Notifications** — fire at or shortly after first launch, because the capabilities they gate (mDNS discovery, the notification subsystem) are initialized during app startup. The rest are deferred until you actually use the feature that needs them.

### "Claudette wants permission to update or delete other applications."

This is macOS's **App Management** prompt (Ventura 13+). It appears the first time Claudette installs its own update — the signed Tauri updater fetches a new build from the [GitHub release feed](https://github.com/utensils/Claudette/releases/latest), verifies the minisign signature against the public key embedded in the app, and replaces the `Claudette.app` bundle in `/Applications`. macOS sees one app modifying another app bundle on disk and requires you to grant the permission once.

- **Grant it** to enable in-app auto-updates. The permission is scoped to Claudette — it does not let Claudette touch any other application.
- **Deny it** and you'll need to update manually by downloading the latest `.dmg` from [Releases](https://github.com/utensils/Claudette/releases/latest) and replacing the bundle in `/Applications` yourself.
- The choice can be changed at any time in **System Settings → Privacy & Security → App Management → Claudette**.

If you installed Claudette outside `/Applications` (e.g. ran it directly from `~/Downloads`), the prompt may not appear until the first time the updater tries to swap the bundle.

### "Claudette would like to find and connect to devices on your local network."

This is macOS's **Local Network** prompt (Sonoma 14+). It appears shortly after first launch because Claudette runs an mDNS browser that discovers other Claudette instances on your LAN to populate the **Nearby** section of the sidebar (used by [remote workspaces](/claudette/features/remote-workspaces/)). The browser is read-only — Claudette doesn't advertise itself unless you run the standalone `claudette-server` binary.

- **Grant it** to see nearby Claudette servers in the sidebar and use remote workspaces over the LAN.
- **Deny it** and the app keeps working — the Nearby list just stays empty. Direct connections to a server by IP/hostname still work, since those don't need mDNS.
- Toggle later in **System Settings → Privacy & Security → Local Network → Claudette**.

### "Claudette would like to send you notifications."

The standard macOS notification prompt. It fires at first launch so the app can post native banners later for events like *agent finished a turn*, *agent is asking a question*, and *plan needs review*. See [Notifications](/claudette/features/notifications/) for the per-event toggles inside the app.

- **Grant it** for OS-level banners and click-to-navigate (clicking a banner focuses the relevant workspace and chat).
- **Deny it** and in-app indicators (sidebar badges, tray tooltip, optional custom sound) still work — only the native banners are suppressed.
- Toggle later in **System Settings → Notifications → Claudette**.

### "Claudette wants to use the microphone" / "speech recognition"

These fire the first time you click the chat composer's mic button. See [Voice Input → Apple Speech](/claudette/features/voice-input/#apple-speech) for the full setup.

### "Claudette wants to control Terminal" (or "iTerm")

This is macOS's **Automation** prompt. It fires the first time you launch a TUI editor or open a workspace path in an external Terminal.app or iTerm2 window — Claudette sends an Apple Event to ask the terminal app to open a new window `cd`'d into the worktree. Denying it disables that one launch target but doesn't affect anything else.

All of these can be reviewed or changed later in **System Settings → Privacy & Security**.

## Windows network prompt

If you run the standalone `claudette-server` binary (used to share workspaces with another machine via [remote workspaces](/claudette/features/remote-workspaces/)), Windows Defender Firewall will ask whether to allow it to communicate on Private or Public networks. The Tauri GUI on its own does **not** trigger this prompt — it doesn't accept inbound LAN traffic. It exposes a local IPC named pipe for the [CLI client](/claudette/features/cli-client/), and any TCP sockets it opens (e.g. the dev-only debug eval server) bind to `127.0.0.1`, which Windows Firewall exempts from the network-access dialog.

- Choose **Private networks** unless you intentionally want to expose the server on a public/coffee-shop network.
- Change later in **Windows Security → Firewall & network protection → Allow an app through firewall**.

Windows builds in CI are unsigned `.exe` files, so **Microsoft Defender SmartScreen** may also warn the first time you run Claudette — click **More info → Run anyway** to proceed.

## Build from Source

If you prefer to build from source, you'll need:

- [Rust](https://rustup.rs/) (stable toolchain, edition 2024)
- [Bun](https://bun.sh/) (JavaScript runtime and package manager)
- [Tauri CLI](https://tauri.app/start/): `cargo install tauri-cli --version "^2"`

**Platform dependencies:**

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="macOS">
    ```bash
    xcode-select --install
    ```
  </TabItem>
  <TabItem label="Linux (Debian/Ubuntu)">
    ```bash
    sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
      libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
    ```
  </TabItem>
  <TabItem label="Windows">
    Install [Visual Studio C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the **Desktop development with C++** workload, then install the Rust toolchain via [rustup](https://rustup.rs/).

    On ARM64, also install Clang/LLVM (e.g. `scoop install llvm`) — the `ring` build script requires `clang` on PATH for its ARM assembly. WebView2 ships with Windows 11 and recent Windows 10.

    For development, use **PowerShell 7 (`pwsh`)** rather than Windows PowerShell 5.1 — the dev launcher and the recommended profile function lean on pwsh-only conveniences.
  </TabItem>
</Tabs>

**Build steps:**

```bash
# Clone the repository
git clone https://github.com/utensils/Claudette.git
cd Claudette

# Install frontend dependencies
cd src/ui && bun install && cd ../..

# Build optimized release binary
cargo tauri build
```

The compiled binary will be in `target/release/` at the workspace root (Claudette uses a Cargo workspace, so the `src-tauri` crate's outputs share the workspace target dir, not its own).

## Run from source

Pick the launcher that matches your platform — `--new`, `--clean`, and `-h`/`--help` work on both. `--clone` (rsync mirror of your real setup into a stable sandbox dir; re-runs sync incrementally) is currently macOS/Linux only.

<Tabs>
  <TabItem label="macOS / Linux">
    ```bash
    # Full-feature dev launcher (required for macOS voice input)
    ./scripts/dev.sh

    # Per-PID empty sandbox under $TMPDIR — first-run / new-user UX
    ./scripts/dev.sh --new

    # Mirror your real setup into a stable sandbox dir via rsync; re-runs
    # sync incrementally. Isolated from the running release app.
    ./scripts/dev.sh --clone

    # GC stale sandboxes from killed dev runs and exit
    ./scripts/dev.sh --clean

    # Plain Tauri (no port probing, no signed bundle, no voice on macOS)
    cargo tauri dev
    ```
  </TabItem>
  <TabItem label="Windows">
    ```powershell
    # Full-feature dev launcher
    .\scripts\dev.ps1

    # Per-PID empty sandbox under $env:TEMP — first-run / new-user UX
    .\scripts\dev.ps1 --new

    # GC stale sandboxes from killed dev runs and exit
    .\scripts\dev.ps1 --clean

    # Print full flag and env var reference
    .\scripts\dev.ps1 --help
    ```

    For a bare `dev` command, drop this into your PowerShell profile (`$PROFILE`):

    ```powershell
    function dev {
        $repo = "<absolute path to your claudette clone>"
        & "$repo\scripts\dev.ps1" @args
    }
    ```
  </TabItem>
</Tabs>

Both launchers do a few things `cargo tauri dev` doesn't:

- **macOS only**: wraps the binary in a signed `Claudette Dev.app` bundle so macOS's privacy system (TCC) grants Microphone and Speech Recognition permissions. A bare Mach-O binary will be killed by TCC the moment the prompt appears.
- Probes free Vite + debug-eval ports so multiple dev instances can run side by side.
- Stages the `claudette-cli` sidecar binary so the in-app CLI install path works in dev.

**Windows-only details** the PowerShell launcher handles for you:

- Forces Vite to bind on `127.0.0.1` (IPv4). The default `localhost` resolves to `::1` first on Windows, but WebView2 navigates IPv4-first, so a mismatch surfaces as a blank webview with `HRESULT 0x80070057`.
- Defaults to the same feature set as `scripts/dev.sh` — `devtools,server,voice,alternative-backends,pi-sdk`. On `aarch64-pc-windows-msvc` the launcher appends `-C target-feature=+fullfp16` to `$env:RUSTFLAGS` so the `gemm-f16` ARMv8.2 inline asm in the `voice` feature compiles. Existing `RUSTFLAGS` are kept (rustc concatenates `-C target-feature` directives), so any flags you already set continue to apply.
- Skips `tauri/custom-protocol`. With it on, `import.meta.env.DEV` is false in the webview, which leaves `window.__CLAUDETTE_INVOKE__` unset and breaks the [`/claudette-debug`](/claudette/) eval server.
- Stages the `claudette-cli` sidecar at the path Tauri's `bundle.externalBin` expects — `tauri.conf.json`'s `beforeDevCommand` shell script can't run on Windows.

## Headless / sandboxed Linux

If you're on a Linux host without ALSA (containers, CI, sandboxed environments), build without voice support:

```bash
cargo tauri build --no-default-features --features tauri/custom-protocol,server
```

The `server` feature keeps the embedded WebSocket server for [remote workspaces](/claudette/features/remote-workspaces/); drop it too if you don't need that.

## Building without the Pi harness

Routine builds ship the [Pi coding-agent harness](/claudette/features/providers/pi/) sidecar and its `~70 MB` of bundled assets by default. If you're shipping a Claudette variant that doesn't need Pi (an internal fork that only supports Claude Code + Codex Native, a slimmed binary for a constrained environment, etc.), drop the `pi-sdk` feature and pair the build with the no-pi overlay so Tauri's bundler stops looking for the sidecar:

```bash
cargo tauri build \
  --no-default-features \
  --features tauri/custom-protocol,server,voice,devtools,alternative-backends \
  -c src-tauri/tauri.no-pi.conf.json
```

This still ships Codex Native and the rest of the alt-backend surface — only Pi is gone. The Rust resolver, the Tauri commands, the Pi sidecar, and the Pi card / Pi runtime option in **Settings > Models** are all absent from the resulting binary; the chat picker and `/model` slash command never expose Pi rows. The same recipe works for `cargo tauri dev` if you need a no-pi dev loop — drop `--config` and pass `--no-default-features` through the dev runner.
