Skip to content
ragtuxPublic

About

Scoria is an ambitious Obsidian clone. Built with rust + GPUI (ZED). Designed to open Obsidian vaults unchanged: same folder, .obsidian config, Markdown, canvas and bases.

Topics

Resources

Security policy

Stars

37 stars

Watchers

1 watching

Forks

Repository files navigation

Scoria

Your vault, opened natively.

100% Rust Linux, Windows, macOS MIT licensed Early alpha, v0.7.0 CI

Status · The window · Reading · Canvas and graph · Search · Writing · Compatibility · Roadmap · Releases · Manual

Scoria is a native knowledge base written in Rust on GPUI, built to open Obsidian vaults unchanged: same folder, same .obsidian configuration, same Markdown dialect, same .canvas and .base files. There is no import step, no conversion and no second copy of anything. It is an independent implementation and is not affiliated with Obsidian.

The Scoria window on the scoria-demo vault, on macOS: the Files pane on the left, two notes split side by side in the middle — one with a callout and a typeset equation, the other with an embedded glossary block and a table — and the Backlinks pane on the right, all inside a frameless window on a desktop wallpaper.

The shell on docs/scoria-demo, a small field guide to scoria and the volcanic rocks around it that ships with the repository for exactly this purpose: two notes split side by side, a callout, an equation typeset from TeX, a block embedded from another note, a table, and the note's backlinks. Obsidian's hidden window frame, its palette, its type scale and its Lucide icons, all read off a running copy rather than guessed at.

Status

Reader done, Writer done: the vault round-tripped byte-identical through a week of mixed use in both apps, closed 9 November 2026. scoria-markdown parses CommonMark (all 652 spec examples), the GitHub extensions Obsidian uses, and Obsidian's own syntax into one tree with byte spans, and renders it to reading-view HTML that matches Obsidian 1.13.7 on 1008 of 1009 corpus notes; the metadata cache, the editor and the link rewriter are all built from that tree. The application opens a real vault with the three-pane shell: a Files view with Obsidian's header, its six sort orders and its keyboard; reading view; Backlinks, Outgoing links, Tags, All properties and Outline, each with its own sort, folds and filter kept in workspace.json; Search with its sort control and the Copy search results modal; the quick switcher, the graph, the command palette and a Settings window that writes. Notes open in Live Preview or Source mode with find and replace, multiple cursors, auto-pairing and autosave; [[, ![[ and # autocomplete against the vault's files, aliases, headings, tags and block references; Obsidian's sixteen table commands add, move and align rows and columns, tables are edited cell by cell and their rows and columns drag by Obsidian's handles; new note, rename, move, copy and delete rewrite links the way Obsidian does, and frontmatter is an editable, typed properties table that rewrites only the lines it changes. A .canvas opens in a canvas view that pans, zooms, selects, moves, resizes, draws edges, groups and undoes, and autosaves in Obsidian's bytes. A .pdf opens in a viewer with Obsidian's toolbar, sidebar and find bar, and ![[x.pdf]] embeds and canvas file cards draw the same viewer. $x$ and $$x$$ are typeset with a KaTeX-compatible engine in Rust and painted in the text's own colour, inline in reading view and Live Preview and as centred blocks. The main area splits into tab groups (Split right, Split down, draggable dividers, the focus commands) and workspace.json records the tree the way Obsidian does, and the Bookmarks pane reads and writes bookmarks.json in Obsidian's bytes. Phase 4 has added the core plugins around that core: bases in four layouts, Mermaid, page preview, popout windows, Slash commands, spellcheck, paste and drop, the Note composer, Workspaces, File recovery, Excluded files and the rest, each probed against Obsidian 1.15 first. Everything is bound through Obsidian's command ids, so a vault's hotkeys.json applies unchanged.

Keep a backup of any vault you open with it. Reading a vault is well covered; editing is newer code against files you cannot get back. The round-trip gate was met on one vault over one week; that is evidence, not a guarantee.

The window

The window has no desktop title bar: it draws Obsidian's hidden frame itself — the sidebar toggles, the dock tab headers, the tab strip and the window buttons all live in one 40 px row, and the empty parts of that row drag, zoom and menu the window. --frame native asks the desktop for its own frame instead. The palette, the type scale, the 40 px headers, the 44 px ribbon and the 300 px sidebars are the values Obsidian computes for its own shell, read over CDP from a running copy and written down in the specification; the icons are Lucide's own drawings, which is what Obsidian names in its DOM.

Reading a vault

Scrolling a note in reading view past a table, a code block, a callout and a task list, expanding a folder in the Files pane, opening a note with an embedded photograph, then opening the Outline pane and jumping to a heading from it.

Reading view on the vault's home note — a table, a code block, a callout, tasks — then a folder expanded in the Files pane, a rock's note with its photograph and an embedded glossary entry, and the Outline pane jumping to a heading.

Images, diagrams, canvas and graph

Notes with embedded photographs and SVG charts, an image file opened in its own tab, a canvas zoomed in from the whole diagram to its text cards, note embeds and image nodes joined by labelled edges, then the graph view settling.

Photographs and SVG charts embedded with ![[file|width]], an image opened as its own tab, a .canvas file with text cards, note cards and image nodes joined by labelled edges, and the graph view laying the vault out.

Search, the switcher and the panes

The quick switcher matching a note as its name is typed, then the Search pane filling with grouped, highlighted results as a query is typed, a result opening at its match, then the Tags and Backlinks panes.

The quick switcher's fuzzy match, Search grouping hits by note with every match highlighted and opening one at its line, the Tags pane with nested tags and counts, and a note's Backlinks.

Writing, tabs and splits

Typing a task at the end of a note in Live Preview, two square brackets opening the completion popup which narrows as letters are typed, the accepted link written, find highlighting a word, then Split right and a second note opened beside the first.

Live Preview: [[ completes against the vault's files, aliases, headings, tags and block references and the accepted row writes the link; find highlights every hit; then Split right and a second note beside the first. The tab-group tree is written back to workspace.json in the shape Obsidian writes.

The Search pane with the query 'vesicularity', showing results grouped by note with the matches highlighted.

Search takes Obsidian's query grammar, groups hits by note with a count, and highlights every match in context.

Typing two square brackets in Live Preview opens a completion popup listing matching notes.

The completion popup as [[ opens it, listing the vault's notes, images and diagrams before a letter narrows it.

Running it

cargo run --release -p scoria -- "C:\path\to\your\vault"
cargo run --release -p scoria -- docs/scoria --synthetic 50000 --stress   # editor spike with a report
cargo run --release -p scoria -- "/path/to/vault" --control /run/user/1000/scoria.sock
cargo run --release -p scoria -- "/path/to/vault" --frame native   # the desktop's own title bar instead of Scoria's hidden frame
cargo test --workspace

The argument is a vault folder, a file inside one (scoria Rocks/Basalt.md opens the vault above it and then the note), or an obsidian:// URI; with none at all Scoria opens the vault manager. scoria --help prints every flag. One vault means one window: a second scoria on a vault that is already open hands it the note, file or URI and raises that window instead of starting again, which is what makes scoria ~/notes Basalt a "go to this note" command from a terminal. tools/linux-desktop/install.sh puts Scoria in the desktop's menu and gives it the folder, Markdown and scoria:// associations.

--control exposes the running app on a Unix socket (on Windows too) speaking newline-delimited JSON: open a note, run a command id, send keystrokes or clicks, and read back a dump of the window's whole state. scoria-mcp wraps that protocol as a Model Context Protocol server over stdio, so an agent can launch Scoria, drive it and screenshot it. The recordings above were made that way: tools/readme-recording drives the app over the socket inside a headless Wayland session whose background is the desktop wallpaper, captures each step, and assembles the GIFs. Both are described in docs/scoria/Development.md.

Compatibility tiers

Tier Goal Plan
1 Vault and format compatibility (no conversion, no data loss) In scope, first
2 Core feature parity with Obsidian's app and the 29 core plugins its Core plugins tab lists In scope
3 Theme compatibility Variable-level subset of the 1047 CSS custom properties
4 Community plugin compatibility New native plugin API; existing JS plugins are out of scope

The full functional specification this project implements, derived from observing Obsidian 1.12.7's behavior, file formats, and public documentation, lives in the docs/scoria vault and is published at scoria.cc, whose site is built from site/ in this repository.

Crates

Crate Responsibility
scoria GPUI application: window, workspace shell, views
scoria-cli The command line: flags and help, the file and URI arguments, the one-window-per-vault handover (no gpui)
scoria-vault A vault is a folder: scanning, file kinds, .obsidian config reads
scoria-markdown Obsidian Flavored Markdown: CommonMark + GFM + Obsidian syntax parsed into one spanned tree, HTML renderer
scoria-cache Metadata cache (CachedMetadata) and link resolution with Obsidian's rules
scoria-formats On-disk formats: file kinds, app.json and friends, JSON Canvas 1.0, Bases YAML
scoria-commands The 244 command ids and default hotkeys so vault hotkeys.json applies unchanged
scoria-search Obsidian's search query language, file matching, fuzzy search, and Excluded files
scoria-text The editor's text model: buffer, selections, undo, the editing commands' edit plans, Vim keys
scoria-suggest Autocompletion: what a line triggers, what the vault offers, and the link accepting one writes
scoria-templates Template placeholders and the moment.js date formats they take
scoria-composer The Note composer: the bytes a merge and an extraction write, their links and their template
scoria-canvas The canvas model: viewport math, edge geometry, hit tests, selection, edits with undo, the embed's minimap
scoria-bases The Bases expression language, parsed into Obsidian's own tree, and the table's cell ranges
scoria-pdf PDF rendering on hayro: pages, the outline, page text, the #page= subpath
scoria-math TeX typeset on RaTeX (KaTeX-compatible) into a drawing list, with the KaTeX fonts
scoria-mermaid Mermaid diagrams laid out as Obsidian's Pele lays them out, through limu
scoria-highlight Code highlighting: Prism's tokenizer and grammars, ported
scoria-export Export to PDF (krilla) and Export as image (tiny-skia)
scoria-audio The Audio recorder (AAC .m4a) and the audio player, and what a video file holds
scoria-paste What a paste or a drop writes: copied HTML as Markdown, attachment names
scoria-spell Spellcheck: Hunspell dictionaries on spellbook, the words checked, the custom dictionary
scoria-control The control socket's protocol and a client, for driving the running app
scoria-mcp An MCP server that launches Scoria and drives it over the control socket
scoria-llm-mcp An MCP server in front of a local model, for bulk text work
scoria-bench Spike benchmarks: synthetic vault generator, index timer

Roadmap

Phase Gate Status
1. Spike 50k-line editor, parser conformance corpus, 2 s vault index Done
2. Reader A daily user browses their real vault with no missing content Done: Files, reading view, Backlinks, Outgoing links, Outline, Tags, Search, quick switcher, graph, command palette, the Settings window, file watching
3. Writer The vault round-trips byte-identical after a week of mixed use in both apps Done, 9 November 2026: seven days of mixed use on a real vault, every changed byte attributed to a person's edit in one of the two apps (docs/scoria/Writer gate run.md). Source mode, Live Preview, find and replace, file operations with link rewriting, properties, autocompletion, table editing with handles, block references, templates, daily notes, tab groups, bookmarks, the round-trip harness, every Settings control Obsidian offers, and the editing commands; file recovery is out of phase 3
4. Parity Core plugin parity Under way, every row of its table done, and the gate — a vault's core plugins behaving as Obsidian's do — still to be run on a real vault: the canvas view and the canvas writer, and a .base parsed, written back, evaluated — its expression language held to 277 of Obsidian's parse trees and 1044 of its answers — and opened in all four of its layouts with its toolbar, panels, editable cells, cell ranges and live embeds; a .pdf in a viewer, embedded, selectable and in spreads; $x$ and $$x$$ typeset (KaTeX's syntax, where Obsidian's MathJax takes more); Mermaid diagrams laid out as Obsidian's Pele lays them out; a vault's CSS theme and snippets loaded and picked in the Appearance tab, with its font pages, and fenced code highlighted from Prism's own grammars in 85 languages; obsidian:// URIs, the command line and the desktop entry; popout windows; page preview; Slash commands; spellcheck; paste and drop; canvas embeds and the audio player; line numbers, indentation guides and right-to-left text; Excluded files; and, each to a probe of Obsidian 1.15, the Note composer, Workspaces, the Unique note creator, Random note, the Footnotes view, backlinks in the document, rename heading, add alias, an editable File properties pane, File recovery, and the app's own toggles. 210 of the 244 command ids run; the 34 left are services Scoria does not have (Sync, Publish, the Web viewer) and ids Obsidian does not register on desktop
5. Ecosystem Native plugin SDK Designed and spiked: WebAssembly components on wasmtime with a WIT world of Scoria's own, Cranelift behind a plugins feature, measured on Linux and Windows 16 November 2026 (docs/scoria/Plugin SDK.md, tools/plugin-spike); the host crate is next

Progress notes, gates and the per-item status live in docs/scoria/Development.md.

Releases

Pushing a v* tag builds the scoria binary on both forges and attaches the archives with a SHA256SUMS file:

Each release carries every archive twice: once named for its tag, and once under a name with no version in it, which is the address that always resolves to the newest release and the one scoria.cc links:

  • https://github.com/ragtux/scoria/releases/latest/download/scoria-linux-x86_64.tar.gz
  • https://github.com/ragtux/scoria/releases/latest/download/scoria-windows-x86_64.zip
  • https://github.com/ragtux/scoria/releases/latest/download/scoria-macos-aarch64.tar.gz

There is no installer: unpack the archive and run scoria /path/to/vault. Linux x86_64 is the build that runs on the reference machine and gets the hours; since 0.3.1 the Windows and macOS builds are run on real hardware too, each drawing its own platform's window — the hidden frame on Windows 11, the traffic lights and the platform text system on Apple silicon. Nothing is code-signed for macOS or Windows — see docs/scoria/Development.md.

Verify a download: sha256sum -c --ignore-missing SHA256SUMS checks the archive against the checksums the workflow wrote; gh attestation verify <archive> --repo ragtux/scoria checks GitHub's build provenance, which ties the archive to the workflow run and the commit it was built from. When a release carries SHA256SUMS.asc, gpg --verify SHA256SUMS.asc SHA256SUMS checks the maintainer's signature. That key is 69BF AA44 7DAC E6C3 EF02 6CBA 4EA6 7A61 88DA 92BD, ragtux <ragtux@outlook.com>, which gpg --keyserver keys.openpgp.org --recv-keys 4EA67A6188DA92BD fetches; the release notes repeat the fingerprint that signed each release. Security problems go through SECURITY.md, not the issue tracker.

License

MIT. See LICENSE.

About

Scoria is an ambitious Obsidian clone. Built with rust + GPUI (ZED). Designed to open Obsidian vaults unchanged: same folder, .obsidian config, Markdown, canvas and bases.

Topics

Resources

Security policy

Stars

37 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages