invited you to Caldera. Install below, then add as a friend from the Caldera panel in Obsidian.
Install
Free and open source / for Obsidian
The social layer
for Obsidian.
Turn your vault into a living profile that updates itself every day, and a digital garden of notes you grow in public. Then connect with friends' vaults: link to each other's gardens, share notes, ask for help, and give gravity to the people who show up for you.
Private by default. Nothing leaves your vault unless you choose it. Privacy Policy
01
A living profile
Caldera reads your vault on your device and builds a profile page: a daily journal you can flip through, an activity score, topics, and the notes you choose to share.
02
A reason to check in
Every morning: what you did yesterday, how it compares to the day before, your streak, and your best days. Bring your own data from calendar, email or git.
03
Friends between vaults
Add friends by handle. Share any note as an end-to-end encrypted card; it lands in their vault as a normal note and updates when you edit it.
04
Asks, offers and gravity
Post what you could use help with and what you can help with. Put a bounty of help credits on an ask and award it to whoever helps. No likes, no downvotes: give gravity to people who helped you. It fades over a month, so recent help counts most.
05
A garden, connected
Plant notes in a Garden folder and each becomes a full public page, marked seedling, budding or evergreen, with a license you choose. Your daily journal grows it too: each project you keep working on gets its own page. Link to a friend's note and theirs links back. See recently tended notes.
06
Open protocol
Your identity is a key that lives in your vault, not an account. Everything is signed. Self-host your page or your own hub.
Private by default
- Your vault never uploads. Caldera builds your profile on your device and sends only the finished page.
- You choose every section. Each part of the profile has its own switch. A note is public only if you plant it in your Garden folder (a full page) or add
caldera: public(title and first paragraph). - Gardens are scrubbed. Email addresses and phone numbers are removed,
%% comments %%never leave your vault, and links to notes outside your garden show as plain text. - Preview first. See exactly what visitors will see before anything is published.
- Shared notes are end-to-end encrypted. The hub only stores ciphertext it cannot read.
- Topics are allow-listed. Only tags you list are ever counted, so private names never appear.
- No telemetry. The plugin talks only to the hub you choose, only when you act.
Install
One paste. Your AI does the rest.
Works with Claude Code, Codex, Cursor, or any AI agent that can edit files on your computer. New to Obsidian? That's fine: the prompt installs Obsidian (free) and sets up your first vault, too.
- 1Copy the promptOne click, below.
- 2Paste it into your agentIt installs Obsidian if you need it, then Caldera, and sets up your daily journal.
- 3Open Obsidian, pick a handleYour profile publishes and opens in your browser. Your key never passes through the AI.
- Installs Obsidian if needed
- Installs the plugin
- Writes a daily journal entry
- Counts your activity
- Privacy rules override everything
- Never touches your key
You are helping me run Caldera, the social layer for my Obsidian vault (https://caldera.social). Caldera builds a public profile page from my vault. Follow these instructions exactly.
Vault: <ABSOLUTE PATH TO MY OBSIDIAN VAULT>
(If I did not fill this in, find my vault yourself: it is the folder that contains a .obsidian folder. If there is more than one, ask me which. If there is none, I probably don't have Obsidian yet - many people don't - so start with step 0.)
My public page: https://caldera.social/@<my handle>/
## 0. Obsidian itself (if I'm new - many people are - this step sets everything up; skip it only if I already use Obsidian)
1. Check whether Obsidian is installed (macOS: /Applications/Obsidian.app or ~/Applications/Obsidian.app; Windows: %LOCALAPPDATA%\Programs\Obsidian\Obsidian.exe; Linux: the obsidian command, Flatpak md.obsidian.Obsidian, or an Obsidian AppImage).
2. If it is not installed, tell me you are about to install Obsidian (the free official app from https://obsidian.md), then install it:
- macOS: brew install --cask obsidian (no Homebrew? download https://obsidian.md/download , open the .dmg and copy Obsidian.app into /Applications)
- Windows: winget install --id Obsidian.Obsidian -e (or run the installer from https://obsidian.md/download)
- Linux: flatpak install -y flathub md.obsidian.Obsidian (or the AppImage / .deb from https://obsidian.md/download)
If you cannot install software here, give me the download link and wait until I tell you it's installed. Do not open Obsidian yet.
3. If I don't have a vault yet, make one for me, completely, BEFORE Obsidian opens it:
a. Ask where I'd like my notes; if I don't care, use ~/Documents/Notes (Windows: %USERPROFILE%\Documents\Notes). Create the folder, a "Welcome.md" note in it ("# Welcome" and one line saying this is my vault), and an empty ".obsidian" folder inside it. That folder is now my vault; use its absolute path below.
b. Install the plugin into it now (exactly as in step 1 below), so it is ready on first launch.
c. Make Obsidian quit if it is running (it rewrites its vault list on exit). Then register the vault in Obsidian's vault list, a JSON file at:
macOS ~/Library/Application Support/obsidian/obsidian.json - Windows %APPDATA%\obsidian\obsidian.json - Linux ~/.config/obsidian/obsidian.json (Flatpak: ~/.var/app/md.obsidian.Obsidian/config/obsidian/obsidian.json).
Create the folder and file if missing. The file looks like {"vaults":{"<id>":{"path":"<absolute vault path>","ts":<now in ms>,"open":true}}}. Add my vault under a new random 16-character lowercase hex id, keep every other key and vault already in the file, and write valid JSON.
d. Open it: macOS open "obsidian://open?path=<url-encoded absolute vault path>" - Windows start "" "obsidian://open?path=..." - Linux xdg-open "obsidian://open?path=..." . If Obsidian instead shows its vault picker, tell me to click "Open folder as vault" and choose that folder.
e. Tell me, in plain words: in Obsidian, open Settings (the gear, bottom left) -> Community plugins -> click "Turn on community plugins". (If Obsidian shows a "Trust author and enable plugins" prompt instead, click that.) Caldera is already switched on, so its Welcome window appears right away. Caldera opens a Welcome window where I type my name and pick a handle; it creates my identity on this device, publishes my profile and opens it in my browser. Do NOT create the identity, read the plugin's data.json, or handle my keys yourself - that file holds my private key. Wait until I tell you my profile is live, then continue with step 2.
Steps a-e replace step 1 - after e, go straight to step 2.
## 1. Install the plugin (when I already have a vault)
1. Download https://caldera.social/download/caldera-latest.zip and unzip it into "<ABSOLUTE PATH TO MY OBSIDIAN VAULT>/.obsidian/plugins/caldera/" so that folder contains main.js, manifest.json and styles.css (create the folders if needed).
2. Add "caldera" to the JSON array in "<ABSOLUTE PATH TO MY OBSIDIAN VAULT>/.obsidian/community-plugins.json" (create the file as ["caldera"] if it does not exist). Do not remove other entries.
3. Tell me to restart Obsidian (quit fully, then open it). If Obsidian asks, I turn off Restricted mode (Settings -> Community plugins -> Turn on community plugins) and make sure Caldera is switched on. Caldera opens a Welcome window where I type my name and pick a handle; it creates my identity on this device, publishes my profile and opens it in my browser. Do NOT create the identity, read the plugin's data.json, or handle my keys yourself - that file holds my private key. Wait until I tell you my profile is live, then continue with step 2.
## 2. Daily routine (run once a day, in the morning, for YESTERDAY's date; I will schedule you)
A. Journal entry. Open (or create) yesterday's daily note, named YYYY-MM-DD.md, wherever my daily notes live. Add these frontmatter properties, keeping everything already in the note:
caldera_headline: one sentence, the shape of the day
caldera_focus: 2-4 short items, what I worked on
caldera_wins: 1-3 short items, what got done
caldera_themes: 1-3 single words
Write them from my notes, calendar, sent email, commits and AI sessions for that day - whatever you can access.
Name my projects the way they appear in Caldera/profile.md "projects" when they come up: Caldera grows a garden page for each project (and each distinctive theme) from these journal lines, adding a dated entry whenever it comes up.
B. Activity counts. Update "<ABSOLUTE PATH TO MY OBSIDIAN VAULT>/Caldera/activity.json" (create it if missing). Format:
{ "days": [ { "date": "YYYY-MM-DD", "meetings": 0, "emails": 0, "prompts": 0, "commits": 0, "docs": 0, "tokens": 0 } ],
"ai": { "total": 0, "window_days": 45, "models": [["Claude Opus 5.5", 0]], "providers": [["Anthropic", 0]] },
"code": { "commits": 0, "repos": 0, "languages": ["Python"], "weekly": [0], "url": "https://github.com/<me>", "start": "Mon YYYY" } }
One object per date: replace that date's object if it exists, keep the last 60 days, and only include counts you can actually measure (omit the rest - never guess). meetings = calendar events attended, emails = emails I sent, prompts = AI prompts I sent, commits = git commits I authored, docs = documents/attachments I produced or filed, tokens = AI tokens processed for me that day. Notes are counted by the plugin itself.
AI usage ("tokens" per day and the "ai" block, last 45 days): read the usage logs of the AI tools on this computer - Claude Code (~/.claude/projects/**/*.jsonl: assistant messages have message.model and message.usage; count each message.id once; tokens = input + output + cache read + cache write) and Codex (~/.codex/sessions/**/*.jsonl: event_msg token_count -> last_token_usage.total_tokens, model from turn_context). Add other tools only if they keep local usage logs. Group by model (readable names) and by provider. Never include prompts, file names or costs.
Code ("code" block, optional): if I use GitHub, count my commits in the last 52 weeks per week across my repositories (the gh CLI or the GitHub API), number of repos, and top 4 languages. Counts only - never repository names that are private.
C. Publish. If Caldera auto-publish is on (Settings -> Caldera -> Auto-publish every N hours), you are done. Otherwise ask me to run "Caldera: Publish my profile" from the command palette.
## 3. Privacy rules (these override everything above)
Everything public is on the open internet, can be copied forever, and can affect other people. Be very cautious. Never write any of these into anything public:
- Other people: no names, initials, handles, photos or descriptions that identify anyone I meet, work with, hire, date, advise or invest with. Say "a founder", "the team", "a friend" only when it adds nothing identifying - usually leave it out.
- Meetings: no meetings, calls, lunches, dinners, interviews or events - not their titles, times, dates, attendees, or that they happened with someone specific.
- Times and places: no times of day, schedules, travel, cities, venues, addresses, offices, home or "where I am".
- Secret or sensitive work: no unannounced, stealth, confidential or NDA projects, codenames, deals, fundraising, investors, acquisitions, valuations, hiring, firing or anything said in confidence.
- Things that can get someone in trouble: legal, medical, health, HR, money, salaries, debts, relationships, family, children, politics, religion.
- Contact details and links: no emails, phone numbers or links to private documents. No money amounts at all.
Describe work only by its public theme ("shipped a release", "wrote about design") and only name things I have already made public on my page (my own public projects, topics and links). If you are unsure, leave it out - an empty field is fine. Caldera also drops any journal line that looks sensitive before publishing.
Themes and topics: only use topics among the tags I allow-listed in Settings -> Caldera -> Public topics.
Also: never write to any other part of the vault, never change notes' privacy markings (caldera: public / garden / friends / private) or move notes into or out of the Garden folder, never touch .obsidian/plugins/caldera/data.json.
## 4. Check your work
After each run, tell me in two lines what you wrote for that day, and anything you skipped because it looked private.
## 5. When I ask you to change my page
My name, headline, photo, banner, links, properties, topics, which sections show and whether I'm listed in the directory all live in the frontmatter of "<ABSOLUTE PATH TO MY OBSIDIAN VAULT>/Caldera/profile.md". Edit that file (keep its format; the same privacy rules apply) and the page republishes itself within about a minute. Guide: https://caldera.social/guide.html
Already installed? In Obsidian, run Caldera: Copy AI agent setup prompt for a version pre-filled with your vault path, handle and topics.
Prefer to install by hand?
1 · Get the plugin
- No Obsidian yet? Download it free from obsidian.md, open it, and choose Create new vault.
- Download caldera-latest.zip.
- In your vault, open the hidden folder
.obsidian/plugins/and create a folder namedcaldera. On a Mac, Cmd+Shift+. shows hidden folders in Finder. - Unzip into it: you should see
main.js,manifest.jsonandstyles.css. - Restart Obsidian, then Settings → Community plugins → turn on Caldera.
Once listed in the community directory: Settings → Community plugins → Browse → search Caldera.
2 · Set it up
- Restart Obsidian. The Welcome to Caldera window asks for your name and a handle, publishes your page and opens it in your browser.
- Save your recovery key when it offers (Settings → Caldera → Export recovery key any time).
- Change anything later in the note
Caldera/profile.md; see the Guide. - Open the flame icon panel to add friends and give gravity.
Optional · after setup
Make it richer
A second prompt that suggests notes to show, topics, activity sources, a 14-day journal backfill, and asks and offers. It asks before anything becomes public.
- Suggests public notes
- Picks safe topics
- Connects activity sources
- Backfills 14 days
- Asks before publishing
Help me make my Caldera profile richer. Caldera (https://caldera.social) builds a public profile page from my Obsidian vault.
Vault: <ABSOLUTE PATH TO MY OBSIDIAN VAULT>
(If I did not fill this in, find my vault yourself: it is the folder that contains a .obsidian folder. If there is more than one, ask me which.)
Work through these one at a time. Anything that would become PUBLIC needs my explicit yes first: show me exactly what you propose, wait for my answer, then make only the approved changes.
1. My garden (public notes). Find 3-8 notes that would be good to grow in public: evergreen essays, how-tos, reading notes, overviews of work that is already public. Skip anything about people, clients, deals, money, health, family or unannounced work. List them with one line each on why, and a suggested stage (seedling = rough, budding = taking shape, evergreen = worked through). After I approve, add to the frontmatter of the approved notes only: "caldera: garden", "stage: <stage>" and "license: all-rights" (ask me if I want "cc-by" instead). The WHOLE note becomes a public page, so read every line and point out anything private first. Email addresses and phone numbers are removed automatically; links to notes that are not in the garden show as plain text. Then tell me to run "Caldera: Preview my garden".
2. Notes friends can receive. Suggest notes I might want to share with friends as encrypted cards (frameworks, checklists, templates). After I approve, add "caldera: friends" to their frontmatter. These are not public; only friends I pick receive them.
3. Public topics. List my 10 most-used tags that are safe to show publicly (no client, company or people tags), with a short label for each. I will add them myself in Settings -> Caldera -> Public topics. Do not edit plugin settings.
4. Activity sources. Set up a daily scheduled job (cron, launchd, Task Scheduler, or your own scheduler) that writes COUNTS ONLY for yesterday into "<ABSOLUTE PATH TO MY OBSIDIAN VAULT>/Caldera/activity.json" in this format, replacing that date's entry and keeping 60 days:
{ "days": [ { "date": "YYYY-MM-DD", "meetings": 0, "emails": 0, "prompts": 0, "commits": 0, "docs": 0 } ] }
Use the sources I actually have: calendar events attended, emails I sent, AI prompts I sent, git commits I authored, documents I produced. Only numbers - never titles, subjects, names or contents. Tell me which sources you connected and which you could not. If a daily journal routine already writes this file, extend it instead of adding a second writer.
5. My page text. Draft, for Caldera/profile.md: "headline" (one line), "summary" (2 sentences, links as [[Label|https://...]]), "now" (3 lines on what I'm doing now), "timeline" (only things already public: "Year | milestone | one-line detail", grouped into chapters with "era | Name | 2015-2020" lines), "projects" (Name | status | https://link, only public projects) and "links" (Label | https://url - include my GitHub profile if I have one: that turns on the Code section). Offer to set a profile photo: save an image I choose into "Caldera/img/" and set "photo" to that path. Also suggest "sidebar" groups (Group | item, item), up to 14 "graph" note names (people/companies/projects I'm comfortable showing - the page shows how many notes link to each), and 6 "backlinks" (Title | short context). Show me everything first; write only what I approve.
6. Daily journal. If nothing writes my journal yet, extend the daily job from step 4 so that each morning it also opens yesterday's daily note (YYYY-MM-DD.md) and adds caldera_headline (one line), caldera_focus (up to 3), caldera_wins (up to 3) and caldera_themes (1-3 words), written from what I did that day, following the privacy rules below. Then backfill: For each of the last 14 days that has activity, add caldera_headline, caldera_focus, caldera_wins and caldera_themes to that day's daily note (YYYY-MM-DD.md), following the privacy rules below. Show me the 14 entries before writing them.
7. Asks and offers. Draft 2 asks ("I could use help with...") and 2 offers ("I can help with...") that fit what I work on. I will post the ones I like with the commands "Caldera: Post an ask" and "Caldera: Post an offer".
8. Finish. Tell me to run "Caldera: Preview my public profile", check it, then "Caldera: Publish my profile".
Privacy rules (these override everything above):
Everything public is on the open internet, can be copied forever, and can affect other people. Be very cautious. Never write any of these into anything public:
- Other people: no names, initials, handles, photos or descriptions that identify anyone I meet, work with, hire, date, advise or invest with. Say "a founder", "the team", "a friend" only when it adds nothing identifying - usually leave it out.
- Meetings: no meetings, calls, lunches, dinners, interviews or events - not their titles, times, dates, attendees, or that they happened with someone specific.
- Times and places: no times of day, schedules, travel, cities, venues, addresses, offices, home or "where I am".
- Secret or sensitive work: no unannounced, stealth, confidential or NDA projects, codenames, deals, fundraising, investors, acquisitions, valuations, hiring, firing or anything said in confidence.
- Things that can get someone in trouble: legal, medical, health, HR, money, salaries, debts, relationships, family, children, politics, religion.
- Contact details and links: no emails, phone numbers or links to private documents. No money amounts at all.
Describe work only by its public theme ("shipped a release", "wrote about design") and only name things I have already made public on my page (my own public projects, topics and links). If you are unsure, leave it out - an empty field is fine. Caldera also drops any journal line that looks sensitive before publishing.
- Never read or edit .obsidian/plugins/caldera/data.json - it holds my private key.
- Never remove or change an existing "caldera:" marking without asking me.
In Obsidian: Caldera: Copy AI prompt: make my profile richer.
Or do it by hand: what each convention does
| Add this | To get |
|---|---|
A note in your Garden folder, or caldera: garden in its properties | A full public page in your garden, with stage: (seedling, budding, evergreen) and license: |
caldera: public in a note's properties | The note listed on your profile (title and first paragraph) |
caldera_headline, caldera_focus, caldera_wins in a daily note named YYYY-MM-DD | That day's journal entry |
Caldera/activity.json | Daily counts from outside tools (meetings, emails sent, commits, AI sessions) for your score |
| Command: Share this note with a friend | An encrypted copy in their vault, under Caldera/Inbox/ |
| Commands: Post an ask / Post an offer | The help exchange on your profile and the hub |
Publishing from a server or a scheduled job: the Caldera CLI in the repository (packages/cli, caldera publish --vault /path/to/vault) uses the same settings and identity.
Questions
Do I need Obsidian already?
No. Obsidian is a free notes app (obsidian.md) for Mac, Windows, Linux, iPhone and Android. The install prompt checks for it, installs it if you say yes, and creates your first vault (a folder of notes). Your page starts simple and fills in as you write.
Is it free?
Yes. The plugin, your profile and friends are free and open source. Optional paid features (like a hosted AI journal and custom domains) may come later.
Who can see my notes?
Only what you publish. Your vault is read on your device; Caldera publishes the sections you switch on, notes you plant in your garden (a Garden folder or caldera: garden), and notes you mark caldera: public. Notes you share with a friend are encrypted so only that friend can read them.
What is a digital garden?
A set of notes you grow in public, linked by topic instead of date, and never quite finished. In Caldera each garden note is marked seedling (rough), budding or evergreen (worked through), so readers know how settled the thinking is. Your profile gets a Garden section, and every garden note gets its own page.
How do links between gardens work?
Write [[@handle/Note title]] in a garden note to link to a note in someone else's garden. Their note then shows "Linked from other gardens" with a link back to yours. New and updated notes from every listed garden appear at caldera.social/gardens.
Can AI companies train on my garden?
You choose a license per note with license:. The default is all rights reserved and not licensed for AI training, and those pages tell crawlers so. Pick cc-by or cc0 to allow reuse. Every published note is also hashed into your signed profile, so anyone can check who wrote it and when.
What are help credits?
Points you earn by helping people with their asks. Everyone starts with 100. They have no cash value and can't be bought or sold.
Does it work on mobile?
Yes, the plugin runs on Obsidian desktop and mobile.
Can I host it myself?
Yes. Use Export profile to a vault folder to get a static site for any host, or run your own hub. The protocol is open.
How do I delete my profile?
In Obsidian, run Caldera: Delete my profile from the hub. Your page, friendships, asks, offers, gravity and credits on the hub are erased. Your vault is never touched.
What if I lose my device?
Your identity is a key in your vault's plugin settings. Export the recovery key when you set up, and import it on a new device.