Skip to content

1.2 ClioDeck Installation ‐ macOS

Jump to bottom
Frédéric Clavert edited this page Jul 23, 2026 · 8 revisions

This guide walks you through the complete installation of ClioDeck on macOS, from prerequisites to first launch.

Table of Contents

System Requirements

  • macOS: 10.15 (Catalina) or higher
  • Architecture: Intel (x64) or Apple Silicon (arm64)
  • Disk Space: At least 5 GB free (for application and Ollama models)
  • Memory: 8 GB RAM minimum, 16 GB recommended

Installing Dependencies

1. Homebrew (Package Manager)

If Homebrew is not already installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the displayed instructions to add Homebrew to your PATH.

2. Node.js and npm

ClioDeck requires Node.js 20+ and npm 10+.

# Install Node.js via Homebrew
brew install node@20

# Verify versions
node --version  # Should show v20.x.x or higher
npm --version   # Should show 10.x.x or higher

Alternative: Using nvm (Node Version Manager)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart your terminal, then:
nvm install 20
nvm use 20
nvm alias default 20

3. Python 3

ClioDeck uses Python for certain services (topic modeling). Python 3.11+ is required.

# Check if Python 3 is installed
python3 --version

# If necessary, install via Homebrew
brew install python@3.11

Note: The Python virtual environment (venv) will be created automatically by ClioDeck on first launch.

4. Pandoc and LaTeX (for PDF Export)

ClioDeck requires Pandoc and XeLaTeX to export documents to PDF.

# Install Pandoc
brew install pandoc

# Install MacTeX (complete LaTeX distribution for macOS)
brew install --cask mactex

# Lighter alternative: BasicTeX (smaller but sufficient)
brew install --cask basictex

If using BasicTeX, install the additional required packages:

# Add tlmgr to PATH
eval "$(/usr/local/texlive/2024basic/bin/universal-darwin/tlmgr path add)"

# Install necessary packages
sudo tlmgr update --self
sudo tlmgr install xetex
sudo tlmgr install collection-fontsrecommended
sudo tlmgr install babel-french

Verification:

# Verify Pandoc
pandoc --version

# Verify XeLaTeX
xelatex --version

5. Ollama (Local LLM)

Ollama is required for local AI features (embeddings and chat).

# Install Ollama
brew install ollama

# Start Ollama service
brew services start ollama

# Alternative: Start manually
ollama serve

Download required models:

# Embedding model (required for RAG search)
ollama pull nomic-embed-text

# Chat model (recommended)
ollama pull gemma2:2b

mxbai-embed-large is a valid alternative embedding model, but it is not an automatic fallback — ClioDeck does not switch between the two on its own.

Note on tool use: gemma2:2b cannot call tools (search your corpus, use MCP servers) inside Brainstorm — Ollama only advertises tool support for a specific model whitelist. If you want the assistant to search your corpus on its own, pull a tool-capable model instead:

ollama pull qwen3:8b   # or ministral-3:8b / ministral-3:14b / mistral-nemo

Verification:

# List installed models
ollama list

# Should show at minimum:
# nomic-embed-text
# gemma2:2b

Installing ClioDeck

Option A: Installation from Binaries (User)

  1. Download the DMG

    • Go to GitHub Releases
    • Download the current release (as of v1.0.0-rc.3: ClioDeck-1.0.0-rc.3.dmg for Intel, ClioDeck-1.0.0-rc.3-arm64.dmg for Apple Silicon)

  2. Install the application

    # Double-click the downloaded DMG
# Drag the ClioDeck icon to the Applications folder

  3. Authorize the application (first launch)

    On first launch, macOS may block the application:

    # Method 1: Via interface
# System → Privacy & Security → Open Anyway

# Method 2: Via terminal
xattr -cr /Applications/ClioDeck.app

  4. Launch ClioDeck

    • From Launchpad
    • Or from Applications → ClioDeck

Option B: Installation from Source (Developer)

To contribute to the project or run the development version:

  1. Clone the repository

    git clone https://github.com/cliodeck/cliodeck-app.git
cd cliodeck-app

  2. Install npm dependencies

    Native modules (better-sqlite3, hnswlib-node) are automatically rebuilt for Electron's ABI by the postinstall script — no separate compile step needed:

    npm install

  3. Build the project

    npm run build

  4. Launch in development mode

    # Terminal 1: Compile in watch mode
npm run dev

# Terminal 2: Launch application
npm start

    Or in a single command:

    npm run dev:full

  5. Build application for distribution

    # Build for macOS (both architectures)
npm run build:mac

# Or a single architecture:
npm run build:mac-intel
npm run build:mac-arm

# DMG lands in release/, named after the current package.json version

Initial Configuration

On first ClioDeck launch:

1. Ollama Verification

ClioDeck automatically checks the connection to Ollama (http://localhost:11434).

If connection fails:

  • Make sure Ollama is started: brew services start ollama
  • Or launch manually: ollama serve in a separate terminal
  • Verify port 11434 is not blocked

2. LLM Configuration

  1. Open Settings → LLM Configuration
  2. Verify settings:
    • Backend: Ollama (default)
    • URL: http://localhost:11434
    • Embedding Model: nomic-embed-text
    • Chat Model: gemma2:2b
  3. Click Test Connection to validate

3. Create Your First Project

  1. New Project → choose a folder and a project type: article (a single document.md), book (chapters as separate files under chapters/), or presentation (slides.md).
  2. ClioDeck creates the structure (article example): 
    my-project/
├── project.json            # Project manifest and settings
├── document.md             # Your text (byte-for-byte, no internal conversion)
├── context.md              # Subject, period, conventions — given to the assistant
└── .cliodeck/
    ├── config.json         # Provider/workspace config
    ├── vectors.db          # PDF vector index
    └── hints.md            # Workspace house rules (optional)
    A book project has no document.md — its chapters live under chapters/, listed in project.json.

4. Zotero Configuration (optional)

If you use Zotero:

  1. Get your API Key: https://www.zotero.org/settings/keys/new
    • Permissions: "Read library" and "Write library"
  2. In ClioDeck: Settings → Zotero Integration
  3. Enter your User ID and API Key
  4. Test Connection

Verifying Installation

Complete Test

  1. Verify Ollama

    curl http://localhost:11434/api/tags
# Should return list of installed models

  2. Verify Node.js and npm

    node --version  # v20.x.x or higher
npm --version   # 10.x.x or higher

  3. Verify Python

    python3 --version  # 3.11.x or higher

  4. Verify Pandoc and XeLaTeX

    pandoc --version   # 2.x or higher
xelatex --version  # TeX Live 2020+ or higher

  5. Test ClioDeck

    • Create a new project
    • Add a PDF to your bibliography (Zotero import, or drag-and-drop)
    • Index it via the interface
    • Verify corpus displays statistics

Check Logs

ClioDeck does not currently write logs to a file — output goes to the console only. Launch it from a terminal to see it:

/Applications/ClioDeck.app/Contents/MacOS/ClioDeck

Troubleshooting

Problem: "App can't be opened because it is from an unidentified developer"

xattr -cr /Applications/ClioDeck.app

Then relaunch the application.

Problem: Ollama doesn't respond

# Check if Ollama is running
ps aux | grep ollama

# Restart service
brew services restart ollama

# Or manually
pkill ollama
ollama serve

Problem: "Module did not self-register" (better-sqlite3)

This means the native module wasn't compiled for your architecture.

cd /path/to/cliodeck-app
npm run rebuild:native
npm start

Problem: Python venv doesn't create

Verify Python 3 is properly installed:

python3 --version
which python3

# If necessary, install via Homebrew
brew install python@3.11

Problem: Insufficient memory for models

Ollama models consume RAM:

  • nomic-embed-text: ~1 GB
  • gemma2:2b: ~2 GB
  • mistral:7b-instruct: ~4 GB

Solutions:

  • Close unused applications
  • Use only gemma2:2b (avoid mistral:7b-instruct)
  • Skip Ollama entirely: ClioDeck can also run on a small embedded model (Qwen2.5-0.5B, ~470 MB, downloaded from Settings → LLM) with no separate service to keep running
  • Upgrade your Mac's RAM

Problem: Port 11434 already in use

If another service uses port 11434:

# Identify process
lsof -i :11434

# Option 1: Stop other service
# Option 2: Configure Ollama on another port
OLLAMA_HOST=127.0.0.1:11435 ollama serve

# Then in ClioDeck Settings → LLM → URL: http://localhost:11435

Getting Help

Uninstallation

To completely uninstall ClioDeck:

# Remove application
rm -rf /Applications/ClioDeck.app

# Remove user data
rm -rf ~/Library/Application\ Support/cliodeck

# (Optional) Uninstall Ollama
brew uninstall ollama
rm -rf ~/.ollama

Note: Your ClioDeck projects (.md files, PDFs, .cliodeck/) are not automatically deleted.

Next Steps

Once ClioDeck is installed, see Getting Started for your first project.

License: GPLv3 Support: Open an issue on GitHub for any questions

Clone this wiki locally