A second brain that lives inside your repo.
Capture ideas, brainstorm, record decisions and move tasks, all as plain Markdown next to your code.
Try it live ·
See it in action ·
Highlights ·
Landing page ·
More by juw12
Plain files, no lock-in
Everything is Markdown in a brain/ folder. Delete Cairn and it still reads fine on GitHub, in Obsidian or in VS Code.
Knows your code
Turns TODO/FIXME comments into tasks that remember the file and line, and commits the brain in one click.
Made for AI assistants too
cairn mcp lets Claude, Cursor, Copilot or OpenCode search and update the brain; brain/CONTEXT.md is a one-page brief for the rest. No API keys.
See it in action
Open the interactive demo at juw12.github.io/cairn
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** | Its own page in the sidebar. One period (7 days to all time, or any number of days) drives the numbers, a **recap with one line per day** (entries, agent sessions, tokens, topics), a mood worked out for you from what you wrote and how busy the day was, a 12-month heatmap, what was on your mind and search across every day. Nothing asks you to write a review. |
| **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](PLUGINS.md)). |
| **Code inbox** | Every `TODO`, `FIXME` and `HACK` comment in the repo. One click makes a task that remembers `file:line`. Under **Tools** (<kbd>Ctrl</kbd>+<kbd>K</kbd>), with Notes, Context pack, Obsidian sync and Plugins. |
| **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** | <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd> across every note and command. <kbd>C</kbd> jumps to capture, <kbd>?</kbd> shows [every shortcut](#keyboard-shortcuts). |
| **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). |
<table>
<tr>
<td width="50%" valign="top"><img src="docs/media/canvas.png" alt="A canvas of notes, cards and groups joined by arrows"><br><sub><b>Canvas.</b> Notes, cards, links and groups on an infinite board, saved as Obsidian <code>.canvas</code> files.</sub></td>
<td width="50%" valign="top"><img src="docs/media/split.png" alt="Two notes open side by side in split view"><br><sub><b>Tabs and split view.</b> Keep several notes open and edit two side by side.</sub></td>
</tr>
<tr>
<td width="50%" valign="top"><img src="docs/media/plugins.png" alt="The plugins page with a plugin's settings open"><br><sub><b>Plugins.</b> Install from the list, a repo or a link; each plugin gets its own settings page.</sub></td>
<td width="50%" valign="top"><img src="docs/media/shortcuts.png" alt="The keyboard shortcuts sheet"><br><sub><b>Keyboard first.</b> Press <kbd>?</kbd> anywhere for every shortcut.</sub></td>
</tr>
</table>
### Keyboard shortcuts
Press <kbd>?</kbd> anywhere in the app (or pick **Keyboard shortcuts** in the palette) for the full sheet. The ones you'll use most:
| Where | Keys |
|---|---|
| Everywhere | <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd> palette · <kbd>/</kbd> search · <kbd>C</kbd> capture · <kbd>L</kbd> voice log · <kbd>?</kbd> shortcuts · <kbd>Esc</kbd> close |
| Tabs | <kbd>Ctrl</kbd>+click a link opens a tab · <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>←</kbd>/<kbd>→</kbd> switch · <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd> close · <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>T</kbd> reopen |
| Split view | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>&#92;</kbd> open/close · <kbd>Alt</kbd>+click a link or tab · drag a tab to the right half |
| Writing | <kbd>Ctrl</kbd>+<kbd>B</kbd>/<kbd>I</kbd> bold/italic · <kbd>[[</kbd> link a note · <kbd>Enter</kbd> continues a list |
| Canvas | double-click add · <kbd>Shift</kbd>+drag select · <kbd>Ctrl</kbd>+<kbd>C</kbd>/<kbd>V</kbd>/<kbd>D</kbd> copy/paste/duplicate · <kbd>Ctrl</kbd>+<kbd>Z</kbd> undo · arrows nudge · <kbd>Shift</kbd>+<kbd>1</kbd> 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`](https://juw12.github.io/cairn/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 marked `publish: true` are 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:
```bash
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](https://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](https://juw12.github.io/cairn/?demo=1) (an offline hiking app). It's saved only in your browser.
### Watch your vibe coding live
**Vibe** (sidebar → Build) 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.
Every block on the Vibe page (live recap, overview, numbers, activity, sessions, skills, models...) folds to one
line with a summary, and moves up or down with its arrows or by dragging its handle. Every other page is built the
same way (Today, Board, Ideas, Decisions, Journal, Projects, Chat, Autopilot, Map, Canvas, People, Proof, Notes and
the Code inbox), each with a **Dashboard** (the numbers) and a **Recap** (what changed and what needs you). On Chat
and the Map the tool comes first and the two blocks sit under it; move them where you like. The layout is saved in
`brain/CAIRN-LAYOUT.md` (one `page-order:` and `page-folded:` line per page), so the desktop app, the web app and
your phone show the same pages.
The **Live recap** is the one list of sessions that are open: each row says *working*, *turn finished*, *stopped on
an error* or *left open*, and opens to the full session (progress, steps, add a step, end it). Its sections
(running, left open, just finished) and each assistant in the overview (OpenCode, OpenBot, Vector...) fold too.
A session counts as running only while it is doing something: nothing ever waits for you to press a button.
Blocks with nothing in them stay away (feedback before the first `fb:` note, models that used no tokens).
```sh
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). `start` prints the
session's slug; set `CAIRN_SESSION` to 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](https://juw12.github.io/cairn/?demo=1). 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`:
```sh
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 is `live` only while a turn is running: the moment the
assistant finishes its turn the session ends (`shipped` if it changed or committed code, otherwise `done`), and a
new message opens it again. A session deleted from OpenCode's database (bots that clean up after themselves) is
closed too. 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 (`shipped` with commits, else `partial`).
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 with `cairn vibe start/log/check/end`. A self-reported session that never says
`vibe end` is closed after four hours without a step, and its next `vibe log --session <slug>` opens it again.
- **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-opencode` and `--no-vector` turn either source off.
- **Several computers:** every session note names the computer it ran on (`machine:`), so two computers can write
into one brain. Sync the brain between them the way you already do (git), run Cairn on each, and the Vibe page
gets a device bar: **All devices** with the totals together, or one computer alone with its own sessions, live
count, tokens and load reading. The first pass on a computer takes every session its OpenCode still has, not just
the last 14 days (`--days 0` does that again later). A watcher only opens and closes the sessions of its own
computer. Another computer is as current as its last sync into the brain. `cairn vibe device` shows the name in
use (`CAIRN_DEVICE=...` sets another), and `cairn vibe device --adopt`, run once on the computer that made them,
puts its name on older sessions that name none. On a Mac the load reading comes from `vm_stat`, `pmset` and `ps`.
- **GitHub Actions minutes:** with a GitHub token (the one `cairn publish` uses) the watcher reads your Actions
usage once an hour and keeps one note per month in `github-usage/`. The Vibe page shows this month's free
minutes as a meter, warns at 75%, 90% and 100% (or when the last 7 days' pace would pass 100% by month end),
and keeps the daily and monthly history. Only private repos count; it is an estimate and GitHub's own meter
decides. The calls only read; `--no-github` turns them off.
- **A second GitHub account:** minutes count for the account that owns a repo, whoever pushes to it. If the
GitHub CLI is signed in to another account of yours (`gh auth login`, with the `user` scope so it may read
billing: `gh auth refresh -h github.com -s user`), `cairn vibe watch --github-account NAME` notes its minutes
too, in `github-usage/NAME/`, and the Vibe page shows a meter for each account. In the desktop app the setting
is `vibeWatchGithubAccounts`. One computer can write the main account's note and another the second account's
(`--no-github --github-account NAME`), so two never write the same note. `cairn vibe github --account NAME`
reads or sets that account's figure.
- **Moving a repo's minutes:** when one account is nearly out and another has room, the meter offers the busiest
private repos with a button, **repo → other account** (or `cairn vibe github move REPO --to NAME`). It asks
GitHub to transfer the repo: GitHub mails the new owner, nothing moves until that link is opened (within a
day), the old owner stays on as a collaborator and can still push, and the old address redirects. Only between
accounts signed in on this computer, only for private repos, only from Cairn on the computer itself (never
from a paired phone), and never without a confirmation. Mind GitHub's terms on how many free accounts one
person may hold.
- **Which account this computer pushes as:** where the GitHub CLI is signed in to several accounts, the Vibe
page shows **Pushes from this computer** with a chip per account, the one in use pressed (or
`cairn vibe github push-as [NAME]`). A press runs `gh auth switch`; the first press also runs
`gh auth setup-git`, after a confirmation, so that git asks the GitHub CLI for its GitHub sign-in. From then
on `git push`, `gh` and an assistant working on that computer all go out as the account picked, and a switch
made in a terminal shows on the page within seconds. Commits keep their author; only the sign-in changes,
the name GitHub puts on a push, a pull request and a release. It is checked on the computer, by comparing
the sign-in git would send with the CLI's, and no token is shown or stored. Never from a paired phone. A repo
whose address names a user or uses SSH keeps its own sign-in. To undo the first press:
`git config --global --unset-all credential.https://github.com.helper` (and the same line for
`gist.github.com`, which the GitHub CLI sets along with it).
- **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 setup` once: it creates
the private repo `<you>/cairn-relay` and 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](https://juw12.github.io/cairn/), sign in with a fine-grained token limited to that repo (*Contents: read and
write*) and open *Chat*: messages land in `devices/<pc>/requests/`, that PC runs them and streams the answer into
`devices/<pc>/threads/`, and the page shows when the PC last checked in. Expect roughly 5-15 s before the reply
starts. **Several PCs:** run `cairn 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](https://juw12.github.io/cairn/) with this PC's GitHub sign-in (the one `cairn relay setup` saved)
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](https://tailscale.com) (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.
### Get a daily status report in Telegram
A Telegram bot of your own tells you once a day whether Cairn is healthy and what the day held, and answers
`/status` whenever you ask:
Cairn on MY-PC · Tue 17 Nov
All good.
Today
6 AI sessions: 4 shipped, 1 partial, 1 still live
3h 05m of session time · checks: 12 passed, 0 failed
Live now: Fix the map on phones
Tasks: 4 to do, 1 in progress
Cairn
Desktop app 1.0.0 (5ba5fd8): running
Brain "brain": in sync with GitHub
Session watcher: running
Phone access: on, 1 phone paired```
The first line under the date is the verdict: All good. or Needs a look: ... with what is wrong (the desktop
app is not running, the brain has work that is not on GitHub, the session watcher stopped, checks failed, GitHub
Actions minutes are running out). If the PC has been off or asleep, the report says since when.
cairn telegram setup # token from @BotFather's /newbot; then open the link it prints (--hour 8 for mornings)
cairn telegram show # print the report here, send nothing
cairn telegram send # send it now
cairn telegram status # what is connected
cairn telegram off # forget the bot```
The bot runs on a small free Cloudflare Worker rather than on the PC, because office networks often block
Telegram and a PC that is off cannot say so. Deploying it takes about ten minutes:
see [`worker/README.md`](worker/README.md). Only the report text leaves the PC (session titles, counts, sync
state), and nothing is sent until you set a bot up.
### Hand over a goal: precedent and autopilot
Say what you want once and get what you would have asked for next. `cairn precedent` learns from your own
history (past prompts in Claude transcripts and OpenCode's local database, your `Update Log`, lessons you logged)
and writes a brief for any goal: a draft Definition of Done, the *hidden asks* (what you asked for after similar
goals before), the closest past prompts, your working profile (`brain/notes/precedent-profile.md`), the queue and
the loop to follow. Any assistant can read it through MCP (`precedent_brief`, the `precedent` prompt) or the
`/precedent` command that `cairn precedent install` writes for Claude Code, OpenCode and Codex.
```bash
cairn precedent learn # build the library in ~/.cairn/precedent (redacts tokens and passwords)
cairn precedent brief "landing page for the new app"
cairn precedent queue "add CSV export" --auto # a #queue task; --auto = safe unattended, --needs-me = waiting on you
cairn precedent next # the next open queue item
cairn precedent log "goal" "what shipped" "what you corrected"
cairn precedent install # /precedent for Claude Code, OpenCode and Codex```
The **Autopilot** page (and `cairn autopilot`) goes one step further: hand over a goal and Cairn runs *your* coding
agent round after round (OpenCode by default, or any command such as `claude -p`) until it reports `STATUS: DONE`,
gives it a couple of polish rounds, marks the queue task done, logs the lesson and takes the next `#auto` item.
You watch the live log, steer with a comment, and get a Windows notification when it needs you.
A round that fails with no reply (connection lost, gateway down) is not counted: the job waits 30 seconds to
…(正文过长,页面只展示前面部分,完整内容见仓库)
