Skip to content

1.2 ClioDeck Installation ‐ macOS

Jump to bottom
Frédéric Clavert edited this page Jul 26, 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) is not created automatically — it's a manual step from Settings → Topic Modeling, where you check status and trigger the install.

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.4: Mac.Intel.-.ClioDeck-1.0.0-rc.4.dmg for Intel, Mac.Silicon.-.ClioDeck-1.0.0-rc.4-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

The first time you open Settings, ClioDeck checks the connection to Ollama (http://localhost:11434) — this happens when Settings mounts, not automatically at app launch.

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. There's no "Test Connection" button here (that's Zotero's, further down) — use the 🔄 refresh-models button to confirm Ollama responds and lists your installed models

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
    ├── brain.db            # PDF/Tropy vectors, research history (shared store)
    └── 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