Skip to main content
The sparkles command runs an installed Claude Code, Codex, or OpenCode agent in a terminal UI and can mirror that session to Sparkles.

​
Prerequisites

Install and sign in to at least one supported local agent:
  • Claude Code, available as claude
  • Codex, available as codex
  • OpenCode, available as opencode
Run sparkles doctor after installation to see which harnesses are available.

​
Installer for macOS and Linux

The HTTPS installer is the recommended channel. It verifies the archive checksum and installs the native binary without requiring Node.js.
The default destination is $XDG_BIN_HOME, or ~/.local/bin when XDG_BIN_HOME is unset. Override the destination or select a version when needed:
SPARKLES_INSTALL_DIR must be writable by the user who runs the installer. System paths such as /usr/local/bin are often root-owned, so either choose a user-owned directory or run the installer as a user with write access to that path.

​
Homebrew

Update an existing installation with:

​
npm and Windows

The npm package installs a native binary for macOS, Windows, glibc Linux, or musl Linux.
Try the CLI without a global install with npx @sparkles-dev/cli.
macOS signing note: The installer and Homebrew channels distribute the signed and notarized v1.3.0 macOS binary. The immutable npm v1.3.0 macOS platform package was published before signing was available. macOS users who require a signed binary should use the installer or Homebrew until a newer signed npm version is published.

​
Verify the installation

Version 1.3.0 prints its version and release commit:
Then authenticate Sparkles for mirrored sessions:
The local agent keeps its own credentials. Sparkles executes the installed harness and does not read or transport that harness’s credential files.

​
Update

Use the command that matches the installation channel: On Windows, update through npm. On macOS and Linux, sparkles update uses the HTTPS installer even when the current executable came from another package manager.

​
Start a session

Run Sparkles from a repository:
Use sparkles --local-only when the session must stay on the current computer. Otherwise, Sparkles asks for consent before it mirrors prompts, agent output, tool activity, and diffs to your organization. Next, learn the terminal UI controls.