cliodeck-app

ClioDeck — Research environment for historians

Desktop application (Electron + React + TypeScript) for the full historian workflow: explore → brainstorm → write → export, with RAG, Zotero / Tropy / Obsidian integrations, and a local-first footprint.

Note: ClioDeck is a vibe-coding experiment. Provided as is, at your own risk. Designed by Frédéric Clavert, coded with Claude Code. See my talk on vibe-coding for historians (French) and ethics considerations.

License: GPLv3

Download

Download v1.0.0-rc.5 — release candidate.

• macOS — DMG for Apple Silicon and Intel, signed and notarized by Apple: it opens like any downloaded app. ClioDeck starts on macOS 12, but Ollama needs macOS 14 (Sonoma) or later. On an older macOS, local AI means the embedded models (their engine is built for macOS 14 too; the generation model did answer on macOS 12 when tried, with no guarantee below), or use a cloud provider
• Linux — AppImage and .deb for x86_64 (uname -m prints x86_64); no arm64 build. On Ubuntu 24.04 and later, prefer the .deb: the AppImage cannot use Chromium's sandbox there
• Windows — no build shipped; the code should work on Windows but is untested

On first launch, macOS asks once for your session password so ClioDeck can reach its keychain entry, where it keeps your API keys encrypted — choose Always Allow. See the installation guides for the rest.

Three kinds of project

A project is an article, a book, or a presentation — the choice shapes the editor and the export.

• Article — a single document.md.
• Book — a manuscript in chapters, one Markdown file each, ordered by a manifest. Chapter navigator, manuscript-wide outline and search, footnote renumbering from the first chapter to the last, PDF with numbered chapters and a table of contents — or a single chapter for a working proof. Notes can be footnotes, per-chapter endnotes, or endnotes at the end of the volume; numbering restarts per chapter or runs through; the bibliography is single or per chapter. All of this is set from a dialog (until rc.4 it could only be changed by hand-editing project.json). Chapter numbering and document structure reach both the PDF and Word exports; the choice between footnotes and endnotes stays PDF-only, since it relies on typesetting commands a .docx cannot express. A per-chapter bibliography needs a bibliography file, falling back to a single one when ClioDeck formats the citations itself. See docs/book-architecture.md.
• Presentation — a slides.md edited in the same editor, exported to RevealJS.

Four modes, one workspace

The modes share the same project, sources and index:

• Explore — corpus explorer, similarity finder, textometrics.
• Brainstorm — chat-driven exploration of your corpus, with an ideas board and a graph, and a one-click Send to Write that lands a formatted draft block in the editor.
• Write — CodeMirror 6 live-render Markdown editor (Obsidian-style) with Pandoc citations ([@key], autocomplete from Zotero), footnotes with in-place editing, and byte-perfect file fidelity.
• Export — PDF (Pandoc / LaTeX), Word, RevealJS slides.

Key features

• Your file stays your file — the editor never converts your text to an internal document and back. Open a file, save it untouched, and it is identical byte for byte, line endings and trailing spaces included.
• The assistant can read your manuscript — what you have already written becomes a fourth corpus, next to your PDFs, Tropy archives and Obsidian notes, so you can ask what you wrote about a subject three chapters ago. Excerpts from your own draft are labelled apart from your sources, and the assistant is told not to cite them as evidence. Indexing runs after each save and needs an embeddings model; Settings shows the index state and lets you rebuild it. Until rc.4 the corpus was indexed on every save but never actually surfaced in an answer — its hits were scored on a scale that put them below every external source. See docs/manuscript-corpus.md.
• The AI only ever proposes — no AI feature writes into your document on its own. Anything it suggests arrives as a proposal you accept, alter or refuse, and each decision is recorded: in full in the research journal, as bare counts in the AI usage journal.
• Consent before sending — the assistant will not reach a remote provider without your explicit consent, a rule the application core enforces itself rather than leaving to the interface.
• Typed LLM provider layer — embedded (bundled llama.cpp), Ollama, OpenAI-compatible (llama.cpp, LM Studio, vLLM, OpenAI), Anthropic Claude, Mistral, Google Gemini. Switch backend in a few clicks, no code change. API keys are encrypted at rest via Electron safeStorage (key derived from the OS keyring; on Linux without a keyring it falls back to plain text with a warning).
• Runs fully offline — with Ollama and local models, or with the small embedded models downloaded from the settings panel; no API key needed.
• Interface in French, English and German — fully, since rc.4. Including the templates inserted into your manuscript, which used to arrive in French whatever your language.
• RAG-powered assistant — hybrid search (HNSW + BM25 + RRF K=60), context compression that keeps RAG citations verbatim, query-aware reranking.
• Zotero integration — sync bibliography, download PDFs, manage tags and metadata.
• Tropy integration — import and search primary sources with OCR + multilingual NER (fr / en / de).
• Obsidian vault integration — index notes (frontmatter, wikilinks, tags) into a parallel SQLite+FTS5 store, searchable from Brainstorm.
• Project context — a context.md at the project root (subject, period, conventions to observe) is given to the assistant at the start of every conversation. Until you write in it, nothing is sent. See .cliohints.
• ClioRecipes — YAML workflows chaining brainstorm → search → graph → write → export steps. Four builtin recipes ship for common historian tasks (Zotero review, Tropy thematic analysis, chapter brainstorm, Chicago export). Run them from Settings → Recipes with a typed inputs form and a live event log.
• MCP server (inactive by default) — expose your corpus to Claude Desktop / Cursor over stdio with a typed, auditable JSONL access log. Each tool is granted or withheld one by one; a withheld tool is not registered at all, so the client never sees its name. Reading your own manuscript (list_manuscript / read_manuscript) is the one capability that stays off until you grant it. One-click install for Claude Desktop (a .mcpb extension) or a named entry per project in its configuration file; on Linux, where Claude Desktop does not exist, a claude mcp add command for Claude Code.
• MCP clients — consume external MCP servers (stdio + SSE) with a typed lifecycle state machine, infra-only auto-recovery, and a status view in Settings; their tools are offered to the agent loop.
• Source inspector — scans everything reaching the model from outside for prompt-injection patterns: RAG chunks, third-party MCP tool results, and the project's own context.md, which is injected with high authority and travels with a shared folder. Modes are warn / audit / block; the default is warn, which records without discarding — a primary source legitimately contains imperatives, and truncating a genuine testimony would be worse than the risk avoided. Use audit for corpora of third-party origin.
• AI usage journal — a reflexive, ethics-oriented record of your inference use (volumes, tasks, corpora) plus a manual decision layer: what non-AI alternative existed, why it was set aside, was it worth it. Kept in a separate .cliodeck/journal.db so it can be archived and published independently. It logs volumes and decisions, never prompts. See docs/journal-usage-ia.md.
• Headless CLI — bin/cliodeck (recipe list|run, search, hints show|set, import-cliobrain, rag-benchmark) for batch / CI work, with usage captured in the journal; bin/cliodeck-journal today|week|export to review and annotate it.

Project context and .cliohints

Two layers of durable context, both local-only and never leaked to MCP clients unless you opt in per tool:

• context.md at the project root — the visible one. Subject, period, conventions. Edit it like any other file.
• .cliodeck/hints.md — workspace house rules injected into every prompt: citation style ("always Chicago author-date"), language ("reply in French").

Quick start

1. Pick how the AI runs

Fully local, nothing to install — in Settings, switch to Expert mode and download one of the small embedded models (Qwen2.5-0.5B, ~470 MB, or Qwen2.5-1.5B, ~1 GB), plus the embedded embedding model (Nomic Embed Text v2, ~344 MB) if you want RAG. Modest quality, but no dependency and no network.

Local with Ollama — better quality, still offline. On a Mac, Ollama itself requires macOS 14 (Sonoma) or later:

# macOS
brew install ollama && brew services start ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

ollama pull nomic-embed-text          # embeddings
ollama pull qwen3:8b                  # generation, tool-capable

Pick a tool-capable model if you want the assistant to search your corpus on its own: qwen3:8b/14b/32b, ministral-3:8b/14b, mistral-nemo. The Llama 3.x / 4.x families are served without tools (see OLLAMA_TOOL_CAPABLE_PATTERNS in backend/core/llm/providers/ollama.ts).

Cloud — Anthropic, Mistral, Gemini or any OpenAI-compatible endpoint. The same provider can serve embeddings, so no local Ollama is needed.

2. Install ClioDeck

Download from Releases and run. Detailed guides: macOS · Linux.

Build from source

git clone https://github.com/cliodeck/cliodeck-app.git
cd cliodeck-app
npm install
npm run build
npm start

Native modules (better-sqlite3, hnswlib-node) are compiled for Electron's ABI by the postinstall. Running the test suite under Node needs npm rebuild better-sqlite3 first — that is what npm run test:integration does, and what CI does. See the Build and Deployment Guide.

Coming from ClioBrain?

ClioBrain was absorbed into ClioDeck as the Brainstorm mode and is in maintenance mode; new features go to ClioDeck.

npm run cliodeck -- import-cliobrain /path/to/your/cliobrain/workspace

The importer copies brain.db, hnsw.index, hints.md and the MCP access log into the workspace's .cliodeck/, merging your existing config.json and preserving unknown keys. Legacy workspace layouts are migrated automatically when a project is opened. See docs/archive/fusion-cliobrain-strategy.md.

Documentation

Full documentation lives in the ClioDeck Wiki.

User guides

• Getting started
• Installation
• The editor
• Books and chapters
• Brainstorm mode
• Keyboard shortcuts
• Zotero integration
• Tropy integration
• Obsidian vault
• Embedded LLM
• Corpus analysis
• Journals and history
• Export presentations
• Word templates

Technical documentation

• Release notes — RC4 (current) · RC3
• Technical architecture
• Book architecture · Editor architecture · Manuscript corpus
• Editor proposals contract — how AI suggestions are adjudicated
• ADR 0001 — RAG pipeline arbitration
• ADR 0005 — threat model, and why the source inspector only warns by default
• AI usage journal (ADR 0007)
• Status and remaining work

Tech stack

Layer	Technologies
Frontend	Electron 43, React 18, TypeScript, CodeMirror 6 / Lezer, Zustand, Vite
Backend	Node.js, better-sqlite3, hnswlib-node, pdfjs-dist, chokidar
LLM layer	Embedded (node-llama-cpp), Ollama, OpenAI-compatible, Anthropic, Mistral, Gemini (typed provider registry)
Embeddings	nomic-embed-text, mxbai-embed-large, Nomic Embed v2 (embedded), OpenAI / Mistral / Gemini embeddings
MCP	@modelcontextprotocol/sdk (server + clients)
Export	Pandoc / LaTeX, docx, RevealJS
Analysis	Python 3.11+, BERTopic (optional)

The Markdown extensions written for the editor are kept as standalone packages under packages/ — @cliodeck/lezer-pandoc-citations and @cliodeck/lezer-footnotes — so they can be reused outside ClioDeck. Not published to npm yet.

Contributing

See our policy.