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.
• Use the command-first quick switcher (Ctrl/Cmd+K or Ctrl/Cmd+P) 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, foldable frontmatter, 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): AI Chat (Ctrl/Cmd+Shift+B, or the Ask AI pill on a selection) with @note / @vault references, attachments and follow-ups; one-click rewrite actions with a diff review; note generation; and repurposing a note into blog/social/newsletter drafts.
• Voice input with an editable preview before insertion (Chromium browsers).

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.

• Tab / Shift+Tab, Enter and the arrow keys move between cells; tabbing or pressing Enter past the last row adds one.
• Column letters and row numbers appear while editing; click them (or right-click a cell) for row, column and table actions: insert, move, delete, align, sort (dates, currency, numbers, text), sum a column, and copy as CSV or JSON.
• Keyboard: Ctrl/Cmd+Enter inserts a row, Ctrl/Cmd+Shift+Backspace deletes it, Alt+↑/↓ moves a row, Ctrl/Cmd+Alt+←/→ moves a column.
• Paste a spreadsheet range or CSV/TSV into a cell to fill cells, adding rows and columns as needed.
• Formulas: start a cell with = — for example =SUM(B2:B5), =AVERAGE(B2:D2), =IF(B2>0, "yes", "no"). Supported functions: SUM, AVERAGE, COUNT, COUNTA, MIN, MAX, ROUND, ABS, IF, AND, OR, NOT, CONCAT. Reference another table in the note by its heading (=SUM(Income!B)) or another note (=[[Budget]]!B5). Amounts such as $2,000 or 1000 RON count as numbers.

Formulas are stored as text (| =SUM(B2:B5) |), so other Markdown apps show the formula rather than the result.

Shortcodes and automation

Type these shortcodes in the editor:

For results that stay beside your working, write the math on its own line instead (see the inline calculator under Markdown writing).

At the start of a line or after a space, type / to insert a link, wikilink, date, task, table, code block, Mermaid diagram, callout, collapsible callout, or frontmatter — plus AI actions when AI is configured.

Autosave can be configured under Settings → Autosave to save after a delay from 0.5 to 10 seconds, on focus changes, or manually only.

Keyboard shortcuts

Development

Requirements: Node.js 22 and Yarn 4 (via Corepack). From the repository root:

cd next-client
corepack enable
yarn install
yarn dev

The development server runs at http://localhost:3000. Available scripts include:

yarn build   # production build
yarn start   # serve the production build
yarn check   # TypeScript check and lint
yarn test    # Vitest (watch mode; add --run for a single pass)

License and security

See SECURITY.md for reporting security issues.