Cairn MCP server
Commit Nov 16, 2026Lets an AI client search and update a Markdown-based second brain stored directly within your code repository.
Also known as juw12/cairn
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 16, 2026
- License
- MIT
What is Cairn MCP?
Cairn lets an AI client search and update a Markdown-based second brain stored directly within your code repository.
Summary generated from the project's README
About Cairn MCP server
Developers can manage a project's collective knowledge and tasks by integrating a Markdown-based second brain directly into their code repository. By using the cairn mcp command, AI assistants like Claude, Cursor, Copilot, or OpenCode can search through and update a dedicated brain folder. This setup allows for capturing ideas, recording decisions, and managing task boards without requiring any API keys.
The system functions by storing everything as plain Markdown files within a brain/ directory, ensuring that notes remain accessible in tools like Obsidian or VS Code even without the server. It can automatically transform TODO, FIXME, or HACK comments from your source code into organized tasks that track specific file lines. This approach keeps project context, such as decision logs and daily journals, physically located alongside the codebase for better alignment between documentation and implementation.
What you can do with it
- 1Automating decision loggingDevelopers can use the tool to document the reasoning and consequences behind architectural choices.
- 2Managing tasks via Markdown databasesAn AI client can update task statuses or due dates within Notion-style database blocks that remain compatible with other editors.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejuw12/cairn is public and reachablegithub.com/juw12/cairn ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/juw12/cairn ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSee it in action
About
Your project's thinking is scattered. Ideas sit in Notion, tasks in GitHub Issues, decisions in Slack threads, TODOs in code comments, and the "why" lives in someone's head. Obsidian and Notion are great at notes, but neither knows anything about your repo.
Cairn puts one calm place inside the project, built around how project work actually moves:
capture → brainstorm → decide → do → remember
bar ideas wall decision board notes, journal,
+ CLI + sparks log map, context pack
| Screen | What it does |
|---|---|
| Quick capture | One bar on every screen. todo: ship v1 #release, decision: use SQLite, log: fixed the bug or just text (an idea). It shows where the note will go before you press Enter. |
| Voice log | One Log button on every screen: in the top bar on a computer, bottom-right in thumb reach on a phone (or L). Talk and it writes a timestamped line into today's journal/YYYY-MM-DD.md; say todo …, idea …, decision … or mood good and it creates the linked note or mood too. Undo, read today, what did I do last Friday, search for …, stop. Uses the browser's speech engine, or an offline voice model that runs on your device; no API key, and typing works everywhere. More below. |
| Ideas wall | Raw → Exploring → Ready → Parked. Drag ideas right as they firm up. Spark drops a thinking prompt into an idea; Promote to task creates a linked task. |
| Board | To do → Doing → Done with drag and drop, checklists and progress bars. |
| Decisions | Lightweight decision records (context, options, decision, consequences), numbered and reviewed in PRs like code. |
| Journal & memories | Streaks, a 12-month heatmap, a mood chart, look-backs (yesterday, a week, a month and a year ago), what was on your mind, search across every day and a one-click weekly review saved as journal/YYYY-Www.md. |
| Notes, Journal | Markdown editor with preview, [[wikilinks]], backlinks, tags and a page per day. Open notes as tabs, and put a second note beside the first (columns button, Alt+click a link or tab, or drag a tab to the right): both stay editable, links in the side note open there, and the layout is remembered. |
| Map | A live graph of every note: drag notes (they stay pinned), zoom, pinch, hover to light up neighbours with direction arrows, click for an inspector with summary and links in/out. Shift-click two notes for the path between them, Alt-drag one onto another to write a [[link]], double-click a hollow "unwritten" link to create that note. Local graph (1-3 hops), search, colour by type / folder / cluster / status, tag hubs, orphan filter, a time-lapse of how the brain grew. Canvas-rendered, smooth with thousands of notes, and every note stays reachable by keyboard. |
| Canvas | Infinite boards of notes, cards, links and groups joined by arrows, saved as Obsidian-compatible .canvas files. Shift-drag to box-select, Ctrl+C / V / D to copy, paste and duplicate (pasting a link, a [[note]] or text makes the right card), drag notes in from the Notes panel. A note shows the canvases it sits on, and the Map draws each canvas as a square joined to its notes. |
| Obsidian sync | Import an Obsidian vault and keep it in sync both ways (notes and canvases). Files are mirrored as they are; nothing is converted. |
| Databases | Notion-style databases inside any note: a ```database block (type: task, where: status != done, sort: due asc, view: board) becomes a live table, board, gallery, list or calendar of your notes. Filters can be relative (where: due < today, due <= today+7), so an Overdue view stays right every day. Click a cell to edit it, drag a card to another column, press New to add a row. Unlike Notion, every row is still a plain Markdown file and every edit lands in its front matter, so Obsidian, GitHub and AI assistants see the same data. The view you pick is saved in the block itself. |
| / menu | Type / in the editor for a Notion-style block menu: headings, to-dos, toggles (foldable Obsidian callouts), callouts, tables, code, maths, Mermaid diagrams, links, embeds, dates and databases. Everything it inserts is plain Markdown. |
| Projects | Every GitHub repo of a person (yours by default, Cairn itself always included; forks, archived and profile/settings repos left out) ranked by how solid it is (live demo, tests, CI, codebase size, months of upkeep, README, license) and how much potential it has (stars, recent pushes, how often your own notes mention it, whether people can try it). Scores are partly relative to your other repos, so similar projects still spread out. Each card says what sets that repo apart (Why) and the concrete step that would lift it (Next); advice that applies to most of your repos is shown once above the list. It re-ranks itself every 15 minutes, shows who moved since yesterday, remembers test/CI checks until a repo is pushed again (so it stays inside GitHub's anonymous rate limit) and can keep a Project ranking note in the brain up to date. |
| Plugins | Community plugins: install from the list, a GitHub repo or a link. Each plugin gets a settings page drawn from its own options, a plugin that breaks is flagged on its row with a Restart button, and the list of plugins you use can be saved into the brain so your other devices offer to install the same ones (sources only, never code). Write your own in one file (PLUGINS.md). |
| Code inbox | Every TODO, FIXME and HACK comment in the repo. One click makes a task that remembers file:line. |
| Context pack | A one-page brief (doing now, up next, decisions in force, open questions) saved as brain/CONTEXT.md for teammates and AI assistants. |
| Search | Ctrl/⌘+K across every note and command. C jumps to capture, ? shows every shortcut. |
| People | Look up anyone on GitHub and see their proof of work, read from their brain's files: working on, shipped, decisions, open to collaborate. Open their brain read-only and Ask to join (opens a prefilled GitHub issue). |
Keyboard shortcuts
Press ? anywhere in the app (or pick Keyboard shortcuts in the palette) for the full sheet. The ones you'll use most:
| Where | Keys |
|---|---|
| Everywhere | Ctrl/⌘+K palette · / search · C capture · L voice log · ? shortcuts · Esc close |
| Tabs | Ctrl+click a link opens a tab · Ctrl+Alt+←/→ switch · Ctrl+Alt+W close · Ctrl+Alt+T reopen |
| Split view | Ctrl+Alt+\ open/close · Alt+click a link or tab · drag a tab to the right half |
| Writing | Ctrl+B/I bold/italic · [[ link a note · Enter continues a list |
| Canvas | double-click add · Shift+drag select · Ctrl+C/V/D copy/paste/duplicate · Ctrl+Z undo · arrows nudge · Shift+1 fit |
Use it
There are four ways to run it. All of them read and write the same plain files.
0. Desktop app for Windows (easiest). Download Cairn-Setup.cmd
and double-click it, or paste this in PowerShell: irm https://juw12.github.io/cairn/install.ps1 | iex.
No admin rights needed. It installs whatever is missing (Python, Git, the window and tray libraries), then opens
Cairn in its own window. After that, everything happens inside the app:
- Your notes open by themselves. The first time, Cairn opens the Obsidian vault you used last (or a fresh
brain in
Documents\Cairn). Switch brain opens another folder, gets a repo from GitHub (private ones too; GitHub's own sign-in window appears once), or starts a new brain. - One Sync button. It saves your edits, gets everyone else's and sends yours (commit + pull + push). It also
runs on its own every 10 minutes. If two people changed the same lines, nothing is lost: your edits stay
committed locally and Cairn tells you. Behind an office proxy, Sync tries every way out it can find (git's own
setting, the Windows proxy,
HTTPS_PROXY, signing in to the proxy as you) and remembers the one that works. - Your public brain stays current. In Settings, name your public repo (e.g.
you/brain) and turn on Publish automatically: after each sync, notes markedpublish: trueare published, but only when one of them changed. - Always there. Closing the window keeps Cairn in the tray and it starts with Windows.
- Updates itself, no restarts. Cairn checks for a new version every 20 minutes. Changes to the app's screens are swapped in with a quick reload the moment you pause (your open note stays open); the rarer changes to its engine restart Cairn quietly while it's in the tray, or after a couple of idle minutes, and bring the window back where you were. Settings turns each of these on or off.
1. Local app from the terminal. Python 3.13+, no dependencies:
git clone https://github.com/juw12/cairn
cd your-project
python -m cairn --root . # run from the cairn folder, or `pip install ./cairn` and run `cairn`
It opens http://127.0.0.1:4777 with code scanning and one-click Commit brain (commits only brain/; push with your usual git tool).
2. In the browser, on your real repo. Open juw12.github.io/cairn, choose Open a repo folder, and pick your project. Chrome and Edge on desktop can read and write the folder directly (File System Access API). Nothing is uploaded.
3. Demo. Try the sample project (an offline hiking app). It's saved only in your browser.
Watch your vibe coding live
Vibe (sidebar → Project) shows what your AI assistant is doing right now, what came out of it, and what people
thought. A session is a plain file in brain/sessions/ with status: live while you work and a log of timestamped
steps; feedback lives in brain/feedback/ with an optional 1-5 rating.
cairn vibe start "add dark mode" --agent claude # opens a live session
cairn vibe log "asked for a theme toggle" --kind prompt
cairn vibe log --progress 40 "wiring the toggle" # how far along it is: drives the live bar and time left
cairn vibe skill /refine "6.5 -> 8.7" # skill runs: /refine, /council, /ambitious-founder, /precedent...
cairn vibe check -- python -m pytest # runs your tests, logs pass/fail with the summary line
cairn vibe end --result shipped "toggle works" # records commits and +/- lines since the start
cairn feedback "toggle is hard to find on mobile" --rating 3 --from @alice
cairn vibe status # the same stats in the terminal
Paste the instructions from the Vibe page into AGENTS.md or CLAUDE.md and your assistant reports its own
progress. Any logged step that starts with a slash command counts as a skill run, and the page tallies them.
- Progress, time left, effort: every live session gets a percentage bar, an estimated time left and a
Light / Medium / Heavy effort badge with the reasons (time so far, lines and files changed, checks and failures).
The percent comes from what the agent logs (
--progress 40,[40%] ...,step 3/7); without that, Cairn estimates it from your own finished sessions (same agent when there are 10+), and says so on the card. - Parallel agents: run several sessions at once (one per terminal or git worktree).
startprints the session's slug; setCAIRN_SESSIONto it in that terminal (or pass--session) and every command goes there. - Live everywhere: the local app updates within seconds, with commits and changed files counted since the session started (exactly, from the commit it began on). A folder opened in Chrome or Edge refreshes every few seconds. A GitHub brain you're signed in to refreshes every 20 seconds with conditional requests, so unchanged checks don't use up your rate limit.
- Demo: Load a sample week on the Vibe page of the demo. Stats: sessions, time, ship rate, checks passing, a 14-day activity chart, open feedback and the average rating. No streaks, no leaderboards: everything is evidence you can open as a file.
Detect sessions automatically
cairn vibe watch notices AI coding sessions without anyone typing vibe start:
cairn vibe watch --once # one sync, then exit
cairn vibe watch # keep watching (every 60 s; --every 30)
cairn vibe watch --everywhere # OpenCode sessions from any folder, not just this repo
cairn vibe watch --install # start hidden at Windows sign-in (--uninstall removes it)
The desktop app does this on its own while it runs (Settings → Record AI coding sessions), so you only need the command without the app. An Obsidian vault takes sessions from every folder; any other brain only its own. Only one watcher writes a brain at a time: if the app, a startup watcher and a terminal all run, the others stand by and take over within five minutes of it stopping.
- OpenCode: each session in OpenCode's local database becomes a session note (
source: opencode) with active minutes (gaps between messages, capped at 10 minutes) and when they happened (spans), model and cost. OpenCode does not record line changes, so the watcher also counts the commits made in the session's folder while it ran (local branches, no merges, no[bot]authors). It islivewhile messages keep arriving,shippedif it changed or committed code, otherwisedone; the log says whether the folder had no commits or is not a git repo at all. Re-running is idempotent and finished sessions are not re-read, and a status you set by hand is kept until the session moves again. Subagent and archived sessions are skipped. - Vector: when the Vector app is running and this repo changes, a session opens; new commits are logged, and it
ends when Vector closes or the repo has been quiet for 30 minutes (
shippedwith commits, elsepartial). Detection is from the outside only (process list and git), so it can't see what was asked. For prompts and steps, let the assistant report itself withcairn vibe start/log/check/end. - Privacy: the OpenCode database is opened read-only and only session metadata and message timestamps are read,
never message text. Nothing leaves your machine.
--no-opencodeand--no-vectorturn either source off. - On the page: sessions are grouped by day (click a day to fold it) and the outcome chips (shipped, no code change, no git) double as the legend and as filters. Day totals are clock time too.
- Time vibing is clock time with at least one session working: two agents running side by side for an hour count as one hour, so it can never exceed the length of the day. The summed agent time is shown next to it as "N× in parallel".
Watch and control it from your phone
Pair a phone the way opencode pair does: in the desktop app open Settings > Pair a phone (or the tray icon's
Pair a phone..., or run cairn pair in a terminal) and scan the QR code. The phone opens straight on the Vibe page
and stays paired, so a home-screen bookmark keeps working: live sessions, autopilot jobs and notes, from the couch.
- Control, not just watch: the phone gets the full app (capture, edit notes, move tasks, start, comment on or stop autopilot jobs), minus the desktop-only controls such as Settings and updates.
- Chat: the Chat page is a plain chat with the AI models of the OpenCode on your PC (company builds such as
PEGAAi OpenCode included): pick a model, type, send, and the answer appears on whichever device you are on. Chats
keep their context and live in
~/.cairn/chats. The Glow tab next to it opens your Glow app (Chat, Council, Arena). - Chat from anywhere (GitHub relay): when the phone can't reach the PC at all (outside the office network,
no Tailscale), Chat goes through a private GitHub repo instead. On the PC run
cairn relay setuponce: it creates the private repo<you>/cairn-relayand saves your GitHub token encrypted for your Windows user in~/.cairn/relay.json; the desktop app then answers from it. On the phone open Cairn, sign in with a fine-grained token limited to that repo (Contents: read and write) and open Chat: messages land indevices/<pc>/requests/, that PC runs them and streams the answer intodevices/<pc>/threads/, and the page shows when the PC last checked in. Expect roughly 5-15 s before the reply starts. Several PCs: runcairn relay setup(optionally--name "Home PC") on every PC signed in to the same GitHub account; each gets its own folder in the repo and the phone shows a Talk to picker to choose which one answers, with each PC's own chats and models. Keep the repo private: anyone who can push to it can make your PCs run OpenCode prompts, and your chats are stored there. - Sign in a phone from any network: Settings > Sign in a phone (any network) shows a QR code that signs the phone's
browser in to Cairn with this PC's GitHub sign-in (the one
cairn relay setupsaved) and opens this brain from its GitHub repo. Copy link does the same for another browser. Show it only to your own devices; revoke the sign-in on GitHub to cut a device off. - Live sync: a change on the phone shows up in the open PC window within a few seconds without a reload, and back the other way. A note you are typing in is left alone until you pause.
- Any network: put both on Tailscale (same account). Settings > Set up Tailscale installs
it on the PC, opens the phone port to Tailscale devices only and turns on Run unattended. The QR code then uses the
PC's Tailscale name (
my-pc.tail1234.ts.net), so the paired phone works on mobile data or any Wi-Fi. Without Tailscale, phone and PC need the same Wi-Fi. - Always connected: Cairn starts with Windows, re-opens the phone port every minute if it dropped, and (by default) keeps the PC from sleeping on its own while phone access is on. Closing a laptop lid still sleeps it.
- Each QR code works once and expires after 5 minutes. A paired phone gets a random device cookie (only its hash is stored); Unpair all phones in Settings cuts every phone off at once, and unticking Let paired phones connect closes the port.
- If the phone can't connect, Windows Firewall may be blocking Python: allow it on private networks.
Cairn MCP questions
Does Cairn require API keys for its features?
No, Cairn does not require API keys for its core functionality or its voice logging features.
Can I sync my existing Obsidian vault with Cairn?
Yes, you can import an Obsidian vault and maintain two-way synchronization for both notes and canvases.