Installation

Install Jean on macOS, Windows, or Linux and set up your development environment

Installation

Jean is available for macOS, Windows, and Linux. Choose your preferred installation method below.

Quick Install

macOS (Homebrew)

The easiest way to install Jean on macOS:

brew tap coollabsio/jean
brew install --cask jean

Homebrew will automatically manage updates. Run brew upgrade jean to update to the latest version.

GitHub Releases

Download the latest release for your platform:

1. Visit the GitHub Releases page
2. Download the appropriate installer:
   • macOS: Jean_<version>_universal.dmg
   • Windows: Jean_<version>_x64_en-US.msi
   • Linux: jean_<version>_amd64.deb or jean-<version>.x86_64.rpm
3. Install the application following your platform’s standard installation process

You can also visit jean.build for direct download links.

Prerequisites

Jean requires at least one of the following AI CLI tools to be installed:

Claude CLI (Recommended)

Install Claude CLI from Anthropic:

# Install Claude CLI following Anthropic's official instructions
# Visit the Claude CLI GitHub repository for the latest installation method

Configuration:

• Requires an Anthropic API key
• Configure with claude config
• Supports MCP servers for extended capabilities

Learn more in the official Claude CLI documentation

Codex CLI

Install Codex CLI for DeepSeek-powered coding:

# Installation instructions
# Visit Codex CLI repository for latest instructions

Features:

• DeepSeek-V3 model support
• Reasoning effort levels
• Multi-agent collaboration (experimental)

Codex CLI support is newer. Some features may have limited functionality.

OpenCode

Install OpenCode for multi-model support:

# Installation instructions
# Visit OpenCode repository for latest instructions

Features:

• Multiple AI provider support (OpenRouter, etc.)
• Custom provider profiles
• Compatible with Claude CLI MCP servers

You can install multiple CLI tools and switch between them per-project or per-session.

Platform-Specific Requirements

macOS

System Requirements

• macOS 10.15 (Catalina) or later
• Universal binary supports both Intel and Apple Silicon

Additional Setup

Xcode Command Line Tools (for git and development tools):

xcode-select --install

GitHub CLI (optional, for enhanced GitHub integration):

brew install gh
gh auth login

Jean can auto-install GitHub CLI if not present, but manual installation is recommended for better control.

Windows

System Requirements

• Windows 10 or Windows 11
• x64 architecture

Additional Setup

Git for Windows (required):

1. Download from git-scm.com
2. Install with recommended settings
3. Configure your identity:

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

GitHub CLI (optional):

winget install --id GitHub.cli
gh auth login

Windows support is not fully tested. Please report any issues on GitHub.

Linux

System Requirements

• Modern Linux distribution (Ubuntu 20.04+, Debian 11+, Fedora 35+)
• x86_64 architecture

Dependencies

Debian/Ubuntu/Linux Mint:

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev librsvg2-dev patchelf

# Ubuntu/Linux Mint: Use Ayatana AppIndicator
sudo apt install libayatana-appindicator3-dev

# Debian/older distros:
# sudo apt install libappindicator3-dev

Fedora/RHEL:

sudo dnf install webkit2gtk4.1-devel librsvg2-devel patchelf

GitHub CLI:

# Debian/Ubuntu
sudo apt install gh

# Fedora
sudo dnf install gh

# Then authenticate
gh auth login

Linux is not officially tested. Community contributions and bug reports are welcome.

Git Configuration

Jean requires git to be configured with your identity:

# Check current configuration
git config --global user.name
git config --global user.email

# Set if not configured
git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Jean will prompt you to configure git identity on first launch if not already set.

Building from Source

For developers who want to build Jean from source:

1. Install Prerequisites

   Required:

   • Node.js v20 or later
   • Bun (recommended) or npm
   • Rust stable toolchain

   Platform-specific:

   • Windows: Visual Studio with “Desktop development with C++” workload
   • Linux: See platform-specific dependencies above
2. Clone Repository

   git clone https://github.com/coollabsio/jean.git
   cd jean
   
3. Install Dependencies

   bun install
   
4. Run Development Build

   bun run tauri:dev
   
5. Build Production Package

   # Build for your platform
   bun run tauri:build
   
   # Platform-specific builds
   bun run tauri:build:macos    # Universal macOS build
   bun run tauri:build:windows  # Windows MSI/NSIS
   bun run tauri:build:linux    # Linux DEB/RPM
   

   Built artifacts will be in src-tauri/target/release/bundle/

Development Setup Details

For full development setup including testing, linting, and code quality checks, see:

• CONTRIBUTING.md
• docs/developer/architecture-guide.md

Key commands:

bun run check:all    # Run all quality checks
bun run test         # Run tests in watch mode
bun run lint:fix     # Fix linting issues
bun run format       # Format code with Prettier

Verification

After installation, verify Jean is working:

1. Launch Jean

   Open Jean from your Applications folder (macOS/Linux) or Start Menu (Windows)

2. Check CLI Detection

   Jean will automatically detect installed CLI tools (Claude CLI, Codex CLI, OpenCode)

   If not detected, check:

   • CLI is installed and in your PATH
   • CLI is configured with API credentials
   • Terminal has been restarted after CLI installation
3. Verify Git Configuration

   Jean will check for git identity. If not configured, you’ll see a setup prompt.

4. Add Your First Project

   Click Add Project and select a git repository to get started

Troubleshooting

CLI Not Detected

If Jean doesn’t detect your CLI installation:

1. Verify CLI is installed:

   claude --version   # or codex --version, opencode --version
   

2. Ensure CLI is in PATH:

   which claude       # macOS/Linux
   where claude       # Windows
   

3. Restart Jean after installing CLI tools

4. Check CLI configuration:

   claude config      # Claude CLI
   

Git Identity Not Set

If you see git identity errors:

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Restart Jean after configuration.

macOS Gatekeeper Warning

If macOS blocks Jean from opening:

1. Go to System Settings > Privacy & Security
2. Find the message about Jean being blocked
3. Click Open Anyway

Or use Terminal:

xattr -cr /Applications/Jean.app

Windows SmartScreen

If Windows SmartScreen blocks installation:

1. Click More info
2. Click Run anyway

This is expected for new applications.

Linux AppImage Issues

If AppImage doesn’t run:

chmod +x Jean-*.AppImage
./Jean-*.AppImage

Or install FUSE:

sudo apt install libfuse2  # Ubuntu/Debian

Next Steps

Now that Jean is installed, continue to the quickstart guide:

Quickstart Guide

Learn how to add your first project and create a worktree