A powerful, entirely local-first browser-based Markdown editor inspired by Obsidian. Built tightly around the File System Access API, it allows users to manage and edit local Markdown files directly within their web browser, maintaining file structures and directories seamlessly. The application operates solely on your local device without any backend or database requirements, ensuring maximum privacy and data ownership. The one optional exception is VaultAgent, a small local helper that runs the AI agent panel (an agent CLI you already use) and the built-in terminal.
- Local Vault Integration: Open a local folder as your "Vault" directly from your machine. Any edits made in the browser are instantly reflected in your local file system, and vice versa.
- Robust Markdown Editing & Live Preview: Powered by CodeMirror 6, the editor hides markdown syntax as you type and seamlessly renders elements such as headings, lists, tables, bold/italic text, and code blocks inline.
- Advanced LaTeX Math Support: Integrated KaTeX rendering allows for both inline mathematical expressions (
$math$) and block equations ($$math$$). - File & Folder Management: Features a built-in file explorer side panel. You can easily create, delete, and rename notes and directories.
- Drag & Drop Organization: Organize your vault effortlessly using contextual drag-and-drop to move files and folders into different directories natively within your file tree. Supported across subfolders and directly to the vault root.
- Integrated Image & Asset Handling: Automatically saves pasted images to a hidden
.Assetsfolder in the same directory as the note, and looks for them nowhere else — so a folder carries its own pictures and stays self-contained wherever it is moved. Delete a picture and its file is retired to that folder's.Garbage(kept if another note in the folder still shows it, and reclaimed on undo). Native rendering of standard images and PDFs directly within the markdown preview. - Pictures Behave Like Pictures: An embedded image is an object, not a piece of syntax — it never turns back into
![[file.png]]under the cursor. Click it while editing to select it, then resize it with the+/−buttons on its corner or remove it with the bin (orBackspace), confirmation and undo included. The file on disk stays plain Markdown throughout. - Tables Behave Like Tables: A rendered table is an object too. Click a cell and type in it — the table never collapses back into pipes and dashes under the cursor.
Tab,Shift + TabandEnterwalk the cells, two+chips at the corners append a row or a column, and right-clicking a cell inserts or deletes rows and columns. Every edit writes back the narrowest change it can, so your alignment colons, your\|escapes and the padding you lined up by hand all survive untouched; the file stays ordinary GFM pipe markdown that Obsidian or GitHub reads the same way. New tables come from a Google-Docs-style matrix picker behind Insert table…, or from simply typing one. - The App's Own Right-Click Menu: Right-clicking a note gives Cut/Copy/Paste/Select all and Insert table…; right-clicking a table cell gives the table's own row and column commands; right-clicking the file tree gives New note, New folder, Rename and Move to Trash, on the row or on the empty space below it. Unavailable rows stay on the menu and say why rather than disappearing. A drawing keeps tldraw's own menu and a PDF keeps the browser's.
- Split-Screen Tabs: Drag any tab out of the strip and drop it onto the page you are reading to put the two side by side in one tab — up to five documents at once, in whatever mix you like (two notes, a note beside a PDF, a whiteboard beside the notes you are taking from it). A purple outline shows which half of the page the tab will take. Every pane is a real editor with its own undo history; a pane's header moves it back to its own tab or closes just that document. Drag the line between two panes to give one of them more room and its neighbour less — only those two move — or double-click that line to even every pane up again.
- Session Persistence: Remembers your open vault, expanded file tree directories, cursor position, last active note, how your tabs were split and how wide you left each pane, and application settings using standard client cache (localStorage).
- Systematic Settings Panel: A native settings modal allows adjustments for editor text width (padding), editor font size, and file tree font size, complete with a "Reset to Defaults" option.
- Theme Support: Clean, intuitive toggle between meticulously designed light and dark themes.
- AI Agent Panel (optional): A chat docked on the right (⌘⇧X) that runs Claude Code, Codex or OpenCode — whichever you have installed and logged in — through VaultAgent, a small background helper (macOS, Windows, Linux). The agent always knows what you are looking at (tabs, panes, the exact lines, page or canvas view), can read, search and edit the open vault and draw on drawings, notebooks and PDFs, and can search the web. It runs with the agent's own full tools on your computer, without permission prompts, and is told to make every vault change through the editor, so each one lands live and undoes with ⌘Z.
- Built-in Terminal (optional): A real terminal docked under the editor (⌃`, or the button beside the agent's), like VS Code's: your own login shell with your profile, PATH, aliases, prompt theme and Nerd Font icons, starting in your home folder, with several tabs, copy/paste and resizing. It runs through the same VaultAgent helper (0.2.0+); on macOS a tiny frozen helper,
vaultagent-pty, owns the shells so the privacy permissions you grant survive VaultAgent updates. The agent never sees it. - Outside Changes, Handled: Files changed by anything else — a
git pull, a formatter, a sync service — reload live in open documents (cursor and scroll kept), and a note with unsaved edits gets a Reload / Keep mine bar instead of being overwritten; whichever version you do not pick is kept asname (conflict).md. Every save checks the file is still the one you opened. The file tree updates live, and.gitis hidden.
The architecture is deliberately chosen to be lightweight and exclusively front-end focused.
- React 19: Functional components, Context API, and Hooks handle complex UI state logic.
- Vite: Next-generation frontend tooling handling rapid Hot Module Replacement (HMR) and optimized build processes.
- CodeMirror 6: An extensible framework providing the foundation for our dynamic text editing experience. It is heavily customized with CodeMirror Lezer extensions and syntax plugins to support real-time "live preview" overlays.
- KaTeX: Efficient and complete mathematical typesetting.
File System Access API Interaction
The lifeblood of the application is the useFileSystem hook which abstracts the experimental browser capability:
- Navigating native folders via Native File/Directory Pickers.
- Saving buffers and reading file streams through OS dialogs.
- Constructing a predictable, reactive file tree model (
fileTreestructure) that maps out nodes and child objects mimicking your actual system.
The Editor Implementation The editor component leverages CodeMirror's state structure to provide split editing paradigms:
- Editor Mode vs Reading Mode: In reading mode, it acts strictly as a static document. In editing mode, active lines show their raw markdown, while inactive text collapses into processed stylings.
- Decorators and Widgets: Utilizing CodeMirror decorators to parse the Lezer syntax tree, selectively hiding tokens and seamlessly injecting CSS styling mimicking standard block elements (indented bullet points, styled quotes, horizontal rules).
- Paste/Drop Listeners: Implemented at the CodeMirror extension level to intercept images natively. It validates the blob, generates unique hash-based filenames, drops it into a sibling-level
.Assetsbucket, and embeds the relative image tag inside the editor cursor position.
Styling Approach
- Vanilla CSS: Entirely reliant on functional raw CSS leveraging root CSS Variables heavily, thus circumventing any preprocessors or bloated utility frameworks. This provides fine-grained control for layout algorithms such as flexbox layouts across the explorer and dynamic responsive padding calculations.
- Design Alignment: Focused deliberately on achieving standard modern note-taking aesthetics, specifically mimicking features found in premium apps like Obsidian.
- Node.js
- A Chromium-based browser or supported variant as full, unrestrained File System Access API is strictly required for application functionality.
- Clone the repository to your local machine.
- Navigate to the project directory:
cd browserMarkdownEditor - Install the required dependencies:
npm install
- Start the development server:
npm run dev
- Open the displayed local link in your browser.
To generate a streamlined, minified set of static assets optimized for standard web hosting environments:
npm run buildThis generates the relevant application bundle dynamically inside the dist/ directory, which can subsequently be deployed to platforms like Vercel, Netlify, or standard Apache/Nginx web servers.
A Bun program, bundled with the dev dependencies:
npm run helper:dev # run it from source; allows http://localhost:* origins
npm run helper:build # compile a standalone binary for this OS into helper/distInstallers are built and published by .github/workflows/vaultagent-release.yml when a vaultagent-v* tag is pushed; the panel downloads them from this repository's latest GitHub Release, and an installed helper (0.1.3+) updates itself from the same release when the user clicks Update in the panel.
To test self-update without publishing, build helpers against a local fake release with bun helper/scripts/build.ts --releases-base http://127.0.0.1:<port>/releases; bun helper/scripts/update-smoke.ts --replace-installed does exactly that end to end. It replaces the helper installed for your user, which the flag acknowledges (CI runs it as CI=true); back yours up first, or reinstall it afterwards.
The macOS PTY host (helper/ptyhost/vaultagent-pty) is a committed, pinned binary that CI never rebuilds — every change to it costs each macOS user one privacy re-grant. Rebuild it only deliberately, with helper/ptyhost/build.sh.
- The underlying architecture heavily depends on browser edge permissions. Users must initially and explicitly grant OS-level prompt access to their chosen folder.
- Deleted items are structured to avoid destructive irreversible permanent OS actions, moving natively to parallel relative
.Garbagecontainer directories.