HermesMarkdown

HermesMarkdown is a local-first Markdown workspace that runs in the browser. It reads and writes a user-selected folder directly through the File System Access API, so your notes remain plain files on your disk. There are no accounts or required cloud uploads.

Architecture

architecture-beta
    group browser(internet)[Browser]
    service workspace(server)[HermesMarkdown Workspace] in browser
    service vault(disk)[Local Markdown Vault] in browser

    group application(cloud)[Next.js Application]
    service web(server)[Next.js Web App] in application
    service ai(server)[AI API Route] in application

    service provider(internet)[AI Provider]

    workspace:R -- L:vault
    web:R -- L:workspace
    web:B -- T:ai
    ai:R -- L:provider

The browser hosts the workspace and accesses the selected local vault. The optional AI route is used only when an AI action is requested and configured.

See next-client/ARCHITECTURE.md for the detailed runtime data flow.

Features

Local-first workspace

• Open an existing folder or create a new vault; create, rename, move, duplicate, and delete Markdown files and folders.
• Browse files in Files, the sidebar's vault tree (Show Files, Ctrl/Cmd+Shift+E; full screen on phones), open them in the editor with tabs, and see every task on the vault-wide Tasks page.
• Be alone with the page: No Distraction Mode (the palette, or Ctrl/Cmd+Alt+Z) hides the sidebar, AI companion, buttons, file name, outline and word count, and the page takes their room.
• Use the command-first quick switcher (Ctrl/Cmd+P or Shift twice) to find files by name, and its prefixes to search tags (#), commands (>), tasks (!), headings in the current note (@), and note text across the vault (/, case-insensitive, all words must match; private notes are never listed). Pin up to five items with Ctrl/Cmd+D.
• External file changes are detected by polling (and immediately when the window regains focus). If both local and external edits exist, a conflict dialog lets you accept the incoming version, keep yours, or resolve them in a merge editor.
• Git stays outside the browser: keep a disk vault in a repository and commit, pull and push with your own tools; .git and tool folders are never listed.
• Works in every modern browser. Chromium-based browsers open folders on disk; Safari (including iPhone and iPad), Firefox, and other browsers use browser vaults stored privately in the browser. Export any vault as a zip, or import a zip, folder, or notes into it, so notes never get stuck in one place.
• Install it as an app (PWA) from any browser that supports installation. The installed app starts offline.

Markdown writing

• CodeMirror 6 source editor with Markdown syntax highlighting, Vim mode, word wrap, line numbers, and slash commands.
• Wikilinks such as [[Note]] and [[Note|Alias]]; type [[ to pick a note and Ctrl/Cmd+Click to navigate.
• Click checkboxes to toggle tasks and click lifecycle tags to cycle their status. Dates and @priority annotations render as pills.
• Fenced code blocks receive syntax highlighting. Mermaid diagrams and display math ($$ … $$ or a ```math fence, rendered with KaTeX) are shown rendered in the editor. Double-click one, or press Ctrl/Cmd+Shift+Enter beside it, to edit its source with a live preview. Mermaid diagrams can also open in a viewer with zoom and SVG download.
• Inline calculator: write rent = 1200, utilities = 180, then rent + utilities, and a faint = 1380 appears at the end of the line. It supports named values, 450 + 15% and 15% of 200. Results are only displayed, and the file keeps just what you typed.
• Optional flow mode (Settings → Editor or the command palette): fades everything but the paragraph you are writing and keeps the current line centered on screen.
• Paste or drop images; they are saved to the vault's assets/ folder and linked.
• Optional AI (bring your own Anthropic or Gemini key, off until you turn it on): a companion panel (Ctrl/Cmd+J, or Ask AI on a selection) with @note / @folder / @vault references, attachments and follow-ups, and rewrite actions on selected text. It reads and edits notes by proposing changes only; you accept or reject each change in a diff before anything is written.

Tasks and metadata

Document lifecycle tags cycle through:

#draft → #review → #active → #archived

Task tags cycle through:

#todo → #prog → #hold → #done

The Tasks page collects checkbox tasks from every note in the vault. Open it from the command palette (Open Tasks) to search task text; filter by due date and one or more custom tags; group by status or note; and sort by due date, priority, status, note, or task text. Click a task to open its source note at that line, or toggle its checkbox to save the change directly back to Markdown.

Use @due(YYYY-MM-DD) for a due date and @priority(high|med|low) for priority. The Tasks page highlights overdue and due-today tasks, and recognizes #prog or [/] as In Progress and #hold as On Hold. Ctrl/Cmd+Enter cycles the status of the task on the current line.

Tables

Pipe tables render as an editable grid: click a cell and type, like a spreadsheet. The file on disk stays a plain Markdown pipe table.

This is the beginning of the README. Read the rest at the original. Read the full README ↗