cuvette Install
Install

Start Cuvette in three commands.

The terminal is the window where you type commands. Use it on macOS, Linux or Windows. On a Mac with an Apple chip, you can use the desktop app instead.

Terminal Desktop app Models

Terminal

For macOS, Linux and Windows. Cuvette needs Node.js 22 or later. Node.js is a free program that runs Cuvette. Get it from nodejs.org.

  1. Install Cuvette. The script checks Node.js and Python, then installs Cuvette and runs cuvette doctor. Read the script before you run it.
    curl -fsSL https://cuvette.ai/install.sh | sh

    On Windows, use npm, the installer that comes with Node.js: npm i -g @elparko/cuvette.

  2. Check your computer. This command finds the programs and models that Cuvette can use.
    cuvette doctor
  3. Open the app in your browser.
    cuvette app

To install from the git repository instead, see From source.

Desktop app

For macOS 13.5 or later on a Mac with an Apple chip (arm64). One .dmg file, the Mac installer, of about 17 MB. You do not need the terminal.

  1. Download the .dmg file and drag Cuvette to Applications.
  2. Warning: Apple has not signed (approved) the app yet. macOS blocks it the first time.Open it the first time. Right-click Cuvette in Applications and choose Open. Choose Open again in the window that follows.
  3. If macOS 15 or later shows only “Move to Trash” and “Done”, choose Done. Open System Settings, then Privacy & Security. Find the message about Cuvette and click Open Anyway.
  4. Open a folder. Choose File, then Open Folder. You can also drag a folder onto the Cuvette icon in the Dock.

After the first open, Cuvette opens with a double-click.

Download for Mac

The download is on the Releases page of elparko/cuvette on GitHub.

The command line tool and the app use the same core. To type cuvette in Terminal after you install the app, use the menu item Cuvette, Install Command Line Tool. See below.

Install Command Line Tool

Get the cuvette command from the app.

The app can add the cuvette command to Terminal. The command runs the core inside the app, so the app and Terminal use one version.

  1. Open the Cuvette app.
  2. In the menu bar, choose Cuvette, then Install Command Line Tool.
  3. Choose where to put the command. /usr/local/bin is for all users, and macOS asks for an administrator password. ~/.local/bin is for you only and needs no password.
  4. Open a new Terminal window and type cuvette doctor.

If you install the npm package as well, the app shows which cuvette Terminal runs, and asks which one to use. To remove the command, choose Cuvette, Uninstall Command Line Tool. If you move the app, install the command again.

From Finder

Right-click a folder. Ask a question.

Run cuvette install-finder-action one time. Then the Finder menu has the Quick Action Analyze with Cuvette. Cuvette opens with that folder as the data for the session.

Finder
plate-03
  • Open
  • Get Info
  • Rename
  • Analyze with Cuvette
  • Compress “plate-03”

First session

Four steps from question to result.

The harness stops at each point where you must decide.

  1. 1QuestionsThe model reads your files and asks a few short questions about the experiment.
  2. 2Proposed metricsIt writes what it will measure and how. You change a line or approve the list.
  3. 3DemonstrationThe method runs on one sample. You look at the result before the other samples run.
  4. 4ConfirmThe method runs on all samples. Each step goes in the session record.

In a session, press Esc to stop the model. Type /help to see the commands. See each step with pictures.

Models

You choose the model.

cuvette doctor shows the models that it finds. The app asks you to choose one before the first session.

Claude

Cuvette connects to Claude through the Anthropic application programming interface (API). It needs an API key, a secret code from the Anthropic Console.

cuvette key
Key storage and model choice

Cuvette checks the key with the API before it saves it. It saves the key in a file that only your user can read.

cuvette key status shows the key masked. cuvette key remove deletes it. If the environment variable ANTHROPIC_API_KEY is set, Cuvette uses it instead of the saved key.

The default model is claude-opus-5-5. To use a different model, add --model claude:claude-sonnet-5-5 to the command.

Ollama

Runs a model on your own computer. Your data and the conversation stay on your computer.

ollama pull qwen3:8b
Context size and small models

Install Ollama from ollama.com first. Then start a session with --model ollama:qwen3:8b.

The context window is the amount of text that the model can read at one time. Cuvette sets it to 32,768 tokens (word parts) by default.

With a small model, Cuvette gives the model fewer program actions at a time and shortens their results. It also summarizes old messages when the conversation gets near the limit.

OpenAI-style server

Uses any model server that accepts requests in the OpenAI format, on your computer or on a remote computer.

--model "openai:<base url>|<model>"
Second model that checks answers

A second model reads the session record and checks each answer. By default, it is the same model. To change it, add --referee claude:claude-haiku-5-5 to the command.

Requirements

What your computer needs.

  • Node.js 22 or later. The terminal install needs it. The desktop app has its own copy.
  • Java. Only the ImageJ adapter needs it. An adapter is the part of Cuvette that runs one program.
  • The science programs. Cuvette does not install them. Install each program that you use, for example samtools or R with DESeq2.

From source

Build it from GitHub.

git clone https://github.com/elparko/cuvette
cd cuvette
npm ci
npm link
cuvette --help

npm link makes the cuvette command global. To list the adapters, run cuvette adapters. To start a session, run cuvette in your data folder.