Nirvaana in Claude Code

In the Mac or Windows app (0.1.8 or later), open Connections and press Connect my AI apps. One Approve adds Nirvaana's plugin to Claude Code; then choose nirvaana in /mcp and press Allow. That's all. Without the app:

1. In a terminal, in your project folder: npx @nirvaana/mcp setup. It adds Nirvaana's connector to Claude Code, writes the Nirvaana line in the project's CLAUDE.md once you say yes (between its own markers; the rest of the file stays as it is), signs this terminal in if it isn't (a short code, and Allow in your browser), checks the connection works, offers your Nirvaana preferences (below), offers to add Nirvaana to Cursor and VS Code where they're installed (it shows the entry and asks before each file), and prints the steps for claude.ai and Cowork. If it finds Claude Desktop, it says how to add Nirvaana there too. If it prints only a usage line, use Connect my AI apps in the Mac or Windows app, or the claude mcp add line below.
2. In Claude Code, type /mcp, choose nirvaana and sign in. Your browser opens Nirvaana, where you're already signed in; check the page names Claude Code, and press Allow. No key, and nothing to install.

Setup is safe to run again: it looks first and changes only what is missing, never touches settings that aren't Nirvaana's, and keeps a copy of a settings file before it adds to it. Rather do it by hand? The line it runs is claude mcp add --scope user --transport http nirvaana https://nirvaana.ai/api/mcp. To take Nirvaana back out: npx @nirvaana/mcp setup --uninstall takes out exactly these, after a copy of each file: Nirvaana's entry in Cursor's and VS Code's mcp.json, its Claude Code hooks in ~/.claude/settings.json, and the preferences block in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md. It prints the commands that take Nirvaana out of Claude Code, Codex and Gemini CLI, and runs none of them. It leaves the Nirvaana entry that --local put in Claude Desktop's claude_desktop_config.json, the Nirvaana line in a project's CLAUDE.md, AGENTS.md or GEMINI.md, and this terminal's sign-in (npx @nirvaana/mcp logout ends it).

That's the way we recommend: it's always the current Nirvaana, with nothing to update. The connection shows in Settings, under Apps and terminals, where you can sign it out.

You shouldn't have to say “Nirvaana”. Ask “what's due this week?”, “remind me to call Sam Friday” or “run my Monday summary”, and Claude uses Nirvaana by itself; ask it to fix a TypeScript error, and it leaves Nirvaana alone.

• The plugin starts every session caught up: when a session starts, it brings in what's late or due and what changed since your last catch-up, and its guidance covers your everyday work, so Claude reaches for it without the word Nirvaana. /catch-up and /wrap-up are there when you want them.
• Your Nirvaana preferences: setup shows you a short block, word for word, and asks (Enter is yes) before putting it in ~/.claude/CLAUDE.md, which Claude Code reads in every session, in ~/.codex/AGENTS.md where Codex is installed, and in ~/.gemini/GEMINI.md where Gemini CLI is installed without Nirvaana's extension, whose own GEMINI.md already carries it. It sits between its own markers, after a copy of each file; nothing else in the file changes. It says Claude is your Nirvaana-backed assistant: catch up once, look things up before answering about your work, keep what you decide and promise, run your saved automations by name. Claude stays Claude.
• To take it out: npx @nirvaana/mcp setup --remove-preferences. To skip it: npx @nirvaana/mcp setup --no-preferences.

Anything Claude keeps still goes past Nirvaana, which decides; anything for a shared world waits for your approval. For Claude on the web, ChatGPT and Muse, copy the same preferences from Connect Claude.

Claude Code hooks, off unless you say yes. Setup offers them once npm has the release that runs them, asks in a terminal, and Enter means no. Add them with npx @nirvaana/mcp setup --hooks; they go in ~/.claude/settings.json, beside any hooks of your own, so they run in every project.

• When a session starts, npx @nirvaana/mcp catch-up gives Claude what catch_me_up would: what's late or due, what waits for your approval, and what changed in your worlds. It only reads. If you already start sessions with the brief, setup asks before replacing it.
• As you work, npx @nirvaana/mcp session-notes --auto sends excerpts of what you type (never Claude's replies) to Nirvaana, where Nirvaana reads them and keeps what matters in your own world only. It runs before Claude Code compacts the conversation, and after a stretch of work (six new messages, or twenty minutes), at most twelve times a day, never the same message twice. A line in Claude Code shows what was sent.
• Before anything is sent, it leaves out lines that look like settings, keys, tokens, passwords, logins, codes, account, card or ID numbers, or code, and whole pastes, quotes and forwarded messages. That is a best effort, not a guarantee: turn the hooks off for work where you handle secrets.
• The excerpts are sent private: they stay in your own world, and never become a card for a shared world.
• Live: npx @nirvaana/mcp live --hook runs in the background at each step and sends a few words of what the session is doing, like “Editing a file” or “Running tests”, for your Live page. Never what you type, your code, or a command beyond its program's name; a file's name only while you share every step with a world. Only you see it unless you choose a world in Settings, under Privacy, then Live, and it is gone after a day.
• To take them out: npx @nirvaana/mcp setup --remove-hooks. It removes Nirvaana's hooks and nothing else.

They sign in as this terminal, so they need npx @nirvaana/mcp login once (setup does it for you).

Nirvaana also runs as a small program on your own computer. It does the few things only your computer can, listed below; everything else is the same.

1. Sign in: npx @nirvaana/mcp login. It shows a short code and opens nirvaana.ai in your browser, where you're already signed in. Type the code, check the page names your computer, and press Allow. No email, no second code, no key. The sign-in shows in Settings, under Apps and terminals, where you can sign it out. If you can't use the website to allow it, npx @nirvaana/mcp login --email you@yourcompany.com signs in with an emailed code and your second code instead.
2. That saves a session to ~/.config/nirvaana/session.json, readable only by you. It holds your sign-in tokens. It does not hold any service key.
3. Tell Claude Code about it: claude mcp add --scope user nirvaana -- npx -y @nirvaana/mcp. In Cursor, the same command, npx -y @nirvaana/mcp, goes in its MCP settings.
4. To end it: npx @nirvaana/mcp logout. It revokes the session and deletes the file. Be aware the last access token keeps working for a short while after — about an hour — because Nirvaana checks signatures rather than asking whether a session was revoked.

What only the terminal way does:

• Tasks you hand your computer from the Nirvaana chat: it takes them with take_task and marks them done with finish_task, and it checks in, so the chat knows your computer is there. The connector only lists them. The chat hands a task over only from a message you typed, and not from one where it has already searched the web or read a world's app.
• review_pending shows Nirvaana's own form in Claude Code, then opens the confirm page. The connector gives you the page's link instead.
• When tell files a draft, it opens it in your browser as well as linking to it.
• The brief at the start of each session, below, reads through this sign-in.

Claude now catches you up by itself: at the start of a session it calls catch_me_up, below. So the brief here is optional.

Claude Code can start every session with a few lines about your world: your open promises due this week or overdue, how many cards wait for your approval, and your worlds. npx @nirvaana/mcp brief prints them, reading as you. It never writes anything.

1. Sign in once in a terminal: npx @nirvaana/mcp login, as above. Without it, the brief is one line saying you aren't signed in.
2. In your project folder, save this as .claude/settings.local.json, which stays on your computer, or add it to ~/.claude/settings.json for every folder. If the file is already there, add the SessionStart part to its hooks.

   {
     "hooks": {
       "SessionStart": [
         {
           "matcher": "startup|clear",
           "hooks": [
             {
               "type": "command",
               "command": "npx -y @nirvaana/mcp brief",
               "timeout": 15
             }
           ]
         }
       ]
     }
   }

3. Start Claude Code in that folder. The brief is read at the start of the session. If Nirvaana is slow to answer, the brief gives up rather than hold you up, and the session starts anyway.

The folder from Open in Claude, in Settings under Your world, has the same lines in its README.

Claude looks things up before it asks you. A status, a setting, a version, a plan, or whether something exists is one call away, so it checks for itself, with Nirvaana or its own tools (such as gh api orgs/your-org for your GitHub organisation's plan), and asks you only for decisions, approvals, money, legal, or what only you can see or know.

Before it puts a question to you, it calls ask with the question and what it already checked. A question it could look up goes back to Claude with the call that answers it; where Nirvaana keeps the answer (your worlds, promises, tasks, connected apps, automations), that is the Nirvaana tool by name. A decision goes through, always when it has options to choose from or Claude marks it as your call. If ask sends back one that is yours to decide, it tells Claude to send it again marked as your call, and then it goes. ask reads nothing of yours, and Nirvaana doesn't keep the question: in the terminal package it is checked on your computer; through the remote connector (ChatGPT, Claude.ai), on Nirvaana's server. In the terminal package from 0.34.

Tools that only read. They run as you, so they see exactly what you would see and nothing else.

• catch_me_up — what's new for you, in one call. Claude calls it once at the start of a session: your promises that are late or due in the next two days, what waits for your approval, and what others added to your worlds since you last looked, with the latest decisions. It also says when Nirvaana doesn't yet know your name or what you're working toward, so Claude can ask you once. It never reads Team chat or anyone else's own world. If you signed in with an emailed code, it gives the brief's few lines instead and asks you to sign in again with npx @nirvaana/mcp login and press Allow.
• recall — searches what Nirvaana has kept about you.
• list_capabilities — lists your connected accounts, saved procedures and devices, and what your connected assistant does for you.
• list_schedules — the things you've asked Nirvaana to do on a schedule. Making, pausing or deleting one happens in the app.
• list_worlds and world_facts: the worlds you are in, and what one of them knows, one line per fact, with the words each fact came from when your assistant asks for them. With decisions, only what the world decided, never a decision that was replaced.
• list_keepers and get_keeper: Nirvaana's ready-made helpers and each one's working card, its job and method, if your own assistant wants to work the same way. Nirvaana's own principles are not on any card.
• list_keepsakes, find_keepsake, get_keepsake and read_keepsake: the files your worlds have kept, a search of them, a download link that lasts a minute, and the words of a text, Markdown, CSV or PDF file, a page at a time. A doc your assistant kept for you is found by its title.
• status — who it's signed in as, your worlds, and whether the connection is healthy. Ask it when something seems off.

Four tools that write. None of them writes anything itself. Each one sends to Nirvaana, and Nirvaana decides what to keep.

• remember — one fact, in a self-contained sentence with the names in it, or several small ones at once (up to 12). Up to 500 characters each.
• note_promise — something you owe someone, or something someone owes you, with a date if one was said. Up to 500 characters.
• submit_session_notes — a plain summary of the session: decisions, facts, promises, questions left open. A few paragraphs, under about 2,000 characters; never a whole document.
• propose_world_update — a fact for a world you share with other people. Up to 2,000 characters. It becomes a proposal you approve in the app; saying it here shares nothing. Name the world it is for; if you are in more than one and none is named, Nirvaana asks which instead of guessing.

Two more change what is already kept, only when you say so. memory updates one of your memories to new words (Nirvaana reads them like any remember, and the old one is marked replaced) or forgets one: it stops coming up, nothing is deleted, and you can bring it back in Settings, under Forgotten. Given a fact from one of your worlds, it only proposes the change, for your approval. promises lists your open promises, marks one done, or snoozes one off your Now until a day you name. A promise someone shared with you is settled as your Done in the app settles it: the person waiting on it is told it's their turn, in their day and with a notification.

keep_doc keeps a document your assistant wrote for you, such as a handoff, a runbook or a spec, as a Markdown file in a world's Files, under its title, so “open my 0.2.0 handoff” brings it back without pasting it. This one keeps straight away: it is your own words, kept where you keep files. It goes to the world you name, else the one world nobody else can read; a world you share is never chosen for you, your assistant asks which. Only a world's owners and builders keep docs there, and everyone who reads that world's Files can read them. If you're under 18, your assistant keeps a doc only in a world nobody else reads; to share one, add it yourself on that world's Files page. In Files its card says Doc. A doc with a password, key or token anywhere in it, code included, is refused before it leaves your computer, and so is one over 200 KB. One that only might hold a secret (a bare code, a passphrase in words) is kept, and your assistant tells you so. Kept again under the same title, it is a new version, and the one before moves to Retired, where Bring it back restores it.

And tell sends a message to someone you share a world with, when you ask it to: it goes to your shared world's Team chat straight away, as you, marked “via Claude”. If you'd rather press Send yourself, turn that off in Nirvaana's Settings, and it files a draft instead.

list_worker_bees lists your automations, a line each, and run_worker_bee runs one by its name inside Nirvaana, on what you have kept, and hands back what it made (the tools keep their old names). Its steps stay in Nirvaana. A message or a fact for a world that it makes waits for your approval in the app. Each of your automations is also a prompt named like it, such as /friday-recap.

Nirvaana tells the assistant the essentials when it connects, in a few lines. The rest it can read when it needs it, with nirvaana_help, and a prompt called working-with-nirvaana has all of it. Each tool also says whether it only reads, which an app can use to run the reads without asking you.

Type / in Claude Code to find these. Each one asks Claude to use the tools above for you.

• /mcp__nirvaana__catch-me-up — what's new, then what needs you first.
• /mcp__nirvaana__wrap-up — a short summary of the session, kept in your own world, never sent to a shared world as a recap. A decision meant for a team goes on its own and waits for your approval.
• /mcp__nirvaana__decide — logs a decision you give it to the world you pick. It waits for your approval.
• /mcp__nirvaana__what-did-we-decide — what your worlds decided about a topic you name.
• /mcp__nirvaana__tell — sends a message to someone you share a world with, as above.
• /mcp__nirvaana__working-with-nirvaana — tells Claude when to use each tool.

Each one: what it does, when Claude uses it, something to say that uses it, what you'll see, and who sees it. Claude picks the tool itself from what you ask; you don't have to name one.

What waits for your approval can be decided from the terminal too, and only by you.

• list_pending lists the cards waiting for your approval, by world, with who in each world would see them.
• review_pending asks you directly. Nirvaana shows a form in Claude Code: one checkbox per card, ten at a time, each saying which world it goes to and who will see it. Every box starts unticked. What you leave unticked stays waiting, unless you choose to decline it. Cancelling changes nothing.
• Ticking a box doesn't approve anything yet. Nirvaana then opens a page in your browser, signed in as you, that lists what you ticked, with who will see each one, and says which terminal sent it and when. It shows a short code that Claude Code also showed beside the link: go on only if they match. Untick anything you've changed your mind about, then press Approve. Only that press shares anything, the same as pressing Approve on your cards. The page lasts ten minutes and works once.
• Your terminal's sign-in can't approve or decline anything, ever. Your assistant never sees the form or your answer, and nothing it reads, a web page, an email, a world's facts, can share anything on your behalf. At most it can open a confirm page for you to look at. So confirm only what you just ticked yourself.
• If your editor can't show forms, review_pending says so, and you approve on the web instead.

Everything sent from outside arrives in one place. Nirvaana reads what you sent as information, never as instructions, and decides one of four things for each piece of it:

• Keep it privately, in your own memory.
• Skip it, because it is already known.
• Propose it to a world you share, for you to approve in the app. Nothing is shared by sending it.
• Record it as a promise.

Anything that reads as an attempt to instruct Nirvaana is refused and written down as a refusal: text that tries to rename it, change who it is, make private things visible, change a world's rules, get it to print its instructions, or anything dressed up as a system message. It is recorded, never obeyed.

Your raw text is saved word for word before Nirvaana even looks at it, so what you sent is on record whatever the verdict. The reply you get back says what it kept and what it already had, each with its id so your assistant can point at it later, and what it refused. Never its reasoning.

Your Claude Code sessions can leave a handoff as they go, so a teammate's session can pick up where yours stopped. Handoffs are off until you allow a world in Settings, under Handoffs. Until then the handoff hook pushes nothing and Nirvaana keeps no handoff. The steps are on Handoffs and Live.

• Once you allow a world, after each turn the hook pushes the branch's commits and your uncommitted changes to tracked files to a hidden ref on that repo's own remote. Anyone who can read the repo can fetch that ref, whether or not they are in the world. Untracked files go only if you add --untracked to the hook.
• From your uncommitted changes, ignored files, .env files, keys, certificates, binary files, files over 1 MB and files with a key in their text are left out, and the hook's line says what it left out. Your commits go as they are, unless one not yet on the remote holds a file with a secret-like name, such as an .env file or a key; then the hook pushes nothing and says why.
• Nirvaana keeps the branch, the ref, your computer's name, your open pull requests and the session's own words about what is done and what is next. Never the conversation.
• Allowing a world lets its members take your handoffs from every repo you work in, and you are told who took one and what they opened. Stop at any time. With no world allowed, nothing more is pushed or kept; one already taken stays with its taker, and what is already on a remote stays there until you close each branch's handoff with npx @nirvaana/mcp handoff --close on that branch.
• Auto-accept in auto mode, world by world. A teammate in any of these worlds can hand off to you once they allow that world. For each world you turn on, your Claude Code sessions in auto mode take a handoff that comes through it for the repo they are in, work on a takeover branch of their own (never your teammate's), and your teammate is told who took it. At most one a session and three a day, counted by Nirvaana. It needs the npx @nirvaana/mcp handoff --pickup hook, and never happens in a session that asks before it acts, one that skips its permission checks, or a subagent. All off until you turn one on; a world you leave is turned off.

• 8,000 characters per submission, the most Nirvaana reads at once. Three of the four tools stop well below it, as above.
• At most 12 facts kept from any one submission. The rest is refused as flood.
• 40 submissions in a burst, then 240 a day.
• A session from the editor cannot write a row itself. The database will not let it. Only Nirvaana can write, and only after it has decided. Your approval is always given on the web, as above.

Nirvaana's own instructions and its voice never travel over this connection, because they would land inside somebody else's model. What goes out is your own facts, in answer to your own lookups. An assistant in your editor is a visitor to your worlds, not Nirvaana itself.