← All repositories

refactoringhqtolaria

7,520
0
View on GitHub
7,520 stars522 forksTypeScriptAGPL-3.0Updated 3h ago1viewtolaria.md

Tolaria

Tolaria is a desktop application for macOS and Linux that stores your notes as plain .md files in a local Git repository. Every vault follows a structured knowledge ontology — Projects, Responsibilities, Procedures, People, Topics, Events, and Notes — so AI agents have a traversable graph rather than a flat pile of text. The editor combines a BlockNote rich-text surface (wikilinks, math via KaTeX, diagrams via Mermaid) with a CodeMirror 6 raw mode, and an Inspector panel exposes YAML frontmatter fields inline.

Built on Tauri v2, it ships a built-in MCP server with 14 tools over stdio (port 9710) and WebSocket (port 9711), so Claude Code, Cursor, Codex, and any MCP-compatible client can read and write vault entries without additional setup. An in-app AI panel spawns these agents as subprocesses and wires them to the local MCP server automatically.

Features

  • Structured knowledge ontology — seven entity types (Project, Responsibility, Procedure, Note, Topic, Event, Person) defined by YAML frontmatter type field; semantic fields per type (status, priority, tags, related)
  • BlockNote rich-text editor — custom wikilink inline content, KaTeX math blocks, Mermaid diagrams, code blocks via @blocknote/code-block
  • CodeMirror 6 raw mode — full markdown and YAML editing with syntax highlighting
  • Wikilink navigation — [[Note Name]] cross-links between entries; Neighborhood mode shows the link graph around the current entry
  • Git-backed sync — every vault is a Git repo; push/pull to any remote; AutoGit creates automatic checkpoints on save; Pulse view shows commit activity feed
  • Incremental vault cache — Rust backend rescans only files changed since the last known Git commit; handles 10 000+ note vaults without slow startup
  • MCP server (14 tools) — list, search, read, create, and update vault entries over stdio and WebSocket transports; lifecycle managed from inside the app
  • AI agent panel — spawns Claude Code, Codex, OpenCode, or Pi as subprocess agents with vault MCP access
  • Four-panel layout — Sidebar (vault tree), NoteList (filtered entries), Editor (flex), Inspector (frontmatter + backlinks)
  • Inbox Zero workflow — capture everything as Notes, then promote to typed entities
  • Full-text search — across all vault entries with type and tag filters
  • In-app updates — Tauri updater plugin delivers releases without leaving the app
  • Opt-in telemetry — Sentry (errors) + PostHog (usage analytics), disabled by default
  • AGPL-3.0 — fully open source

Documentation

Quick start

# End users: download the latest release
# macOS → .dmg   Linux → .tar.gz AppImage
# https://github.com/refactoringhq/tolaria/releases

# Local development
git clone https://github.com/refactoringhq/tolaria
pnpm install
pnpm tauri dev
# Prerequisites: Node.js 22+, pnpm 10+, Rust 1.87+, Tauri CLI v2

Tags

Maturity
BetaBetaActively developed but pre-1.0 — no stable release tagged yet.View all repositories tagged
Release pattern
TightTightFrequent releases with short gaps — max release gap under 30 days.View all repositories tagged
Persona
Frontend engineerFrontend engineerEngineers building React, Vue, or other browser-side UIs and dashboards.View all repositories taggedKnowledge workerKnowledge workerProfessionals who manage and produce knowledge as their primary work — researchers, writers, consultants, independent professionals.View all repositories tagged
License Category
CopyleftCopyleftCopyleft license requiring source sharing when the software is offered as a service.View all repositories tagged
Built With
CodeMirrorCodeMirrorExtensible code and text editor component library for the web (version 6).View all repositories taggedTailwind CSSTailwind CSSComponent styling written with Tailwind CSS utility classes.View all repositories taggedshadcn/uishadcn/uiDistributed as a shadcn/ui-compatible component registry — installed via the shadcn CLI.View all repositories taggedBlockNoteBlockNoteBlock-based rich-text editor library for React with extensible block types.View all repositories taggedRustRustSystems programming language used for CubeAPI, CubeHypervisor, and CubeShim components.View all repositories taggedRadix UIRadix UIUses Radix UI primitives (dialog, popover, tooltip, etc.) for accessible interaction surfaces.View all repositories taggedReactReactJavaScript UI library for building component-based user interfaces.View all repositories taggedTypeScriptTypeScriptStatically typed superset of JavaScript used for the frontend codebase.View all repositories taggedTauriTauriDesktop application framework using Rust backend and system WebView for cross-platform native apps.View all repositories taggedViteViteNext-generation frontend build tool with instant HMR and optimised bundling.View all repositories tagged
Security Posture
UnratedUnratedOSSF Scorecard has not yet scanned this repository — security posture is unknown.View all repositories tagged
Maintainer Model
Single-personSingle-personMaintained primarily by one developer — top contributor accounts for most commits.View all repositories tagged
Form Factor
ApplicationApplicationA complete standalone application, not a library or framework.View all repositories tagged
Platform
DesktopDesktopRuns as a native desktop application on macOS and Linux.View all repositories tagged
Issue load
Well-resourcedWell-resourcedVery low ratio of open issues to stars, indicating active issue management.View all repositories tagged
Use case
Rich-text markdown editing with wikilinks and diagramsRich-text markdown editing with wikilinks and diagramsWhen I write technical documentation in my vault, I want wikilinks, KaTeX math, and Mermaid diagrams in the same editor so I can produce structured, cross-linked notes without switching tools.View all repositories taggedOpen-source Obsidian alternative with structured ontologyOpen-source Obsidian alternative with structured ontologyWhen I want to move away from Obsidian's proprietary sync and plugin ecosystem, I want an open-source alternative with a convention-driven ontology so I can maintain a structured vault on my own terms.View all repositories taggedAI agent access to a markdown vaultAI agent access to a markdown vaultWhen I want an AI coding agent to understand the context in my notes, I want a local MCP server that exposes my vault so I can ask Claude Code questions that draw on my project notes and procedures.View all repositories taggedOffline-first local note takingOffline-first local note takingWhen I need to take notes without an internet connection or cloud account, I want a local-first desktop app so I can keep my knowledge base private and available everywhere.View all repositories taggedStructured personal knowledge managementStructured personal knowledge managementWhen I have thousands of unstructured markdown notes, I want to apply a typed ontology (Projects, People, Procedures) so I can navigate my vault semantically rather than by keyword search alone.View all repositories taggedIn-app AI agent panel for vault-aware codingIn-app AI agent panel for vault-aware codingWhen I want to use an AI coding agent that has context about my projects and procedures, I want to spawn Claude Code from inside my notes app so I can consult my vault without me copying and pasting context.View all repositories taggedGit-backed note sync across machinesGit-backed note sync across machinesWhen I work on multiple machines, I want my notes stored in a Git repo I control so I can sync via GitHub without a third-party sync subscription.View all repositories tagged
Ecosystem
JavaScriptJavaScriptBuilt with JavaScript, runs in the browser or any JS runtime.View all repositories tagged
Status
ActiveActiveReceives recent commits and releases, issues are being addressed.View all repositories tagged
Features
Wikilink navigationWikilink navigation[[Note Name]] cross-links between vault entries; Neighborhood mode shows the link graph.View all repositories taggedIn-app automatic updatesIn-app automatic updatesTauri updater plugin delivers new releases without requiring manual downloads.View all repositories taggedAI agent panelAI agent panelSpawn Claude Code, Codex, OpenCode, or Pi as a subprocess with vault MCP access.View all repositories taggedGit sync with AutoGit checkpointsGit sync with AutoGit checkpointsAutomatic Git commits on save plus manual push/pull sync; Pulse view shows commit feed.View all repositories taggedVault full-text searchVault full-text searchFull-text search across all vault entries with type and tag filters.View all repositories taggedStructured knowledge ontologyStructured knowledge ontologySeven entity types (Project, Responsibility, Procedure, Note, Topic, Event, Person) enforced via YAML frontmatter.View all repositories taggedCodeMirror 6 raw editor modeCodeMirror 6 raw editor modeSwitch to raw markdown/YAML editing with full CodeMirror 6 syntax support.View all repositories taggedBuilt-in local MCP serverBuilt-in local MCP server14-tool MCP server over stdio and WebSocket, managed from inside the app.View all repositories taggedBlockNote rich-text editorBlockNote rich-text editorBlock-based rich-text editing with custom wikilink inline content, math (KaTeX), and Mermaid diagrams.View all repositories taggedInline frontmatter inspectorInline frontmatter inspectorSide panel for editing YAML frontmatter fields (status, tags, dates, custom fields) without leaving the editor.View all repositories tagged

Documentation

8 pages indexed · 1,240 words
  • READMETolaria — READMEgithub.com/refactoringhq/tolaria/blob/main/README.md

    Tolaria

    Tolaria is a desktop application for Mac and Linux that lets you manage a local markdown-based knowledge base (a "vault") with a structured note ontology, rich-text editing, full-text search, Git-backed sync, and a built-in MCP server so AI assistants can read and write your notes.

    Core principles

    • Files-first — plain .md files on disk; no proprietary format
    • Git-first — every vault is a Git repository; sync via push/pull, AutoGit checkpoints
    • Offline-first — no cloud account required
    • Open source — AGPL-3.0
    • Standards-based — CommonMark + YAML frontmatter
    • AI-first — MCP server exposes 14 tools for Claude Code, Cursor, and any MCP-compatible client
    • Keyboard-first — command palette, modal navigation

    Getting started

    Download the latest .tar.gz from the GitHub releases page. Supported on macOS and Linux.

    Local development

    prerequisites: Node.js 22+, pnpm 10+, Rust 1.87+, Tauri CLI v2
pnpm install
pnpm tauri dev

    License

    AGPL-3.0

  • Architecture Overviewgithub.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

    Architecture

    Tolaria is a Tauri v2 (2.10.0) application: a Rust backend with a React 19 + TypeScript 5.9 frontend rendered in a system WebView.

    Tech stack

    Layer Tech
    Desktop shell Tauri v2 2.10.0
    UI React 19, TypeScript 5.9, Tailwind CSS v4, Radix UI + shadcn/ui
    Rich-text editor BlockNote 0.46.2
    Raw/code editor CodeMirror 6
    Build Vite
    Testing Vitest, Playwright, cargo test
    Telemetry Sentry + PostHog (opt-in)

    Four-panel layout

    • Sidebar (250 px) — vault tree, entity-type navigation
    • NoteList (300 px) — filtered/sorted list of entries
    • Editor (flex) — BlockNote rich-text or CodeMirror raw mode
    • Inspector (280 px) — frontmatter fields, links, metadata

    Release cadence

    Calendar-alpha versioning: YYYY.M.D-alpha.N. In-app updates via Tauri updater plugin.

  • AI Agent Integrationgithub.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

    AI Agent Integration

    AI Panel (AiPanel)

    Tolaria includes an in-app AI agent panel that spawns AI CLI agents (Claude Code, Codex, OpenCode, Pi) as subprocesses. The panel gives the agent access to the vault via the built-in MCP server.

    Built-in MCP server

    A full Model Context Protocol server is included with 14 tools for reading and writing vault entries:

    • stdio transport (port 9710) for CLI agents like Claude Code
    • WebSocket transport (port 9711) for web-based MCP clients

    This means any MCP-compatible AI assistant can read your notes, create new entries, update frontmatter fields, search the vault, and follow wikilinks — all without leaving the app.

    Practical workflow

    1. Open the AI panel in Tolaria
    2. Tolaria starts the MCP server locally
    3. Spawn a Claude Code or Cursor session
    4. The agent operates on your vault with full context

    Backed by the @anthropic-ai/sdk npm package and the MCP SDK 1.0.

  • MCP Server — 14 Toolsgithub.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

    MCP Server

    Tolaria ships a local MCP (Model Context Protocol) server with 14 tools, exposable over stdio (port 9710) and WebSocket (port 9711).

    The server lifecycle is managed from within the Tauri app. It starts when the vault opens and stops when the app closes.

    What the tools cover

    • List and search vault entries by type, tag, or full-text
    • Read a note's full content and frontmatter
    • Create new notes with structured frontmatter
    • Update frontmatter fields (status, tags, dates, custom fields)
    • Follow wikilinks and traverse the knowledge graph
    • Query entity relationships (Projects → Tasks, People → Notes)

    Transport options

    • stdio on port 9710 — for CLI agents (Claude Code, Cursor, Codex)
    • WebSocket on port 9711 — for browser-based or remote agents

    Any MCP-compatible client can connect without additional setup.

  • Vault Model & Knowledge Ontologygithub.com/refactoringhq/tolaria/blob/main/docs/ABSTRACTIONS.md

    Vault Model

    A vault is a directory of .md files where each file is a VaultEntry. Entries are typed via a type field in YAML frontmatter.

    Entity types

    Type Purpose
    Project Goal with tasks and deliverables
    Responsibility Ongoing role or area of ownership
    Procedure Step-by-step process or runbook
    Note General-purpose capture
    Topic Domain concept or reference
    Event Meeting, deadline, occurrence
    Person Contact or collaborator

    Semantic fields

    Each entity type defines standard frontmatter fields (e.g., status, priority, tags, related). System properties use an underscore prefix (_created, _modified).

    Navigation

    • Wikilinks [[Note Name]] navigate between entries
    • Neighborhood mode shows all entries linked to the current one
    • Inbox Zero workflow: capture everything as Notes, then promote to typed entities

    Editor capabilities

    • BlockNote rich-text with custom wikilink inline content
    • Math blocks via KaTeX
    • Diagrams via Mermaid
    • Raw markdown mode via CodeMirror 6
  • Product Visiongithub.com/refactoringhq/tolaria/blob/main/docs/VISION.md

    Vision

    Tolaria was built by Luca Rossi (author of the Refactoring newsletter, 200K subscribers) to manage his personal 10K+ note vault. The problem: unstructured markdown vaults don't lend themselves to AI use — an LLM that has 10K untyped notes has no better starting point than keyword search.

    Core insight

    A PKM system has to ship the method alongside the tool. Tolaria's knowledge ontology (Projects, Responsibilities, Procedures, People, Topics, Events, Notes) gives the vault structure that AI agents can actually traverse.

    Design philosophy

    • Convention over configuration — opinionated ontology, no blank canvas
    • Git-first — local files + git for sync, conflict resolution, and history
    • Offline-first — no account, no cloud dependency

    Positioning vs Obsidian

    Obsidian is a blank canvas; Tolaria is opinionated. Obsidian uses a proprietary sync service; Tolaria uses Git. Tolaria ships a built-in MCP server; Obsidian requires community plugins.

    Roadmap stages

    1. Personal PKM tool (current)
    2. Independent knowledge workers and freelancers
    3. Small teams
  • Getting Startedgithub.com/refactoringhq/tolaria/blob/main/README.md

    Getting Started

    Install (end users)

    Download the latest release from the GitHub releases page:

    • macOS: .dmg installer
    • Linux: .tar.gz AppImage

    In-app updates are handled automatically via the Tauri updater plugin.

    Local development setup

    Prerequisites:

    • Node.js 22+
    • pnpm 10+
    • Rust 1.87+
    • Tauri CLI v2
    git clone https://github.com/refactoringhq/tolaria
pnpm install
pnpm tauri dev

    First vault

    1. Launch Tolaria
    2. Create or open a directory as your vault
    3. Tolaria initialises a Git repository in that directory
    4. Start capturing notes; use Inbox Zero to keep things organised

    Connecting an AI agent

    1. Open the AI panel (sidebar icon)
    2. Tolaria starts the MCP server on localhost:9710 (stdio) and :9711 (WebSocket)
    3. Point Claude Code or Cursor at the MCP server
    4. The agent can now read and write your vault entries
  • Git Integration & Syncgithub.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

    Git Integration

    Every Tolaria vault is a Git repository. The app exposes Git operations through the UI and backend:

    Sync flow

    1. User triggers sync (or AutoGit fires on save)
    2. Rust backend stages all changed .md files
    3. Commit is created with an automatic message
    4. Push/pull to the configured remote (GitHub, GitLab, any Git host)
    5. Conflicts are surfaced in the UI for manual resolution

    AutoGit

    AutoGit creates automatic checkpoints on every save. You can roll back to any previous state via the Git history.

    Pulse view

    A git activity feed showing recent commits, file changes, and sync status in a timeline view.

    Vault cache

    The backend maintains a git-based incremental cache: only changed files since the last known commit are rescanned, keeping startup time fast even for 10K+ note vaults.

    Conflict resolution

    When a push/pull produces a merge conflict, Tolaria surfaces the conflicting files with a diff view. The user resolves conflicts and recommits.