Markoo is a smart two-way connector between a knowledge base and a local Git repository. Write a note in your knowledge base and it lands in your repo's docs/ with working Markdown links; pull a teammate's change to docs/ and your knowledge base is updated.
Knowledge base tools are supported through adapters. Obsidian is the first one implemented; Logseq, Foam, Dendron and plain Markdown folders are designed to follow. When both sides changed, Markoo merges them like Git does, and only asks you when there is a real conflict.
Warning
Keep a backup of your notes, and start on a copy: a mistake in the choice of folders copies a lot of files. The Linux app is new and less tried than the macOS one; Windows only has the command line for now.
- Any knowledge base, through adapters: Obsidian and plain Markdown folders today, others later. Each adapter converts its tool's Markdown dialect to standard Markdown and back.
- Three sync directions per pair: KB → repo, repo → KB, or both ways.
- Projects: pairs are grouped by project, for example a project's documentation and its skill, and a whole project syncs at once. Each pair has a name you choose and can change at any time ("Technical documentation"), and a stable id that keeps its history and hooks.
- 3-way merge: changes on both sides are merged line by line against the last synced version. You only decide on real conflicts.
- No data loss: dry-run before anything is written, atomic writes, backups and a trash folder. Markoo never commits or pushes for you.
- Obsidian ↔ GitHub conversion (first adapter):
[[wikilinks]]become standard Markdown links, attachments are copied toassets/, callouts become GitHub alerts, and Obsidian-only frontmatter is filtered — all reversibly. - Rename detection: a moved or renamed note is moved on the other side too, and links pointing to it are updated.
- Many triggers: time interval, Git hooks (
post-merge…), local HTTP API, MCP server for Claude and other AI agents, CLI. - Desktop app: menu bar status, pair setup wizard, side-by-side conflict view.
- Cross-platform: the app runs on macOS (Apple Silicon) and Linux; the command line also runs on Intel Macs and Windows. See supported systems.
For every file, Markoo compares three versions: the knowledge base, the repo, and the base — the content at the last successful sync. The base tells which side changed, so Markoo can copy, merge or flag a conflict without guessing.
flowchart LR
B[("Base<br/>last sync")] --> M{"Compare"}
V["KB"] --> M
R["Repo"] --> M
M -->|one side changed| C["Copy"]
M -->|both changed, no overlap| F["Merge"]
M -->|both changed, overlap| K["Conflict: you decide"]
Details: sync algorithm.
Get the app or the command line from the releases, or build from source with cargo install --path crates/markoo-cli --locked. The user guide explains the rest.
| System | Desktop app | Command line |
|---|---|---|
| macOS 11 or later, Apple Silicon | ✅ .dmg |
✅ |
| macOS 11 or later, Intel | ❌ | ✅ |
| Linux x86_64 (glibc 2.35 or later: Ubuntu 22.04, Debian 12 or later) | ✅ .AppImage, .deb |
✅ |
| Windows 10 or later, x86_64 | ❌ | ✅ |
The app includes the command line. Linux on ARM and Windows on ARM have no build; the command line can be built from source there.
markoo pair add clara --project Clara --kb ~/Obsidian/Knowledge/Projects/Clara --kb-type obsidian --repo ~/code/clara/docs --direction bothmarkoo statusmarkoo sync --dry-runmarkoo hook install --pair claraConfiguration lives in a single markoo.toml, editable by hand or from the app. See configuration.
Rust (Cargo workspace) · Tauri 2 · SQLite · axum · MCP (rmcp)
crates/markoo-core sync engine (all the logic)
crates/markoo-cli `markoo` command
crates/markoo-daemon scheduler + HTTP API + MCP host
crates/markoo-mcp MCP tools
app/ Tauri desktop app
Start with the user guide. The design documentation is available in English and French: documentation index.
| Vision and scope | Architecture |
| Sync algorithm | Transformations |
| Triggers | Configuration |
| Roadmap | Configuration UI |
| Knowledge bases | User guide |
Contributions are welcome. Before contributing:
- documentation is bilingual: any change in
documentation/en/must be mirrored indocumentation/fr/in the same commit, and vice versa.
Licensed under the Apache License, Version 2.0.