virwave-breathe

# VirWave Breathe

Calm, animated breathing sessions from the [VirWave](https://virwave.com) app, as an MCP server. Ask for a breathing break and you get a session paced to your breath. In Claude Desktop the session appears in the chat itself; elsewhere it opens in your browser. Either way it waits for you to press Begin.

It runs on your computer, makes no network requests, and collects nothing. It works with Claude Desktop, Claude Code, and any other MCP client that can start a local server.

## Install

You need [Node.js](https://nodejs.org) 18 or newer for the `npx` routes. The Claude Desktop extension uses the Node.js that comes with Claude Desktop.

**Claude Desktop, as an extension**

1. Download `virwave-breathe.mcpb` from the [latest release](https://github.com/virwave/virwave-breathe/releases/latest).
2. In Claude Desktop, open Settings, then Extensions, and drag the file in (or double-click it).
3. Choose Install. The options let you keep sessions in the chat (the default) or send them to your browser, and choose whether and where session pages are saved.

The first time a session appears in the chat, Claude asks for permission to show it. Choose "Always allow" and later sessions appear straight away.

**Claude Desktop, by hand**: add this to `claude_desktop_config.json` (Settings, Developer, Edit Config), then restart Claude Desktop.

```json
{
  "mcpServers": {
    "virwave-breathe": { "command": "npx", "args": ["-y", "virwave-breathe"] }
  }
}
```

**Claude Code**

```bash
claude mcp add virwave-breathe -- npx -y virwave-breathe
```

For any other MCP client, the command is `npx -y virwave-breathe` (stdio).

**Claude on the web, iPhone, and Android, with nothing to install**

VirWave Breathe is also hosted, at one address:

```
https://xswebtvkueusdaeboizp.supabase.co/functions/v1/breathe
```

In Claude (on a paid plan), open Settings, then Connectors, choose "Add custom connector", give it the name VirWave Breathe and that address, and add it. It needs no sign-in. The same address works in ChatGPT with developer mode on, and in any MCP client that connects to a URL. See "Hosted" below for what is different.

## What to say

- "I need a breathing break."
- "I feel wired and I have five minutes. Can you match me a breathing session?"
- "Start a box breathing session for two minutes."
- "Which breathing patterns don't hold the breath?"
- "I'd rather watch something move than follow a line. Start a ripple session."

In Claude Desktop the session appears in the chat, as a card you can expand to fill the window. In a client that can't show it in the chat, it opens in your default browser. In Claude Code, Claude publishes it as an Artifact instead. Every way, it opens at rest and only starts when you press Begin.

## Tools

| Kind     | Name                 | Does |
| -------- | -------------------- | ---- |
| Tool     | `start_session`      | Matches a session to how you are, what you'd like instead, and how long you have (2, 5, 10, or 15 minutes). Moves through stages at one steady pace, with no breath holds |
| Tool     | `breathe`            | Creates a session from a pattern and shape you choose, for a number of minutes or breath cycles |
| Tool     | `list_patterns`      | Lists the patterns: phases and seconds, what each is good for, its shapes, and whether it holds the breath |
| Resource | `virwave://patterns` | Same data as `list_patterns` |
| Resource | `virwave://shapes`   | The seven shapes, a plain line on each, and the patterns each draws |
| Resource | `ui://virwave-breathe/session-<fingerprint>.html` | The session as it appears in the chat (an MCP Apps view). One fixed page for every session |
| Prompt   | `breathing-break`    | "Here's how I feel and how long I have": matches a session (or picks a hold-free pattern) and starts it |

`list_patterns` only reads. When the session is shown in the chat, `breathe` and `start_session` write nothing. Otherwise each saves one new HTML file (the session page) on your computer and, unless you turn it off, opens it in your browser. They never change or delete anything. The tool result always says which happened: "Shown in the chat", "Opened in their browser", or the file path.

With no arguments, `breathe` plays the app's own default session: In & Out, 4 seconds in and 8 seconds out, with no breath holds, drawn on the circle (`DEFAULT_BREATH_CONFIG`).

## Settings

| Setting | Extension option | Environment variable | Default |
| ------- | ---------------- | -------------------- | ------- |
| Show sessions in the chat | "Show sessions in the chat" | `VIRWAVE_INLINE`: `auto`, `on`, or `off` | `auto`: in the chat when the client supports it, in the browser otherwise |
| Save a copy of sessions shown in the chat | "Also save the session page to a folder" | `VIRWAVE_SAVE_COPY` (`true` turns it on) | Off |
| Open sessions in the browser | "Open sessions in my browser automatically" | `VIRWAVE_OPEN_BROWSER` (`false` turns it off) | On |
| Where session pages are saved | "Where session pages are saved" | `VIRWAVE_SAVE_DIR` | A `VirWave Breathe` folder in your computer's temporary files |

How the server decides: a client that can show MCP Apps says so when it connects (`capabilities.extensions["io.modelcontextprotocol/ui"]`, as the MCP Apps specification sets out). With `VIRWAVE_INLINE=auto` the server follows that: such a client gets the session in the chat, with no browser and no file, and every other client gets exactly what version 1.0 gave. `off` sends every client to the browser. `on` answers for the chat view even if the client didn't say it supports it. The browser and folder settings apply whenever the session is not shown in the chat; the folder also applies to saved copies.

The temporary folder is the default because it needs no permission prompt, keeps your own folders tidy, and is cleared by the system. When opening is off, or a browser can't be opened, the tool result says so and gives the file path instead. When a caller passes its own `out_dir` (as Claude Code does, to publish an Artifact), the browser is left alone.

The hosted server has none of these settings: it saves nothing and opens no browser (see "Hosted").

## Safety

Sessions are for relaxing and resetting. They are not medical care, and nothing here is described as treatment. The server's instructions and the `breathing-break` prompt follow the app's own rules (`src/domain/distressProtocol.ts`):

- Patterns with no breath holds come first. A pattern with a hold is only offered when the person asks for one or says holds feel comfortable for them. Matched sessions (`start_session`) never hold the breath at all.
- No breath holds for anyone who says they're panicking, distressed, dizzy, or pregnant, or who mentions a heart or breathing condition. They get In & Out with a long breath out instead.
- Anyone who feels lightheaded is told to stop and breathe normally.
- Anyone in crisis is pointed to local emergency services or a crisis line, not a session.
- The page never starts by itself. It waits for Begin.

`test/instructions.test.ts` fails if any of these lines go missing.

## Accessibility

- **Reduced motion**: when your system asks for less motion, the rings hold still, the particles and sweep stop, fades are instant, and each shape shows its still version. The countdown and phase text still guide the breath.
- **Screen readers**: phase changes are announced, every button has a label, and the decorative drawing is hidden from assistive technology.
- **Keyboard and voice control**: every control is a real button with a visible focus ring, and Space begins, pauses, or resumes. This holds inside the chat too, and the chat view never pulls the keyboard away from the message box.
- **Not colour alone**: phases are always named in text, and counts can be switched on or off.
- **Dark by design**, with text on frosted surfaces for contrast. There is no sound.

## Privacy Policy

VirWave Breathe, as an extension or through `npx`, runs entirely on your computer. The hosted server is covered at the end of this section.

- **Data collection**: none. The server collects no personal data, no usage data, and no analytics. It has no accounts and no sign-in, and the extension and the `npx` command make no network requests.
- **Usage and storage**: the tools use only the choices passed to them (pattern, shape, and length, or the feeling, goal, and minutes for a matched session) to build the session page. A session shown in the chat writes nothing. Otherwise the only thing written is that page: an HTML file saved on your computer in the folder you chose (by default a `VirWave Breathe` folder in your temporary files). Your choices are not logged or kept anywhere else. The page, and the view in the chat, load nothing from the internet and store nothing in your browser. The chat view declares an empty list of allowed internet addresses, so the client blocks it from the network as well.
- **Third-party sharing**: none. Nothing leaves your computer. The finished screen has a "Get the VirWave app" link, which opens the App Store or Google Play page only if you choose it, with no tracking parameters. In the chat, Claude asks you to confirm before it opens. Those stores have their own privacy policies.
- **Data retention**: VirWave keeps nothing, because it receives nothing. Session pages stay on your computer until you delete them or your system clears its temporary files.
- **Contact**: [info@virwave.com](mailto:info@virwave.com)

VirWave's full privacy policy: <https://virwave.com/privacy/>. Terms: <https://virwave.com/terms/>.

**The hosted server** (see "Hosted") is the same code at an address on the internet, for Claude on the web and phones and for ChatGPT. What changes: your assistant's requests to it (the tool's inputs: pattern, shape, and length, or feeling, goal, and minutes) travel to that server, which builds the session and sends it back, and a session opened from its link is fetched f