Skip to content

Features

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

ClioDeck Features

Version: 1.0.0-rc.4

This document provides an overview of ClioDeck's main features.

Bibliography Management

Zotero Integration

ClioDeck integrates seamlessly with Zotero for bibliography management:

  • Import from Zotero: Connect to your Zotero library and import collections with a single click
  • Bidirectional Sync: Detect changes (additions, modifications, deletions) between local and Zotero bibliographies
  • Conflict Resolution: Three strategies - Remote Wins, Local Wins, or Manual selection
  • PDF Download: Automatically download PDFs from Zotero attachments
  • Collection Selection: Choose which Zotero collection to sync
  • Group Support: Access Zotero group libraries

BibTeX Support

  • Import: Load existing .bib files. Until RC4, any entry missing an author field was silently dropped — edited volumes and anonymous works, common in historical bibliographies, vanished with only a console warning
  • Export: Export bibliography to BibTeX format with all metadata preserved
  • Round-trip: Full preservation of custom fields, tags, and notes during import/export

PDF Management

  • Automatic Indexing: Index PDFs for semantic search using RAG. Switching project mid-indexing used to crash the job; since RC4 the in-flight pass is drained first
  • Batch Download: Download all missing PDFs from Zotero
  • Orphan Detection: Find and clean up PDFs not linked to any citation
  • Archive Option: Safely move orphan PDFs to archive folder instead of deleting

Tags and Metadata

  • Custom Tags: Organize citations with user-defined tags
  • Tag Filtering: Filter bibliography by one or more tags — matches citations with any selected tag (OR), not all of them (AND); there's no mode toggle (citationSlice.ts: citation.tags.some(tag => selectedTags.includes(tag)))
  • Custom Fields: Store additional metadata not covered by BibTeX
  • Notes: Add personal notes to citations
  • Date Tracking: Automatic timestamps for added/modified citations

Statistics Dashboard

Interactive statistics with 5 tabs:

  • Overview: Total counts, year range, PDF coverage, publication types
  • Authors: Top 15 authors, collaboration metrics, publication years
  • Publications: Top journals, yearly distribution histogram
  • Tags: Tag coverage (% of citations tagged) and most-used tags
  • Timeline: Cumulative and annual publication trends

Primary Sources (Tropy Integration)

ClioDeck integrates with Tropy for managing primary sources:

  • Import Tropy Projects: Read .tropy packages and .tpy databases
  • Metadata Sync: Import title, date, creator, archive, collection, tags
  • Transcription Support: Import transcriptions from Tropy notes, OCR (Tesseract), or Transkribus
  • Unified RAG: Search both secondary sources (PDFs) and primary sources (Tropy) together
  • Auto-sync: Detect changes in Tropy files and re-sync automatically and silently — no prompt, no user choice
  • OCR Pipeline: Built-in Tesseract.js for images without transcription

AI-Powered Research Assistant

RAG (Retrieval-Augmented Generation)

  • Semantic Search: Query your indexed PDFs and primary sources using natural language
  • Context Retrieval: Automatically retrieves relevant passages from your corpus
  • Source Citations: Every answer includes references to source documents
  • Multi-source Search: Combines results from PDFs, Tropy sources, an Obsidian vault and — new in RC3 — your own manuscript, whose excerpts are labelled distinctly so you always know when you are reading yourself
  • Configurable Parameters: Adjust topK, similarity threshold, chunking strategy
  • Query Embedding Cache: Optimized performance with LRU cache (2,000 entries, 10min TTL)
  • Context Compression: wired into the retrieval path since RC4 (it was implemented but unreachable before). RC4 also fixed three ways it distorted what you were shown: markdown tables were shredded and recomposed, distant sentences were joined without an ellipsis, and a fallback returned them in score order. Cuts are now marked […], tables and code blocks pass through whole, and document order is preserved
  • RAG Explanation: Transparency about retrieval process (chunks used, source types, compression ratio)
  • Stream Cancellation: Cancel ongoing generation at any time

Manuscript corpus (interface new in RC4)

  • Your own text is indexed as a fourth corpus, beside the bibliography, Tropy archives and Obsidian vault — so the assistant can answer "what have I already written about this?"
  • Excerpts are always labelled as coming from the manuscript, never from the bibliography: you must be able to see when you are citing yourself
  • Settings → Manuscript corpus shows the index state (pieces, extracts, date of the last indexing pass), offers a re-index button, and exposes the on/off switch. Until RC4 the corpus was indexed on every save but never actually reached the assistant, and nothing in the interface showed it

Project Context

  • context.md: describe your subject, period, corpus and conventions; the file is sent to the assistant at the start of every conversation (new in RC3 — the file existed before but nothing read it)
  • .cliodeck/hints.md: still read when present, and combined with it

One Assistant

  • A single chat surface across the application (new in RC3): the side panel and the Brainstorm centre panel were merged
  • Send to the document: turn a reply into an adjudicable proposal in your text, from wherever you are
  • Cloud consent enforced by the main process before anything leaves your machine

LLM Integration

  • Ollama Support: Use local LLMs via Ollama (default: llama3.2; gemma2:2b is a commonly recommended alternative)
  • Embedded LLM: Download and run models directly (Qwen2.5-0.5B, 1.5B) for offline use
  • Auto Fallback: In the default Auto mode, generation always falls back from Ollama to the embedded model when Ollama is unreachable. Embedding fallback is more cautious: it only engages when the embedded and Ollama embedding models share the same vector dimension — a mismatch would silently corrupt similarity search, so ClioDeck fails loud there instead (cliodeck-config-adapter.ts). See Embedded LLM Guide.
  • Cloud providers: Anthropic Claude, OpenAI-compatible endpoints, Mistral, and Google Gemini — connect any of them for generation and/or embeddings (optional)
  • System Prompts: Customizable system prompts in French and English (getDefaultSystemPrompt only accepts 'fr' | 'en' — German is a UI language, not a system-prompt language)

Hybrid Search

  • HNSW Index: Fast approximate nearest neighbor search (~15ms for 50k chunks)
  • BM25 Search: Keyword-based search for proper nouns and acronyms
  • RRF Fusion: Reciprocal Rank Fusion combining both approaches (60% dense / 40% sparse)
  • Multilingual Query Expansion: Automatic FR↔EN translation for academic terms (e.g., "primary sources" ↔ "sources primaires")
  • Exact Match Boosting: Priority for exact keyword matches

Topic Modeling (Optional)

  • BERTopic Integration: Identify main themes in your corpus — the minimum topic size sent is hardcoded to 3 (useCorpusData.ts), silently overriding the Python service's own default of 5, with no UI to change it; see Corpus Analysis Guide
  • Topic Timeline: Visualize theme evolution over time
  • Python Environment: Isolated Python venv for dependencies
  • Optional Feature: Install only if needed

Corpus Analysis

Knowledge Graph

  • Document Network: Visualize relationships between documents
  • Citation Links: Track internal citations within your corpus
  • Similarity Edges: Connect semantically similar documents
  • Community Detection: Identify document clusters (Louvain algorithm)
  • Interactive Exploration: ForceAtlas2 layout with zoom and pan

Textometrics

  • Word Frequencies: Most common words (stopwords removed)
  • N-grams: Bigrams and trigrams analysis
  • Lexical Richness: Type-Token Ratio and vocabulary metrics
  • TF-IDF: Characteristic words identification

Similarity Finder

  • Document Comparison: Compare your text with indexed sources
  • Segment Analysis: Analyze by section, paragraph, or sentence
  • Recommendations: Get relevant source suggestions for each segment
  • Smart Cache: Hash-based caching for performance

Document Editing

The Editor (CodeMirror 6)

One editor, rendering markdown live — the previous WYSIWYG/source pair and its toggle are gone. See The Editor.

  • Live rendering: formatting is shown as you write; the markdown of a construct reappears when your cursor enters it
  • Byte-for-byte fidelity: opening and saving without editing leaves the file strictly identical, line endings included
  • Footnotes: superscript references, hover tooltip, in-place editing popup, jump to definition and back, deliberate renumbering
  • Citations: pills, @ autocompletion from Zotero, resolved reference on hover, unresolved keys flagged without blocking
  • Front matter: YAML block folded out of the way, editable on click
  • Pandoc dialect: footnotes, citations with clusters and locators, GFM tables
  • AI proposals: anything the assistant writes arrives as an adjudicable proposal (accept / reject / edit), never as silent text
  • Auto-save with a status-bar indicator

Books and Chapters

New in RC3 — see Books and Chapters.

  • One file per chapter, ordered by a manifest in project.json
  • Chapter navigator: create, rename, reorder, attach stray files, remove from the manuscript without deleting the file
  • Outline of headings, book-wide search, footnote renumbering and citation checking
  • Book settings: footnote or endnote style, continuous or per-chapter numbering, one bibliography or one per chapter, chapter numbering
  • Export: real chapters, table of contents, front/back matter, or a single chapter as a working proof

Export Options

  • PDF Export: Generate professional PDFs via Pandoc/LaTeX
  • Word Export: Export to .docx format with template support. A cited book used to come out empty of chapter content; fixed in RC4, which also made the export honour chapter numbering and document structure from the book settings (note style stays PDF/LaTeX only). See the Word Templates guide
  • Presentations: reveal.js (online, offline or PDF) and Beamer

Research Journal

  • Session Tracking: Track research sessions and activities
  • Chat History: Review past conversations with the AI assistant — viewable, not resumable; there is no "pick up an earlier conversation" feature anywhere in the app
  • Event Timeline: Within a single session, events shown as a plain chronological list — not a calendar or heatmap across days
  • Date/Time Display: Sessions show both date and time
  • Filter Empty Sessions: Hide sessions without activity
  • AI proposals: every accept / reject / edit is recorded — with the full text in the research journal, and as a bare decision without content in the AI usage journal
  • Purge (RC4): the research journal can be wiped, behind a double confirmation that names what disappears. Deleting a single session is still not possible

Project Management

  • Project Types: Article, Book (multi-file chapters, new in RC3), or Presentation projects
  • Recent Projects: Quick access to recently opened projects. Opening one with unsaved editor changes used to discard them silently; since RC4 the outgoing document is saved first — as it is when you quit the app
  • Project Settings: CSL styles, export options
  • Database Actions: Purge the PDF vector database or the primary sources (Tropy) database — no rebuild or optimize action exists
  • Per-project Configuration: Independent settings for each project

Accessibility and interface (RC4)

  • Fully translatable into French, English and German — 181 hard-coded strings were removed, including insertion templates that wrote French into your own manuscript
  • Escape closes dialogs, and focus is trapped inside them so Tab cannot wander into the page behind
  • Confirmation dialogs focus Cancel — the destructive button is never the default
  • Interface density: comfortable or compact, in Settings
  • Floating panels share one stacking scale, so opening two no longer hides one behind the other

User Interface

Themes

  • Dark/Light Mode: Toggle between themes
  • Auto Theme: Automatic switching based on time of day
  • Consistent Styling: All components adapt to selected theme

Internationalization

  • Languages: French, English, German
  • Auto-detection: Detects system language on first launch
  • Menu Translations: Complete localization including menus

Technical Features

Vector Database

  • HNSW Index: Fast approximate nearest neighbor search (hnswlib-node)
  • BM25 Index: Sparse search for keywords (natural.js)
  • SQLite Storage: Persistent storage for chunks and metadata
  • Shared Store: PDFs and Tropy primary sources share the same .cliodeck/brain.db (consolidated since before RC2), each with their own HNSW index

Chunking Strategies

Strategy Chunk Size Overlap Use Case
cpuOptimized 300 words 50 Modest machines (8GB RAM)
standard 500 words 75 Balanced performance
large 800 words 100 Maximum precision (16GB+ RAM)

RAG Configuration

Parameter Default Description
topK 10 Number of chunks to retrieve
similarityThreshold 0.12 Minimum score (RRF-optimized)
useHybridSearch true Combine HNSW + BM25
enableQualityFiltering true Filter low-quality chunks
enableDeduplication true Remove duplicate chunks

Configuration

  • Settings Panel: Centralized configuration for all features
  • Per-project Settings: Some settings (like database actions) are project-specific
  • Persistent Storage: Settings saved via Electron Store

For detailed technical documentation, see the numbered guides linked from Home, or FEATURE_SIMILARITY_FINDER.md for the one remaining standalone feature note.

Clone this wiki locally