Workspace & Files

Cairn stores all data in a single folder you choose. Understanding the layout helps you keep backups, sync across devices, and edit files outside the app.

How the workspace works

On first launch (or via Settings → Workspace → Change Folder), Cairn asks you to pick a root folder. Everything Cairn knows about your projects, notes, and tasks lives inside that folder and nowhere else.

Closing and reopening Cairn with the same folder restores your exact state. Pointing Cairn at a different folder instantly switches workspaces — you can maintain multiple independent workspaces.

File layout

my-workspace/
  cairn.db            ← SQLite database (projects, tasks, settings)
  notes/
    My Project/
      Design spec.md
      Meeting notes.md
    Another Project/
      Roadmap.md

cairn.db — the canonical data store. Board state, task cards, settings, and note metadata all live here.
notes/<Project>/<Title>.md — one file per note, organised into folders by project name. These are secondary representations that stay in sync with the database.

File naming

Note filenames are derived from the note title. Renaming a note inside Cairn renames the file. Characters that are invalid in filenames are replaced with underscores.

YAML frontmatter

Each .md file starts with a YAML frontmatter block that Cairn writes and reads:

---
title: Design spec
project: My Project
created: 2026-01-15T10:32:00Z
updated: 2026-04-10T14:05:22Z
pinned: false
tags: []
---

# Design spec

Your note content starts here...

The frontmatter is maintained automatically. You can read it with any tool that understands YAML frontmatter (Obsidian, VS Code extensions, Pandoc, etc.).

Editing files externally

Cairn watches the notes/ folder for changes. If you edit a .md file in another editor — VS Code, Obsidian, Neovim, anything — Cairn detects the change and syncs it back into the database within a second or two.

This means your notes are genuinely portable. You are never locked in to the Cairn editor.

Reveal in Finder / Explorer

Right-click any note in Cairn → Reveal in Finder (macOS) or Reveal in Explorer (Windows) to open the .md file directly.

Do not edit cairn.db directly

The SQLite database is the source of truth for tasks, projects, and board state. Edit only .md files externally — Cairn does not watch the database for external modifications.

Portability

iCloud Drive

Put your workspace folder inside ~/Library/Mobile Documents/com~apple~CloudDocs/ (or any subfolder within iCloud Drive) to sync across your Macs automatically. Cairn works normally with iCloud — the file watcher handles any on-demand downloads transparently.

Dropbox

Move your workspace folder into your Dropbox folder. Cairn and Dropbox sync the same files from different angles — Cairn writes, Dropbox syncs to cloud and other devices.

Git

Put your workspace folder in a git repository. The .md files version perfectly. Add cairn.db to .gitignore if you only want to version the markdown, or include it if you want full board state versioning (the database is binary, so diffs won't be human-readable).

Backup strategy

Because everything is files on disk, any file backup strategy works:

Time Machine (macOS) backs up the workspace automatically
Dropbox / iCloud provide continuous cloud backup
A daily cp -r my-workspace my-workspace-backup is sufficient for simple use cases
Git gives you a full history of note content

← Getting Started

AI Chat →