Install and run Ensemble

Run Ensemble with one command, open it in your browser, and keep it up to date.

On this page

Ensemble is an npm package that you run on your own computer. One command starts it and opens the app in your browser. There is nothing to sign up for. You need Node.js and the GitHub CLI, signed in to the GitHub account whose repositories you want to follow.

#What you need

  • Node.js 22 or later. Check with node --version.
  • The GitHub CLI (gh), installed from cli.github.com and signed in. Ensemble reads GitHub with the CLI's sign-in. It does not ask for, or store, a GitHub token of its own. See GitHub.
  • Optional, for the AI features: a Claude Code sign-in, an Anthropic API key, or a ChatGPT sign-in for Codex. You can add these later. See Claude and Codex.

#Start Ensemble

  1. Sign in to the GitHub CLI, if you have not already: gh auth login.
  2. Run npx ensemble-review in a terminal.
  3. Wait for the address to show. Ensemble opens your browser at http://localhost:4000/app.
  4. Keep the terminal open. Ensemble runs while the command runs. Press Ctrl+C to stop it.
Illustration: The terminal after you start Ensemble.

#What happens the first time

  • Ensemble makes its data folder, ~/.ensemble, and its local database there.
  • It reads your GitHub account through the GitHub CLI and suggests repositories you worked on recently. See Add your repositories.
  • In the background, it downloads the runtimes the AI features use (about 110 MB, one time). It does this after the app is open, so you do not wait for it. Signing in is the only step you do.
  • The model that scores review bot comments is a separate download (about 240 MB). It is downloaded only when you choose to set it up. See Severity scoring.

#Options

OptionWhat it does
--port 4100Listen on another port. The default is 4000.
--no-openDo not open the browser.
--db <path>Use a database file in another place.
--helpShow every option and command.

Commands

  • npx ensemble-review status prints your My Turn list in the terminal, with links. Add --sync to read GitHub first, or --watch to repaint it until you stop it.
  • npx ensemble-review ai login codex signs Ensemble in to Codex with your ChatGPT account. Add --device-auth on a machine with no browser.
  • npx ensemble-review ai install and npx ensemble-review ml install download the AI runtimes or the comment-scoring model now, instead of when Ensemble first needs them.

#Set up the rest

Ensemble works as soon as you add repositories. Everything else is optional. Switch on the parts you want, in this order:

  1. Add your repositories. Tick the ones Ensemble suggests, or search for any repository. See Add your repositories.
  2. Connect your AI agent for AI Review, AI Fix and the chats. Sign in to Claude Code with claude, or sign in to Codex with your ChatGPT account in Settings → AI. See Claude and Codex.
  3. Check the AI budget. On a subscription, Ensemble may use 50% of your week for its automatic runs until you change it. On an API key, there is no limit until you set a weekly budget in US dollars. See The spend budget.
  4. Add the scoring model if your repositories use review bots. It scores each bot comment from nit to critical, on your machine. See Severity scoring.
  5. Connect your issue tracker so reviews can check each pull request against its ticket. GitHub Issues needs nothing. See Jira, Linear and GitHub Issues.
  6. Connect Slack for a daily digest of the team’s Pending board. See Slack.

#Update Ensemble

npx can keep an older copy. To run the newest release, run npx ensemble-review@latest. If you installed it globally, run npm install -g ensemble-review@latest. Your data stays in ~/.ensemble, and the database updates itself the next time Ensemble starts. The Changelog says what each release changed. The version these docs describe is shown at the top of every docs page.