A local-first notes app: Markdown notes, handwriting with a built-in Xournal++ editor, PDF annotation, a calendar with daily notes, and viewers for PDFs, images and video, all in one folder you own.
Your notes are plain files in a folder on your computer. There is no account, no server and no sync service. Cosmos reads and writes that folder directly, so you can open the same files in any other editor, back them up with any tool, or keep them in git.
Built with Tauri 2, SvelteKit (Svelte 5), CodeMirror 6 and pdf.js.
- Screenshots
- Features
- Keyboard shortcuts
- Where your data lives
- Getting started
- Building the app
- Project layout
- Known limits and roadmap
Handwriting. Open and edit Xournal++ files: pen with pressure, highlighter, shapes, text, selection, page thumbnails.
Blocks inside notes. Text columns side by side, and a live handwriting canvas embedded in a Markdown note.
Command palette. One box for file names, commands and full-text search with snippets.
Calendar. Month, week and day views, a reverse planner, and a daily note for any date.
- Markdown files on disk. Each note is a
.mdfile; there is no database. - Always editable, with live preview. Notes open ready to type, like a notepad. Headings, bold, links, lists, quotes and code render as you type, and the Markdown marks reappear only where your cursor is. Line numbers sit beside the text.
- Wiki links. Type
[[to autocomplete another note. Links to notes that don't exist yet show in red, and clicking one offers to create it. - Backlinks, outline and properties in a right-hand panel: every note that links here (with a snippet), clickable headings, word count, created and modified time, folder and tag count.
- Autosave about 2.5 seconds after you stop typing, plus Ctrl/Cmd+S. Switching tabs saves the note you leave.
- Conflict protection. If another program changes a note while it's open, Cosmos won't overwrite it silently. It asks whether to keep your version.
- Tabs, with a dot on tabs that have unsaved work and a check before closing them. The
+button opens a page with Create note and Go to file. - Templates when creating a note: Blank, Daily and Meeting.
- Formatting shortcuts (bold, italic, link, code block, heading levels) and find and replace.
- External links open in a new window instead of replacing the app, and rendered notes go through a sanitizer, so pasted HTML can't run scripts.
The Add menu above the editor drops a block into the note at the cursor. Blocks stay plain text in the .md file. They can be dragged to another line by their handle, folded, renamed (click the name) and removed.
- Handwriting. A small Xournal++ canvas inside the note, stored as
![[name.xopp]]with the file in a hidden.sketchesfolder beside the note. It has the full editor toolbar plus Grow / Shrink for the drawing area (both undoable). Drawing near the window's edge scrolls the note, so a tall canvas works with just a stylus. - Link existing handwriting note. Shows a
.xoppyou already have, right there in the note. Editing the block edits that file. - Split notes. 2–5 text columns side by side, each a small live-preview editor, stored as a
:::columns … :::| … :::region.
Cosmos opens .xopp files, including ones that annotate a PDF, and edits them.
Viewing
- Pages, pen and highlighter strokes with pressure-varying width, typed text and embedded images.
- Plain, lined, ruled, graph and dotted backgrounds.
- PDF backgrounds drawn under your ink with pdf.js, only for pages near the screen, so big documents stay quick.
- Page navigation, zoom and Fit width. Drag with the Hand tool (or in view mode) to pan.
- Page sidebar with a thumbnail of every page that follows your edits. Add and delete pages from it or by right-clicking a page (Add page before / after, Delete page); both are undoable.
- Typed text in
.xoppfiles is searchable, and[[links]]can point to them.
Editing (press Edit or Ctrl/Cmd+E)
- Pen with stylus pressure, highlighter, and an eraser that removes whole strokes.
- Text tool in Sans, Serif or Monospace. Click to place a box, or click existing text to edit it.
- Selection: lasso, rectangle and single object. Move, resize, recolour, change pen or text size, nudge with the arrow keys, cut, copy, paste (between open files) and delete.
- Shapes: line, rectangle, ellipse, arrow, double arrow and coordinate axes. Shift gives a square or circle. Snapping to a 5 mm grid and to 15° angles can be toggled, and Alt skips it. Rectangles and ellipses can be filled. Shapes are saved as normal Xournal++ strokes.
- Xournal++'s five pen sizes, named colour presets, highlighter presets and unlimited undo/redo.
- Safe saving. Autosave writes a temporary file and renames it into place. The first save of each session keeps a hidden
.name.xopp.bakbackup, and if the file changed on disk (say, in Xournal++) you choose Overwrite or Reload. - Edits change the original XML instead of regenerating it, so anything Cosmos doesn't understand survives a save. Files saved by Cosmos open in Xournal++ 1.3.7.
- The Xournal++ button opens the file in your installed Xournal++ (native or Flatpak) for anything the built-in editor doesn't do.
New handwriting notes. From the sidebar's pen button, the right-click menu, the create-note form or the palette, choose:
- Blank pages: page size (A4, A5, A6), orientation, background, colour and page count.
- Annotate a PDF: uses a PDF already in your vault, one page per PDF page.
- PDFs open in a viewer with page navigation, zoom, Fit width and a thumbnail sidebar. To write on a PDF, use Annotate a PDF.
- Images (
png,jpg,gif,webp,bmp,svg,avif) open with zoom, 100% and Fit width. - Videos (
.mp4,.m4v, H.264) play in the app.
All three are view-only and appear in the sidebar, the notes list and search like any other note.
- Any folder is a vault. On first run you create a new one or open an existing folder. Switch vaults any time from the sidebar footer, Settings or the palette, with no restart.
- Folder tree of any depth, with drag-and-drop moving, inline rename and a filter box.
- Notes list of cards for the current folder, each with a preview, tag and date, plus All / Pinned / Recent filters. Right-click a card to open, rename, pin or delete it.
- Pinned notes float to the top, and a Pinned view shows only them.
- Recent files: the last five notes you opened, in a collapsible section.
- Tags stored as YAML frontmatter (
tags: [physics, wip]). Add and remove them as chips above a note, and click a tag in the sidebar to filter. Other frontmatter is left untouched. - Trash with undo. Deleting moves a note or folder to
.trashwith an Undo button. Restore, permanently delete or empty it from the Trash view.
- Daily notes named
YYYY-MM-DD.md, opened or created from the calendar or the palette (Open today's daily note). Days that have one show a dot. - Month, week and day views, plus a reverse planner for logging what you did each hour.
- Selected-day panel with that day's events, its daily note and the month's totals. Double-click a day for the full day view.
- Events are stored in
.vtfiles in your vault: readable text with the data embedded as JSON.
- Command palette (Ctrl/Cmd+P or K). Empty, it shows recent notes and all commands. Typing searches note names first, then commands, then the full text of every note, with a snippet for each match.
- Full-text index built in the background and kept in memory, including the typed text in handwriting files.
- Commands include new note, folder or handwriting note, Annotate a PDF, daily note, import, export, switch vault, theme toggle and settings.
- Cosmic dark theme, a light theme, and System to follow your OS.
- Accent colour picker that re-tints the whole interface, and a font size slider.
- A slim custom title bar in place of the OS one, with minimize, maximize and close.
- Fonts are bundled (Inter, JetBrains Mono), so the app makes no network requests.
- Responsive layout: on narrow windows the sidebar slides over the content.
- Export the open note as Markdown, standalone HTML, or PDF through the print dialog.
- Import Markdown (
.md,.markdown,.txt),.xopp, PDFs and images from the palette, or by dropping files on the sidebar. Name clashes becomename (1).ext; nothing is overwritten. - Sandboxed file access. Every file operation is checked to be inside the open vault, including symlinks and
..tricks. - Crash-safe saves. A note's new text is written to a temporary copy before the note itself is overwritten.
- No telemetry, no accounts, no network.
| Keys | Action |
|---|---|
| Ctrl/Cmd+P (or K outside the editor) | Command palette |
| Ctrl/Cmd+N | New note |
| Ctrl/Cmd+S | Save |
| Ctrl/Cmd+W | Close tab |
| Ctrl/Cmd+\ | Toggle sidebar |
| Keys | Action |
|---|---|
| Ctrl/Cmd+B / I | Bold / italic |
| Ctrl/Cmd+K | Insert link |
| Ctrl/Cmd+` | Code block |
| Ctrl/Cmd+1 … 6, 0 | Heading level 1–6, remove heading |
| Ctrl/Cmd+F | Find and replace |
[[ |
Wiki-link autocomplete |
Active only while a .xopp file is open, and mostly only in edit mode. The layout follows a custom Xournal++ plugin. Here Ctrl+W deletes the selection instead of closing the tab. The keyboard button in the toolbar shows an on-screen cheat sheet.
| Keys | Action |
|---|---|
| Ctrl/Cmd+E | Toggle edit mode |
| Q | Pen |
| E | Eraser |
| Z | Hand tool (drag to pan) |
| G | Select region (lasso) |
| A | Select rectangle |
| Shift+X | Select object |
| P | Coordinate axes (drag a box) |
| Ctrl+A | Select everything on the page |
| Ctrl+X / C / V | Cut / copy / paste |
| Ctrl+W, Delete | Delete selection |
| Ctrl+Z, Ctrl+Shift+Z | Undo, redo |
| Arrow keys (Shift = 10×) | Nudge selection |
| Esc | Clear selection |
Colour keys switch to the pen first; with something selected they recolour it instead.
| Key | Colour | Key | Colour |
|---|---|---|---|
| W | White #ffffff |
Shift+E | Emerald #81f499 |
| C | Chartreuse #b7f01a |
Shift+B | Bright Lemon #fffa0a |
| R | Red #ff0000 |
X | Electric Rose #f51aa4 |
| T | Tropical Mint #19f0be |
B | Black #000000 |
| H | Hyper Magenta #be19f0 |
Shift+W | White highlighter |
| S | Sky Surge #06bee1 |
Shift+T | Tropical Mint highlighter |
| Y | Saffron #f0be19 |
Shift+D | Bright Lemon highlighter |
| F | Flame Orange #fd5200 |
To change any of these, edit src/lib/xoppshortcuts.ts.
| What | Where |
|---|---|
| Notes and all other files | The folder you chose as your vault |
| Settings, last vault, recent vaults | settings.json in your OS config folder: ~/.config/cosmos/ (Linux), %APPDATA%\cosmos\ (Windows), ~/Library/Application Support/cosmos/ (macOS) |
| Pins, recents, trash list | .vault-meta.vt.md in the vault |
| Deleted items | .trash/ in the vault |
| Handwriting blocks inside notes | .sketches/ next to the note |
| Xournal++ backups | hidden .<name>.xopp.bak next to the file |
| Calendars | .vt files in the vault |
Cosmos hides all of these except your notes and calendars from the sidebar. Coming from an older build that used ~/.config/thevault/settings.json? On first launch Cosmos imports it once and keeps your folder as a known vault. The old file is left alone.
Cosmos also runs in a Chromium-based browser (npm run dev) through the File System Access API. Moving files there needs a recent Chromium, and the Xournal++ button only works in the desktop app.
You need Node.js 18+ and, for the desktop app, Rust and the Tauri prerequisites for your platform. On Debian, Ubuntu or Mint that means libwebkit2gtk-4.1-dev, libgtk-3-dev and related packages.
git clone https://github.com/BigK-Out/cosmosapp.git
cd cosmosapp
npm install
npm run tauri dev # desktop app with hot reloadOther scripts:
npm run dev # browser only (Chromium, File System Access API)
npm run check # type-check Svelte and TypeScript
npm run build # build the frontend only
cd src-tauri && cargo test # backend tests (vault sandbox, settings)npm run tauri build -- --bundles deb,appimage # Linux
npm run tauri build -- --bundles nsis,msi # Windows
npm run tauri build -- --bundles dmg # macOSInstallers go to src-tauri/target/release/bundle/.
- Linux AppImage: the AppImage bundles its own GStreamer plugins so video playback works (
bundleMediaFrameworkintauri.conf.json). This makes the file about 165 MB and needspatchelfon the build machine (sudo apt install patchelforpipx install patchelf). Without the plugins the app crashes when a video opens. The.debuses your system's GStreamer instead. - Windows: you also need the Microsoft C++ Build Tools and WebView2 (already on Windows 10/11).
.github/workflows/release.yml builds all three platforms and attaches the installers to a draft release:
git tag v3.0.0
git push origin v3.0.0Watch the builds in the Actions tab (10–20 minutes the first time). When they finish, open Releases, review the draft and press Publish. Once the workflow is on your default branch you can also start it from Actions → Release → Run workflow.
| Platform | You get |
|---|---|
| Windows | Cosmos_x.y.z_x64-setup.exe and a .msi |
| Linux | a .deb (Debian, Ubuntu, Mint) and a portable .AppImage |
| macOS | a universal .dmg |
The installers aren't code-signed, so Windows SmartScreen and macOS Gatekeeper warn on first launch (Windows: More info → Run anyway; macOS: right-click → Open). Bump version in src-tauri/tauri.conf.json, src-tauri/Cargo.toml and package.json before tagging.
Cosmos is developed and tested on Linux. The Windows and macOS builds use the same code but haven't been tried yet.
src/
routes/ app shell (+layout) and the note view (+page)
lib/
api.ts one API for desktop (Tauri) and browser (File System Access)
opennote.ts the single "open this note in a tab" path
components/ Sidebar, NotesList, Editor, XoppViewer, PdfViewer, ImageViewer,
VideoViewer, Calendar, CommandPalette, Settings, …
xopp.ts .xopp parser, SVG renderer, edit and serialize helpers
newxopp.ts creating .xopp files (blank pages or over a PDF)
livepreview.ts CodeMirror live preview
noteblocks.ts in-note blocks (handwriting, split notes) and their syntax
search.ts in-memory full-text index; backlinks.ts builds on it
vaultmeta.ts pins, recents and trash manifest
vault.ts switching vaults and resetting state
stores/ shared UI and vault state
styles/ CSS (theme tokens live in src/app.css)
src-tauri/
src/main.rs sandboxed file commands, settings, vaults, safe writes
docs/screenshots/ images used in this README
newDesignCosmos/ the original design prototype
Handwriting editor, still to come
- Rotating a selection
- Reordering pages and changing page backgrounds
- Inserting images and LaTeX, and erasing part of a stroke
- Exporting an annotated file to PDF (use the Xournal++ button for now)
General
- PDFs, images and videos are view-only; video is limited to MP4/M4V (H.264)
- The calendar has no recurring events, reminders or external calendar sync
- No built-in sync: keep your vault in any sync tool you already use
- Tested on Linux only; Windows and macOS builds exist but are untried
MIT