Handoffs

1. Set up Nirvaana in Claude Code first (Nirvaana in Claude Code).
2. Add the handoff hook: npx @nirvaana/mcp handoff --auto after each turn. It does nothing until the next step.
3. In “Settings”, under “Handoffs”, press “Allow” beside each world whose members may take your handoffs.

“Stop” beside a world ends it at any time. A handoff already taken stays with whoever took it.

• The branch, your commits and your uncommitted changes to tracked files, pushed to a hidden place on the repo's own remote. Anyone who can read the repo can fetch it.
• Keys, .env files, certificates, large and binary files are left out, and the hook says what it left out. If a commit holds a file that looks like a secret, it pushes nothing and says why.
• Nirvaana keeps the branch, your computer's name, your open pull requests and the session's own words on what is done and what is next. Never the conversation.
• npx @nirvaana/mcp handoff --close on a branch ends its handoff and takes it off the remote.

In Claude Code, ask to see the handoffs offered to you, and to take one. Your session gets their letter and their changes, and they are told you took it.

In “Settings”, under “Handoffs”, “Auto-accept in auto mode, world by world” lets your Claude Code sessions that run in auto mode take a teammate's handoff for the repo they are in, by themselves. Each one works on a branch of its own, never your teammate's, and your teammate is told who took it.

• Every world starts off. “Turn on” beside a world, and “Turn off” whenever you like. A world you leave is turned off.
• At most one a session, and three a day.
• 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.

Where you see “Live”, it shows what your agents are doing right now: a Claude Code session, a Claude chat using Nirvaana, or one of your automations, a few words a step, such as “Editing a file” or “Running tests”. Your own coding sessions and the desktop app's runs also get “Pause” and “Stop”; it never steers them.

• Open one of yours and press “Pause” or “Stop”, or use “Pause all” and “Stop all” above the list. Stop asks once more first. “Resume” undoes either.
• A run the desktop app is doing stops at once, or holds where it is until you resume. On Windows a run can't be held, so a paused one carries on until it finishes; Stop still ends it.
• A coding session in a terminal, Claude Code's or Codex's, can't be interrupted from outside in the middle of a turn. Paused, nothing you send it from Nirvaana reaches it until you resume. Stopped, it finishes the turn it is on, what was waiting for it is cancelled, and it takes nothing more from Nirvaana until you type in that terminal again.
• Only you can press them, on your own sessions. A teammate who sees yours on Live never gets the buttons.

One world's agents

Live can show one world at a time. On the web, the chips above the list say “Every world”, then each world with agents running now and how many; choose one to see only its agents and its projects. In the desktop app, open a world in the sidebar and Live shows only that world's; close it (its ×) and Live shows them all again, as it does under Your world.

• An agent is in a world when it is a step of a project started in that world, its task was sent from that world's chat, it runs an automation shared with that world, or it works in a GitHub repo that feeds that world. Nirvaana never guesses: an agent that fits two worlds, or none, shows only under Every world.
• A teammate's agent is placed only by its repo, and only in a world they are in and share at least its titles, repo and branch with.
• “Pause all” and “Stop all” reach every world, so they show only with every world. With one world open, open a session to pause or stop it.

The desktop app's sidebar also shows a small ring and a number beside each world that has agents working or waiting on their person, and nothing beside a world with none. It follows Live's own stream while the app is in front.

• For Claude Code, add the hooks: npx @nirvaana/mcp setup --hooks. It sends never what you type, your code, or a command beyond its program's name.
• Only you see yours, until you choose a world in “Settings”, under “Privacy”, then “Live”: nothing, that your agents are working, their titles, repo and branch, or every step. What it shows is gone after a day.

new

Tell the chat what you want built or fixed in one of your projects, in your own words. Nirvaana plans it like a good developer would, and your own coding app does the building on your computer, on your own plan: Claude Code, Codex or Gemini CLI. Nirvaana doesn't replace them: it adds the plan, the checks, a second pair of eyes, and your Approve.

“add a contact form to my site”

1. A project card shows the steps, who does each one, and what each may do. Nothing starts until you press “Approve”. To change the steps, say what to change in the chat: the new plan replaces the old card.
2. Each step works in its own copy of your project, never straight into your main version.
3. Then, on its own: it runs your project's tests and style checks, and a second agent that didn't write the change looks it over for bugs, security problems and anything more complicated than it needs to be. It says “Ship it” or “Fix first”.
4. It checks speed too: a database lookup with no index, a picture over 500 KB that should be WebP or AVIF, and a loop that asks once per item instead of once for all. Each comes with its fix in plain words. Speed alone never holds a change up: it's listed in the change request, and fixed in a fix round when there is one.
5. On fix first, or when a check fails, it fixes what was found and checks again: two rounds at most. After that you decide: “Open a change request anyway”, or “Stop”.
6. It opens a change request (a pull request on GitHub: the changes, put up for you to look over before they go in), with a plain summary.
7. Putting the changes into your main version waits for you: press “Approve” and confirm it's you with Touch ID or Windows Hello where you added it, or your authenticator's code or your password (or, if you have no authenticator and no password, a code we email you, even where you added Touch ID or Windows Hello). You can undo it later with GitHub's Revert button on the change request.

If a teammate's part comes after it's live, the card shows the message for them once the changes are in, and “Send to” them is yours to press. At the end, the card sums it up: what got built, what went out, the test results, the review, the change request, where to see it, and anything still waiting on you or a teammate.

One request, many kinds of work

A project can mix coding agents, agents in your apps, and teammates. The card shows who does each step, and a project that builds nothing has no coding step and nothing to merge.

“launch the bakery's online ordering: the order page, the announcement email, and ask Maya for the menu photos”

1. A coding agent builds the order page, in its own copy of your project, as above.
2. An agent in your apps works on your computer in an empty folder of its own, with nothing but Nirvaana: it can't open your files. It uses only the apps and actions its step shows on the card (like “Reads your Gmail” or “Drafts in Gmail, unsent”), only apps you let your AI use on Your connections, and Nirvaana holds it to them. It reads on its own. Anything it would make or send in an app (a draft, an email, an issue, a comment, an event with guests) waits as a card under “Before it goes out”, with everything it would send and its own “Approve”; the project shows it under its step.
3. A teammate's step goes only to someone you already share a world with: never a guess, and never anyone new. If a name could be two people, Nirvaana asks which. Sending the message is yours to press, and a promise keeps track of it. The step counts as done when they mark that promise done, or when you say so.
4. “Live” shows the project as a header with one row per step: what each agent is doing, the apps it may use, what waits for your Approve, and who it's waiting on. At the end, one summary says what got built, what went out on your Approve, and what is still waiting on someone.

Starter templates

Three templates start a project for you: “Launch a product”, “Weekly team update” and “Build a site”. In the chat, type “/template” and pick one, or press “Start it” on one under “A first project” at the end of setting up.

1. The box starts with the template's first sentence (“Start from the “Launch a product” template.”): say what it's for after it, and send. Nirvaana plans nothing until you send it.
2. Nirvaana plans it from the template and your words, and the project card shows the steps. Nothing starts until you press “Approve”, and anything that would go out waits for its own “Approve”.

• “Launch a product” builds a one-page site, drafts the announcement in your email, unsent, and asks a teammate you name to look it over.
• “Weekly team update” reads your week in your apps, asks a teammate you name for their news, and drafts the update.
• “Build a site” builds the pages you describe, with tests.

Start from a template. The chat opens with its first sentence written: say what it's for, and send. Nothing starts until you press Approve on its card.

Preview, in the Mac and Windows app

In the Mac and Windows app, “Preview”, on a project in “Live” that builds something, shows what it built, inside the app.

• “On this computer” shows the project's own page from its copy here: its dev script (npm run dev) if it has one, else a plain index.html as it is, else npm start, as you'd run it yourself. A dev script is asked to listen on this computer only, and Preview checks that it does: if the project's dev server opens itself to the network, Preview stops it and says so.
• “Its change request” shows the preview address GitHub lists for the change request, where a host such as Vercel or Netlify adds one.
• It's a picture of the page, taken out of sight, so no window opens, at a computer's or a phone's size: “Refresh” takes a new one, and “Stop the preview” ends what it started.
• It shows only your own projects, and nothing on the page can click, sign in or open anything in the app.

The AI that does the work

A project's agents run on Claude Code, Codex or Gemini CLI: your own app, signed in on your computer, on your own Claude, ChatGPT or Gemini plan. Nirvaana never reads or sends its sign-in. Whichever it is, each step works in its own copy of your project, with only the tools its step shows on the card, and anything that would go out still waits for your “Approve”.

1. On the project's card, before you press “Approve”, choose “The AI that does the work”. “Your computer's choice” uses the one chosen in the Nirvaana app's Settings on that computer. Only an app installed on one of your computers is offered, and a computer whose Nirvaana app is too old to say which it has offers none. Changing it means pressing “Approve” again for the card as it is now.
2. Codex only builds and fixes. It never gets Nirvaana's connection to your apps, because its commands can read your whole computer, so planning, the review and any step that uses your apps or Nirvaana's tools run on Claude Code, or on Gemini CLI where Claude Code isn't installed. A plan that builds nothing doesn't offer it. On your computer, Codex never works at the same time as a step that holds Nirvaana's connection: one waits for the other, and says so. A plan waits at most two minutes, then the project says a Codex run is still working on your computer, so you can let Nirvaana plan it instead, or try again when Codex ends. Stop ends a wait at once.
3. Gemini CLI gets Nirvaana's connection to your apps only in Nirvaana's own empty folder, never inside your project, so a building step that needs your apps runs on Claude Code. In your project it runs only where you've trusted the folder in Gemini CLI.
4. If the one chosen isn't installed on the computer that takes a step, or can't do that step, another one does it. Each step says which ran it, on whose plan, and why.

Start a project from your phone

In the Nirvaana app on your iPhone, under Projects on Work, press “Start a project”. Say what you want built (or pick a starter template, when the app shows them), choose “The AI that does the work” if you like, and press “Start”. Your computer plans it on your own plan (Nirvaana plans it when none of your computers is on), and your computer does the work. The phone never approves for you: when the plan is ready, press “Approve in Nirvaana” and press “Approve” on the project's card there.

When something goes wrong: Fix it

The card says what went wrong in one plain sentence: the tests or the style checks don't pass, two parts of the work changed the same lines, something couldn't be installed, git isn't set up, your computer's sign-in to GitHub ran out, Nirvaana on your computer had to sign in again, your Claude plan reached its limit, your computer didn't answer, or the reviewer still asks for changes. Under it, one line says what “Fix it” will do, and nothing happens until you press it.

• After the two fix rounds, or when the changes can't go into your main version because it changed in the same places, “Fix it” adds one more fix step on your computer for exactly that, then checks and reviews again. If they pass, the change request is opened or updated on GitHub, as your plan said. Your main version isn't touched. Twice at most for a project: after that, the card says so, and you can “Open a change request anyway” or “Stop”.
• Otherwise it tries the step again, or lets Nirvaana plan it when your computer didn't answer. Where something has to happen on your computer first (installing git, signing in to GitHub again, or getting it online), the line says so. When your Claude plan reached its limit there is nothing to press: press “Try again” once it has reset (Claude says when).
• A Fix it that would send the project's copy to GitHub asks you to press “Approve” first.
• A task you sent to your computer from the chat that went wrong says so too. Its “Fix it” puts a message in the chat box for you to send, and Nirvaana plans the fix as a project, with its own Approve. A task no computer has picked up for a while offers “Open Settings”, to see which of your computers are connected.

Undo the last step

When your computer has told Nirvaana where a step started (a snapshot of the project just before it), the card shows “Undo the last step” for the newest step that changed the project's files: a build step, a fix, or the merge. Checks, reviews and change requests change no files, so they are never the step undone. It shows once nothing of the project is running; while a step runs, the card says to stop it first. Press it, read what it will do, and press “Approve”: your computer puts the project's own copy back as it was just before that step, the next time it's on, and the card says how it went. Earlier steps, your main version and anything already on GitHub stay as they are.

If the last step was the merge into your main version, Undo doesn't rewrite it. You confirm it's you, and your computer opens a change request that takes those changes back out. Your main version keeps the changes until that change request goes in, which it does on the card, when you press “Approve” and confirm it's you again: there is nothing to do on GitHub.

• Every card has a way on. If a step doesn't finish, press “Try again”. If your computer doesn't answer with a plan, press “Let Nirvaana plan it”. You can press “Stop” at any time, and the work so far is kept in its own copy.
• Before you approve the merge, “Don't” leaves your main version as it is: the change request stays open on GitHub, and the project stops.
• Anything you paste with your goal (an error, an email, a page) is read as information, never as orders.
• Each step can do only what the card shows, and anything that would leave your computer still waits for your Approve.