Welcome
outl
Local-first outliner. Markdown is the source of truth. Sync that doesn’t corrupt your tree when two devices edit offline.
outl takes the parts of Roam Research and Logseq that work — bi-directional links, dense queries, block-level thinking, journal-first — and rebuilds the part that doesn’t: how your notes survive being on more than one device.
Where to start
| You want to… | Read |
|---|---|
| Install and try outl in a minute | Getting started |
| Install via Homebrew (GA or beta) | Homebrew tap |
| Understand the pitch vs. Roam/Logseq | Why outl |
| Know exactly how sync works | Sync, done right |
| Use the TUI fluently | TUI manual |
| Change colors / write a theme | Theming |
| Script outl or plug it into Claude Code | CLI |
| Connect outl to Claude Desktop, Cursor, etc. | MCP |
| Build an MCP-driven skill or slash command on top of outl | MCP recipes |
| Send a PR and know what reviewers look at | Contributing & code review |
What’s locked in
The shape of outl is settled:
- Markdown is on disk, untouched. No
id::lines. No HTML comments. No frontmatter delimiters. What you wrote is what’s saved. Stable IDs live in a sidecar file (foo.outl, next tofoo.md) you’ll never have to look at. - The op log is the source of truth. Not the file.
Not the database.
A sequence of
Move/Edit/Create/SetPropops with HLC timestamps. The tree you see is a projection. - Storage is a trait, not a struct. JSONL (one append-only file per device) ships today; ChronDB is tracked publicly for when you want git-style history with branches and time travel.
- Every UI surface shares one core. The TUI, the Tauri desktop, and the iOS app all reuse
outl-coreandoutl-md— including the tokens, the index, the slugify rules. Android is not built yet.
Status (May 2026)
- Single-device editor: works. Modes, undo/redo, autocomplete, backlinks, theming, fuzzy switcher, workspace-wide search, command palette.
- Cross-device sync: works today (macOS TUI ↔ iOS app). The iOS client is on public TestFlight beta — join here.
- P2P transport: iroh (default).
QUIC, end-to-end encrypted, no central server; pairing via
outl peer pair. The CRDT algorithm is implemented and tested (170+ tests); thefiletransport (iCloud Drive / Syncthing / shared FS) is the opt-in alternative. - Tauri desktop: works (macOS / Linux / Windows).
Where it’s headed: the roadmap lives on the GitHub Project.
Background reading
Long-form posts about the engineering behind outl, published on avelino.run:
- File sync isn’t trivial — the distributed-systems problem behind concurrent file moves, and what a formally-verified algorithm gives you that ad-hoc merge doesn’t.
- From paper to outliner — the engineering between a CRDT proof and a shipped app: projections, reconciliation, transport edge cases, editor state.
Contributing
The README on GitHub has the install bits and the dev workflow. Before sending a PR, read Contributing & code review — the rules of the game are written down so you know exactly what reviewers will look at. Open issues to discuss design before sending big PRs; the sync algorithm in particular has a 100% coverage rule on its critical functions.
License
MIT.