Task management,
done right

Download

Folio v1.0 is available for macOS, Windows, and Linux. Pick your platform below.

Notarised and signed on macOS. Requires macOS 12+, Windows 10+, or a recent Linux distribution.

Overview

Folio is built with vanilla JavaScript, HTML, and CSS — no frameworks, no build step. It runs as a native Electron desktop app on macOS, with Automerge CRDT persistence for conflict-free multi-device sync. Designed to be fast, private, and deeply customisable for the way academics work.

The Interface

Folio's interface is split into three resizable panels. You can drag the dividers between them to adjust widths, or double-click a divider to reset it. Your layout preferences are saved automatically.

Sidebar

The left panel contains perspectives (smart views of your tasks) and the folder tree (your organisational hierarchy). Projects and folders can be nested to any depth. Double-click any node to rename it inline. Right-click for a context menu with options to create sub-items, set a header background image, add a note, rename, or delete.

Main Panel

The centre panel displays the task list for the currently selected perspective or project. Tasks show inline metadata — due dates, priority stripes, flag icons, tag chips, subtask counts, and note previews. Nested projects appear as grouped sections with depth-aware typography (tapering font size, weight, and colour with each level).

Inspector

The right panel is a detail editor for the selected task, subtask, or project. It provides fields for title, dates, tags, priority, flag status, notes, attachments, and repeat configuration. For subtasks, a progressive disclosure triangle reveals additional fields. A location breadcrumb at the top shows the path from the project root to the current item. When multiple items are selected, the inspector shows a summary view with chips for each item and a bulk delete button.

Perspectives

Perspectives are smart views that filter and organise your tasks by different criteria. Access the core perspectives from the sidebar or with keyboard shortcuts ⌘ + 1 through 7. Additional perspectives appear in a collapsible section below.

Tasks & Subtasks

Tasks are the core unit of work in Folio. Create a new task with ⌘N or the + Task button — the title appears inline in edit mode, ready to type. Tasks carry a full data model: title, due date, defer date, tags, priority level, flagged status, notes, attachments, and timestamps.

First-Class Subtasks

Subtasks in Folio aren't second-class citizens — they share the exact same data model as tasks, including dates, tags, priority, flag, and notes. Subtasks can nest to arbitrary depth, forming recursive trees of work.

All subtask management happens inline in the main panel. Double-click a subtask to edit its title, press Enter to create a sibling below, or ⇧⌘S to create a child. The inspector shows a dedicated view for the selected subtask with a progressive disclosure triangle for additional fields and a breadcrumb path back to the parent task.

Nesting & Promotion

Use Tab to demote a subtask (nest it under the sibling above) and ShiftTab to promote it up a level. Tab and Shift+Tab also work during inline editing, preserving your cursor position across the re-render. You can also drag subtasks to rearrange, nest, or even promote them to full tasks by dropping them onto a project in the sidebar.

Inline Tab-Flow Editing

When editing a task title inline, press Tab to cycle through metadata fields without leaving the keyboard: Title → Due Date → Defer Date → Flag. ShiftTab cycles in reverse. This enables rapid task triage — type a title, Tab to set a due date, Tab again for a defer date, Tab to toggle the flag, then Enter to commit everything.

Date fields accept natural shorthand: today, tomorrow, 3d, +1w, -2m, fri, eow (end of week), eom (end of month), 12 mar, or full ISO dates. The flag field toggles with Space. All changes are reflected live in the inspector as you make them. Press Escape at any point to revert all changes.

If a defer date is set after the due date, a wavy red underline appears as a visual warning — but the app won't prevent you from doing it.

Completion & Clean Up

Completing a task with incomplete subtasks triggers a confirmation dialog with three options: Complete All, Complete Task Only, or Cancel. Completed tasks remain visible in their project in their original position — they never reorder, so the authored sequence is always preserved (this is what enables meaningful PDF export).

Use ⇧⌘K or the cleanup bar button to Clean Up — this hides completed tasks from the current view with a smooth fade-out animation. Cleaned tasks move to the Completed perspective where they can be permanently deleted with Empty Trash. The Task menu also offers Clean Up Everywhere to stamp all completed tasks globally. Uncompleting a task restores it to its original view.

Multi-Selection

Select multiple tasks and subtasks for bulk operations. ⌘+Click toggles items in and out of the selection, ⇧+Click selects a range of tasks, and ⌘A selects all visible tasks. The inspector shows chips for every selected item with a bulk Delete button. Press ⌘⌫ to delete the selection (with confirmation for 2+ items). Escape clears multi-selection.

Cross-References

Use the Copy Reference button in the inspector or right-click any task, subtask, project, or folder to get a cross-reference link with a folio:// URI. Paste it into any notes field — in either the source editor or the WYSIWYG editor — and it renders as a clickable link that navigates to the referenced item. External links (https://, mailto:, etc.) open in your default browser.

Bidirectional Conversion

Folio supports full bidirectional conversion between projects, tasks, and subtasks — primarily via drag-and-drop. Drag a task or subtask onto a folder in the sidebar (or the root tree area) to promote it to a project — subtasks become tasks. Drag a project from the sidebar onto a task list, project header, or between tasks to demote it to a task — the project's contents recursively flatten into a subtask tree. You can even drag a task onto another task's middle zone to convert it into a subtask, or drag a subtask into empty space to promote it to a top-level task. All fields transfer losslessly in both directions, so round-trip conversions preserve your data exactly.

Organisation

Folio uses a hierarchical structure of folders and projects. Folders are organisational containers; projects hold tasks. Both can nest to any depth, and both carry the enriched data model (dates, tags, priority, flag, notes), so they can be freely converted to tasks and back.

Nested Projects

When you open a project that contains sub-projects, the main panel displays them as grouped sections. Each level has depth-aware typography — font size, weight, and colour taper gradually so you can see the hierarchy at a glance. Sub-project group headers show notes banners and are collapsible.

Project Notes & Headers

Every project has a persistent notes area (the "project dashboard") that appears pinned above the task list. Use it for project-level documentation, meeting notes, or reference material. The notes banner is collapsible — click the sticky note icon (📝) next to the task count in the project header to show or hide it. Notes start hidden by default and auto-reveal when you first add content. Sub-project notes banners in the grouped view have the same toggle.

Projects can have decorative header background images. Right-click a project in the sidebar and choose Set Header Background, or ask the Claude agent with natural language (e.g. "add a mountain sunset background"). Backgrounds are sourced from Unsplash and render as a full-width banner at the top of the project view, with photographer attribution.

Projects in Perspectives

Projects with due dates appear in Today, Upcoming, and Calendar alongside tasks. Flagged projects appear in the Flagged perspective. They render as distinct project cards with an accent icon, title, parent breadcrumb, due date, tag chips, and a task count badge.

Notes & Rich Content

Every task, subtask, and project can carry rich notes with live preview. As you type in the inspector's notes field, the inline preview beneath the item in the main panel updates in real time (debounced at 200ms).

Editor Modes

Folio offers two editor modes, switchable in Preferences → Editor Mode:

• WYSIWYG (default) — A rich text editor with a toolbar for bold, italic, headings, lists, links, and more. LaTeX math renders live as you type and can be edited by clicking. BibTeX citations also render inline and are click-to-edit. Right-click any task, subtask, or project and choose Add Note to create or reveal the notes editor (also available from the Task menu).
• Source — A syntax-highlighted text editor with custom highlighting for LaTeX math and tables. You write using a lightweight formatting syntax and see a rendered preview below. Best for users who want precise control over formatting. You can switch between modes without losing data.

The source editor is powered by CodeMirror 6 (via the <folio-editor> web component with Shadow DOM) and uses Markdown syntax. The WYSIWYG editor uses Tiptap/ProseMirror (via <tiptap-editor>) with custom atom node extensions for inline/block math (MathJax SVG rendering) and BibTeX citations (Biblify rendering). Content is stored as Markdown internally — Tiptap round-trips through @tiptap/markdown.

Both modes support the LaTeX Symbol Reference panel — click any symbol to insert it at your cursor position, whether you're in the main editor or editing a math expression in the WYSIWYG dialog.

Formatting

Notes support rich formatting including headings, bold, italic, code blocks, links, images, and lists. Formatting also works in task titles, project names, subtask labels, sidebar nodes, group headers, and tags — so you can have a tag called $\Sigma$-algebras and it renders the Greek letter.

Notes use Markdown syntax internally, parsed by marked.js with all output sanitised through DOMPurify. Inline rendering uses renderInlineMd() with MathJax typesetting.

Extended Tables

In the source editor, Folio extends standard Markdown tables with advanced features: column spanning, row spanning, multi-row headers, column widths, and — uniquely — headerless tables. All table cells support full inline formatting (bold, italic, code, links, LaTeX math). Tables render with styled borders, alternating row backgrounds, and hover highlights.

Standard Tables

Standard GFM-style tables work as you'd expect — a header row, a separator row with dashes, and body rows. The separator row's colons control alignment:

| Left     | Centre   | Right    |
|:---------|:--------:|---------:|
| Euler    | $e$      | 2.718    |
| Pi       | $\pi$    | 3.14159  |

Headerless Tables

Sometimes you just need a grid of data without headers — grading rubrics, matrices, scheduling grids, quick reference cards. Folio supports two headerless syntaxes:

Pure pipe tables — simply write pipe-delimited rows with no separator line anywhere. Every line must begin and end with |:

| A | B | C |
| D | E | F |
| G | H | I |

Separator-first tables — start with a separator row (no header above it) to get alignment and column widths without a header:

|:---|:---:|---:|
| Left | Centre | Right |
| L    | C      | R     |

Column & Row Spanning

Make a cell span multiple columns by adding extra trailing pipes. Make a cell merge into the row above by placing a caret ^ before the closing pipe. Both work in all three table types:

| H1 | H2 | H3 |
|---|---|---|
| Spans 3 columns |||
| A  | B  | C  |

| Name    | Details  |
|---------|----------|
| Alice  ^| Grade: A |
| (Chair) ^| GPA: 3.9 |
| Bob     | Grade: B |

Multi-Row Headers & Column Widths

Multiple rows before the separator line are all treated as header rows. Set explicit column widths as percentages in the separator row:

| Semester Results ||          Multi-row header with colspan
| Student | Grade  |
|-- 60% --|-- 40% --|         Percentage widths in separator
| Alice   | A      |
| Bob     | B+     |

Quick Reference

Feature              Syntax                  Notes
──────────────────   ──────────────────────  ────────────────────────
Standard table       | H |    (header row)   Header + separator + body
                     |---|    (separator)
                     | D |    (body rows)

Pure pipe table      | D |    (just rows)    Every line starts & ends with |
                     | D |                    No separator needed

Separator-first      |---|    (separator)     Separator first, no header
                     | D |    (body rows)     Supports alignment & widths

Left align           |:---|                   Colon on left
Centre align         |:---:|                  Colons on both sides
Right align          |---:|                   Colon on right

Column span          | spans 2 cols ||       Extra trailing pipes
Row span             | continues ^|           Caret before closing pipe
Column width         |-- 40% --|              Percentage between dashes

LaTeX Mathematics

Write inline math with $...$ and display math with $$...$$. MathJax renders both in notes and in titles — so you can have a task called "Prove $\sum_{n=1}^{\infty} 1/n^2 = \pi^2/6$" and it renders beautifully everywhere.

A custom math protection pipeline (protectMath/restoreMath) shields LaTeX delimiters from the parser's escape processing. All parsing is routed through safeMdParse().

BibTeX Citations

Folio includes a full citation system powered by the Biblify library. Use LaTeX-style citation commands in your notes — \citet{} for textual citations, \citep{} for parenthetical, and \fullcite{} for full references. Citations are rendered inline as formatted references using your chosen CSL template.

The Bibliography panel (⌘⇧B) collects citations from all notes in the current project tree and renders a combined reference list with hanging indents and clickable DOI/URL links. It updates live as you type, using the same 200ms debounce as the notes preview.

Configure your bibliography file path and citation style in Preferences (⌘,). Built-in styles include Chicago author-date, AJP, BJPS, and Philosophy of Science. You can also install custom CSL templates by dragging .csl files into the Preferences modal — they appear as chips that can be renamed (double-click) or deleted.

Mermaid Diagrams

Write mermaid diagram code in your notes and it renders as interactive SVG — flowcharts, sequence diagrams, Gantt charts, and more. Diagrams are theme-aware and switch between dark and light modes automatically.

TikZ Diagrams

Write tikz code in your notes and it compiles to SVG via TikZJax, running a full TeX engine under WebAssembly in the browser. This brings the full power of PGF/TikZ to your task notes — circuit diagrams, commutative diagrams, plots, and more. Diagrams are theme-aware: switching between dark and light mode is instant with no recompilation.

Each diagram is compiled twice — once with dark-mode defaults, once without — producing a dual-SVG pair. CSS toggles visibility of the inactive variant, so theme switching has zero latency. SVGs are auto-trimmed via getBBox() and centred via flexbox.

Syntax Highlighting

Code blocks with a language identifier get full syntax highlighting via highlight.js. The theme follows your dark/light mode preference.

Embedded Content

You can embed videos, Observable notebooks, simulations, and other interactive content directly in your notes using standard HTML <iframe> tags.

DOMPurify is configured to whitelist <iframe> tags with sandbox attribute support. HTML width/height attributes are automatically promoted to inline CSS styles via an afterSanitizeElements hook.

Resizable Previews

Every inline notes preview — on tasks, projects, sub-project groups, and subtasks — has a drag handle at the bottom for resizing. Heights are saved per item and persist across sessions.

Tags & Priority

Tags

Tasks, subtasks, and projects support multiple tags displayed as coloured chips. Colours are auto-assigned from a 15-colour palette based on a name hash, so the same tag always gets the same colour. Add tags in the inspector using the autocomplete input — type to filter existing tags, press Enter or , to add, and Backspace to remove the last tag.

Priority Levels

Set priority via a segmented button group in the inspector. Priority is indicated by a coloured vertical stripe on the left edge of each task row:

Priority stripes fade on completed tasks. In the Calendar view, day badges use the highest priority colour among that day's tasks.

Drag & Drop

Folio uses the native HTML Drag and Drop API throughout the application with a consistent interaction model. Dragging initiates from the task header area (title and meta row) — notes and subtask regions are excluded so embedded media controls remain interactive.

Three-Zone Hit Detection

When dragging over tree nodes, subtasks, and tasks in project views, the drop target is divided into three zones: above (insert before), onto (nest inside, shown with a dashed accent outline), and below (insert after). Perspective views use simpler two-zone detection (above/below) for task reordering. Cycle prevention ensures you can't drop an item inside itself or its descendants.

What You Can Drag

Sidebar nodes can be reordered and reparented within the tree. Tasks can be reordered within a project, dropped onto a different project in the sidebar, or dropped onto another task's middle zone to become a subtask. Subtasks support reordering, nesting (via three-zone detection), and promotion to full tasks by dragging onto a sidebar project or into empty space in the task list.

Project ↔ Task Conversion

Drag-and-drop is the primary way to convert between projects and tasks. Drag a project from the sidebar onto a project header, between tasks, or onto a task to convert it to a task (or subtask) — the project's hierarchy is recursively flattened into a subtask tree. Drag a task or subtask onto a folder in the sidebar (or the root tree area) to convert it to a project — subtasks are promoted to tasks. All fields (dates, tags, priority, flag, notes, actions, attachments) transfer losslessly in both directions.

File Drops

File drops are routed intelligently based on the drop target. Files dropped on the Claude panel are staged for the agent. Files dropped on a notes editor are embedded as resources. Files dropped on a CSL drop zone in Preferences install custom citation styles. Files dropped elsewhere on a task become standard attachments.

Search

A permanently visible search bar sits in the main header. Press ⌘K to focus it instantly. Search covers task titles, notes content, tags, subtask titles (via recursive tree walk), and project names.

Multiple search terms use AND logic — all terms must match. Results are relevance-scored and displayed with project context tags and match-location badges (e.g. "title", "notes", "tag"). Navigate results with ↑↓ arrow keys and press Enter to jump to the matching task's project. Escape clears the search and restores your previous view.

Repeating Tasks

Tasks that recur on a schedule can be set up to regenerate automatically when completed. When you check off a repeating task, Folio marks it as done and creates a fresh copy with the next due date.

Folio uses a clone-on-complete model with fixed-schedule date computation (the next due date is calculated from the original due date, not from the completion date). Subtasks are deep-cloned with checkboxes reset. If the task had a defer date, the offset between due and defer dates is preserved.

Setting Up a Repeat

In the inspector, the Repeat section appears between Priority and Subtasks. Click Set repeat… to open the configuration modal. Choose a frequency, interval, and optional end condition.

Weekday Selection

When the frequency is set to Weekly, a row of day-toggle buttons appears (Mon–Sun). Select any combination of days. The next due date always advances to the nearest matching day, cycling to the next week when all selected days have passed.

End Conditions

By default, a repeat runs forever. You can limit it in three ways:

How Completion Works

When you check off a repeating task, Folio marks the current instance as completed and creates a clone with the next due date. The clone inherits everything: title, project, notes, tags, priority, flag, and the repeat rule itself. Subtasks are cloned with their checkboxes reset.

Date computation uses the original due date (fixed schedule, not from completion date). The defer date offset between due and defer dates is preserved. The occurrence counter, if set, is decremented on each clone. computeNextRepeatDate() and cloneSubtaskTree() handle the arithmetic and deep cloning respectively.

Attachments

Tasks, subtasks, and projects can have file attachments. Drag files onto a task row or use the inspector's attachment section to add them. Folio copies files into a content-addressed store in the app data directory, preserving original filenames.

File Attachments

Attachments appear as chips in the inspector with the filename and a remove button. Click an attachment to open it with your default application. Attachments are preserved when duplicating tasks or spawning repeating task clones. For projects and folders, attachments also appear as clickable chips in the main panel header, below the action buttons.

Embedded Resources

Drop files onto the notes editor to embed them inline. Images render directly in the notes preview. Other file types appear as clickable links.

Resources use folio-resource:// URIs as a portable abstraction layer in the note source. At render time, URIs are resolved to file:// paths via a pre-populated _resourcePathCache map. Resources are stored in content-addressed storage alongside attachments.

Actions

Actions turn Folio from a passive task list into an active environment launchpad. Attach launch operations to any task, subtask, or project — open files, folders, terminals, URLs, or run shell commands with a single click.

Action Types

Five action types are available:

Open File — opens a file in its default application, or in a specific app you choose from a searchable dropdown with icons. Open Folder — opens a directory in Finder. Open Terminal — opens a terminal emulator at the specified directory; you can choose which terminal app to use (Terminal, iTerm, Warp, etc.) from a filtered dropdown, with an "Other…" option to pick any installed application. Open URL — opens a web address in your default browser. Run Script — opens a full syntax-highlighted script editor (powered by CodeMirror 6) with a language picker supporting 17 languages, a working directory field, and fire-and-forget execution. Scripts use standard hashbang syntax (#!/bin/bash, #!/usr/bin/env python3, etc.) to select the interpreter.

Using Actions

Actions appear as launch buttons in four places: on the task row (between the title and the flag icon), on subtask rows (after the meta indicators), in the project header (below the subtitle), and in the inspector's Actions section. Click any button to launch the action immediately.

To add or edit actions, click the gear icon in the inspector's Actions section, or click "Add actions…" if none exist yet. The action editor lets you add actions, set their type, and enter paths, URLs, or shell commands. Paths support ~/ shorthand for your home directory. File and folder path fields have a browse button that opens a native file picker.

Subtasks have full action and attachment support — both sections appear inside the "More options" disclosure in the subtask inspector, after Priority/Flag and before Notes.

Action Groups

For tasks with multiple actions, you can organise them into named groups — for example, a "Writing" group that opens your manuscript, bibliography, and a terminal, or a "Review" group that opens the PDF and reference materials. When groups exist, each enabled group becomes a single launch button that opens everything in the group at once.

Individual actions can belong to multiple groups. Groups can be enabled or disabled, and the button bar updates to show only enabled groups.

Quick Entry

A system-wide floating window for capturing tasks without switching to the main Folio window. Activated via ⌃⌘N (works even when Folio isn't in the foreground), the Quick Entry panel provides fields for task title, project assignment (with a dropdown of all projects), due date, and flag status. Press Enter to save the task to the selected project (or Inbox) and dismiss the panel. Press Escape to cancel.

Export to PDF

Export the current project view as a formatted PDF document via File → Export to PDF… (⌘⇧P). The export walks the entire project tree — including sub-projects, tasks, and subtasks — in the same order as the main panel, producing a print-ready document.

What's Included

The PDF renders project and sub-project titles as hierarchical headings, task and subtask titles with checkbox indicators (☑/☐) and strikethrough for completed items, due and defer dates, priority badges (colour-coded), flagged status, tags, and fully rendered notes including:

• LaTeX equations — typeset via MathJax (both inline and display math)
• TikZ diagrams — compiled to SVG via TikZJax (WebAssembly)
• Mermaid diagrams — flowcharts, sequence diagrams, Gantt charts, etc.
• BibTeX citations — \citet{}, \citep{}, \fullcite{} resolved inline, with a formatted bibliography appended at the end
• Code blocks — with syntax highlighting

Subtask trees are rendered recursively with indented borders.

What's Excluded

Actions, attachments, and embedded resources are not included in the PDF export — the output focuses on the intellectual content of the project.

Claude Agent

Folio includes a deeply integrated AI assistant — not a bolted-on chatbot, but an agent that can read, create, modify, and organise your tasks, projects, and folders through natural language. Toggle the Claude panel from the header bar or press ⌘⇧C.

How It Works

When you send a message, Claude sees your current view context — which project or perspective you're looking at, your full project tree, and task counts — so it can make informed decisions without you needing to spell everything out.

Responses stream in real time with an animated sparkle icon during thinking and a blinking cursor during text output. When Claude uses tools, a "Working…" indicator appears, followed by green confirmation lines describing each action taken.

Claude operates through the Anthropic Messages API, streamed via the Electron main process to keep your API key secure and out of the renderer. Tool execution is sorted by dependency order (read → folders → projects → tasks → updates → deletes → navigation) and yields to the browser event loop before execution for paint. Smart model routing sends creative/analytical tasks to Opus and routine CRUD to Sonnet.

What Claude Can Do

Claude has a comprehensive tool set covering the entire Folio data model:

Claude can also manage tags and subtasks on existing tasks, and set Unsplash header backgrounds on projects using natural language photo searches (e.g. "add a mountain sunset background to my dissertation project").

Example Conversation

Drag-and-Drop Files

Drag files directly onto the Claude panel to stage them for task creation. ZIP archives are automatically extracted — their contents appear as collapsed chips above the input showing the archive name, file count, and total size. Individual files appear as separate chips. Once staged, tell Claude what to do with them and it will attach them to the tasks it creates.

Academic Workflow

Claude's system prompt includes guidelines for academic work. When creating tasks, it will format notes with LaTeX where appropriate, include DOI links for references, and maintain citation honesty. It understands the structure of research workflows — literature reviews, drafting, revision cycles — and can scaffold project hierarchies accordingly.

Configuration

Claude requires an Anthropic API key, which you can set via the panel footer. The key is stored securely by the Electron main process and never exposed to the renderer. If you want Unsplash header background support, a separate Unsplash API key can be configured in the same area.

Keyboard Shortcuts

All shortcuts are context-aware and suppressed when text inputs are focused (except Esc, ⌘N, and ⇧⌘S). During inline task editing, Tab and ShiftTab cycle through metadata fields instead of their usual subtask nesting behaviour.

During Inline Task Editing

Design Principles

Folio is guided by a set of principles that shape every design and engineering decision.

Roadmap

Folio's development follows a structured five-phase plan, progressing from visual polish through full desktop integration and mobile support.