Quick start

1. Install the CLI

The install script downloads a self-contained binary for macOS or Linux. No runtime is required. On Windows, run it inside WSL2.

curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh | bash

The binary installs to ~/.local/bin. If the installer reports that this directory is missing from your PATH, follow its instructions before continuing.

2. Create your first agent

Open a terminal in a project directory or a folder of files you want Jazz to work with:

jazz

On first run Jazz welcomes you, lists any provider API keys it found in your environment, and asks whether to turn on desktop notifications. Choose Start setup to pick a provider and model, select a persona, and name your agent. For a hosted provider, supply its API key when asked; Model providers explains how to get credentials. Jazz opens a conversation when setup finishes.

On later runs, jazz shows your agents and a message box. Pick an agent and type a message to start a conversation, or use /resume to continue an earlier one. To open a specific agent directly, run jazz agent chat <agent-name>.

Jazz is free and MIT-licensed. Model providers may charge for usage. To start without a paid API model:

Start using Jazz for free: choose OpenRouter and the Free Models Router model. No credit card.
Run locally: start Ollama with a tool-capable model, then choose ollama during setup.

3. Give it a task

During setup, choose the default persona and name your agent assistant. The conversation opens automatically.

Try this prompt:

Read the files in this directory and explain what this project does.
List the main parts and how to get started. Do not change any files.

Jazz shows the tools the agent calls as it reads. You can ask follow-up questions in the same conversation, or give it a task such as:

Write a GETTING-STARTED.md based on what you found. Include the setup commands
and explain how to run the project.

When Jazz asks for approval, review the proposed change and approve or reject it. You can continue refining the result in the same conversation. To return later, run jazz and enter /resume.

4. Update Jazz

jazz update

Before updating across a minor version, read Upgrading: it explains the versioning policy and what to change when a release renames a setting.

Other installation options

Override the installation directory with JAZZ_INSTALL_DIR, or pin a version with JAZZ_VERSION:

curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh |
  JAZZ_VERSION=v0.15.21 JAZZ_INSTALL_DIR="$HOME/bin" bash

Jazz is also on npm, which installs the same macOS or Linux binary through your package manager:

# npm
npm install -g jazz-ai

# bun (--trust lets the postinstall script fetch the platform binary)
bun add -g --trust jazz-ai

# pnpm
pnpm add -g jazz-ai

# yarn
yarn global add jazz-ai

jazz update upgrades either kind of installation: a binary replaces itself from the GitHub release, and a package install goes back through the package manager that put it there.

Windows is not supported natively, by the installer or by npm. Install Jazz inside WSL2 with the curl command above; it behaves there as it does on any Linux machine.

Verify where a binary came from

The checksum check proves the download is intact. To prove it was built by this repository’s release workflow, check its build provenance with the GitHub CLI. Release binaries with signed attestations can be checked as follows:

tag="v$(jazz --version)"
gh release download "$tag" --repo lvndry/jazz --pattern 'jazz-darwin-arm64.gz'
gh attestation verify jazz-darwin-arm64.gz --repo lvndry/jazz

Swap in the asset for your platform (jazz-linux-x64.gz, jazz-linux-arm64-musl.gz, and so on).

Next steps

CLI: conversations, attachments, approvals, and run controls
CLI reference: all commands and flags
Creating agents: configure one for a specific job
Surfaces: run the same agent headless, on a schedule, in CI, or in a chat thread
Guides: copy-pasteable recipes
Concepts: learn the vocabulary behind Jazz