# 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 that opens in your browser and 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`.
2. In Claude Desktop, open Settings, then Extensions, and drag the file in (or double-click it).
3. Choose Install. You can set two options: whether sessions open in your browser automatically, and where session pages are saved.

**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).

## 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 opens in your default browser. In Claude Code, Claude publishes it as an Artifact instead. Either 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 |
| 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. `breathe` and `start_session` each save one new HTML file (the session page) on your computer and, unless you turn it off, open it in your browser. They never change or delete anything.

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 |
| ------- | ---------------- | -------------------- | ------- |
| 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 |

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.

## 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.
- **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 runs entirely on your computer.

- **Data collection**: none. The server collects no personal data, no usage data, and no analytics. It has no accounts and no sign-in, and it makes 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. 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 loads nothing from the internet and stores nothing in your browser.
- **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. 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/>.

Your conversation with Claude, or with any other assistant you use this with, is covered by that product's own privacy policy, not this one.

## Licence

[MIT](LICENSE), copyright 2026 VirWave OAM, Inc.

The published bundle includes these parts of the VirWave app's code, under the same licence: the breathing engine (`src/engine/breathingEngine.ts`), the rhythm, timing, breakdown, shape, and session-matching data from `src/domain/`, and a snapshot of the design tokens the session page uses (`src/theme.generated.ts`). It also bundles the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and [zod](https://github.com/colinhacks/zod), both MIT, with their dependencies. The rest of the VirWave app, the VirWave name, and the logo are not covered by this licence.

Support: [open an issue](https://github.com/virwave/virwave-breathe/issues), or write to [info@virwave.com](mailto:info@virwave.com).

---

# How it works

The rest of this page is for people working on the package.

## Matched sessions

In the app, Breathe opens `app/begin.tsx`: colour wheel, then how it feels, what you'd like instead, and how long you have. `start_session` is that flow without the screen. It's a separate tool rather than more inputs on `breathe` because a match picks its own shapes, rhythm, and length, so `pattern`, `shape`, and `cycles` would only conflict with it.

- **Inputs**: `feeling` (flat, faint, nameable, directional, insistent, saturating), `goal` (grounded, calm, clear, unstuck, settled), and `minutes` (2, 5, 10, or 15). The descriptions are the app's own labels and notes from `src/domain/sessionMatch.ts`. The feeling is how clearly something comes through, never which emotion; Claude is told never to name, guess, or ask about one, and to ask at most one plain question when it can't tell.
- **The colour wheel isn't ported.** It's a touch interaction, and nothing in the match reads it.
- **Stages**: `sessionPlan` gives the stages and seconds; `resolveModality` gives each stage's shape and whether it's counted. The page swaps the drawing at each boundary with `activeStageAt`, instantly, as `app/session.tsx` swaps the renderer. Phase text and counts follow each stage until the person uses T or #.
- **Rhythm**: one breath pace for the whole session, from the core (the stage carrying the match, as `app/begin.tsx` picks it with `coreSegment`) through `shapeSelectionPatch` and `deriveSessionRuntimeConfig`. Every modality the match can reach runs In & Out 4-8, so every matched session is hold-free, whatever the answers: breathe in, a longer breath out. `test/match.test.ts` and `npm run smoke` check all 120 combinations for a hold and fail if one appears.
- **Length and progress**: cycles are the app's `matchedCycles`, the session ends on the meditation timer at the chosen minutes, and the bar shows one segment per cycle (capped at 8), as the app's bar does. It doesn't show stages.
- **Why**: the app stores `whyLine` but doesn't show it on the session screen, so it's only in the tool result for Claude.
- **One difference**: the app starts counting down as soon as the screen opens, showing the core stage's shape until the first stage takes over. The page waits at rest for Begin, so it rests on the first stage's shape instead.

`test/match.test.ts` checks all 120 feeling, goal, and length combinations against the app's functions.

## Shapes

| Shape         | What you see                                                                 | Patterns                   |
| ------------- | ---------------------------------------------------------------------------- | -------------------------- |
| `box`         | A square whose outline draws itself once per breath cycle                    | Box Rhythm, In & Out, In, Hold, Out |
| `triangle`    | A triangle whose outline draws itself once per breath cycle                  | In, Hold, Out, 4-7-8, In & Out |
| `circle`      | A ring that draws itself once per breath cycle, with no corners to turn      | In & Out, In, Hold, Out, Box Rhythm, 4-7-8 |
| `focus-point` | A soft point crosses a line as you breathe in and comes back as you breathe out | In & Out                |
| `infinity`    | A soft point travels a figure-eight, once around per breath cycle            | In & Out                   |
| `ripple`      | Rings spread out from a still centre and fade, once per breath cycle         | In & Out                   |
| `color-field` | Soft colour swells and settles, once per breath cycle                        | In & Out                   |

The last four are the app's breath-locked modalities. The app pairs them with In & Out only, so this server does too. Their names and one-line descriptions come straight from `src/domain/modalityConfig.ts`.

**Why the default is the circle.** It's the app's own: `DEFAULT_BREATH_CONFIG` opens every new session on the circle with In & Out 4-8, and the matched Breathing stages run there too. The app gives the circle to everyone, so every pattern can be drawn on it; for patterns with holds, the box or triangle comes first. For In & Out the box remains the best fit after it (a two-phase rhythm turns on a corner), and the triangle would switch phase mid-side, so it ranks last.

**Reduced motion.** Each shape has the app's still version: the box, triangle, and circle show their full outline, the focus point rests at the middle of its line, the infinity point rests at the crossing, the ripple's rings hold evenly spaced, and the colour field holds at its resting size.

## The session page

The page is the app's session screen (`app/session.tsx`), rebuilt for the browser and checked side by side against iPhone 16e screenshots of the app:

- **Background**: the session gradient (`sessionTokens.background`, navy to teal, corner to corner) under the app's default dim, with the twelve ambient particles spread across it, at the percentage positions `CinematicParticles` gives them.
- **Orb**: the three `SessionAura` rings (outer and inner breathe in opposite directions, the middle sweep turns once every 20 seconds) and the `ShapeAura` glow, sized with `computeAuraRingSizes` and driven by the app's `resolveAuraInstruction`. The shape sits inside it at `layout.shapeRatio`.
- **Text**: the 3, 2, 1 countdown, then the phase name and count centred in the shape on a frosted pill. Box, triangle, and circle start counted; focus point, infinity, ripple, and colour field start uncounted, as their app modalities do.
- **Controls**: the glass pill with pause or resume, end, phase text, and count, which dims after a few seconds without interaction; the time left shows under it while paused; the thin segmented bar shows progress, one segment per cycle.
- **Start and finish**: the app starts straight into the countdown. A page can't, so it opens on the orb at rest with a single Begin button in the same glass pill and a quiet line with the rhythm and length (plus the hold note for patterns with a long hold). Ending shows the app's "Well done" or "Session ended" message with Breathe again, and under it a quiet "Get the VirWave app" text link: the App Store (`apps.apple.com/app/id6738364276`, from `eas.json`) on Apple devices and Google Play (`com.virwave.virwave`) elsewhere, chosen from the user agent, App Store without JavaScript. It opens in a new tab and carries no tracking parameters.
- The title stays in `<title>` and a heading only screen readers see. Phase changes are announced, every button has a label and a visible focus ring, and Space begins, pauses, or resumes.
- **Reduced motion** matches the app: the rings hold their resting size, the sweep and particles stop, the countdown and fades are instant, the controls don't dim, and each shape takes its still pose.

The app sizes the screen in points with fixed caps. The page keeps the iPhone proportions and scales them to the window (up to `layout.maxContentWidth`), so a desktop browser shows the same composition, larger, rather than a shape that outgrows its orb.

## How it reuses the app

The sessions are built from the VirWave app's own files, unchanged. In the app's repository the package compiles them in place from the app's `src/` folder, which is how the paths below are written. In the public repository, [virwave/virwave-breathe](https://github.com/virwave/virwave-breathe), the same files are copies under `vendor/virwave/` (so `src/engine/breathingEngine.ts` is `vendor/virwave/engine/breathingEngine.ts`). The copies are made by a script and never edited by hand; see `vendor/virwave/README.md`. The one exception is `domain/worlds.ts`, which is a short stand-in there: the app's file lists its background themes, and this project only uses the default one. Design tokens are not copied at all: `src/theme.generated.ts` is a snapshot of the few values the session page reads (`npm run generate:theme`, app repository only).

- `src/engine/breathingEngine.ts` is bundled **unchanged** into the page and drives the animation.
- Patterns come from `src/domain/rhythmTemplates.ts` and `timingPresets.ts`: free-tier presets only, gated to `FREE_SHAPES`.
- Breakdowns are composed by the app's `resolveBreakdownFromRhythmAndTiming`.
- The default pattern is `DEFAULT_BREATH_CONFIG.timingPresetId`, so it follows the app.
- The geometry of all seven shapes is ported from `src/render/shapes/` with the same constants. For the four breath-locked shapes, the maths inside each renderer's `useAnimatedProps` worklet is now a plain function in `src/player/geometry.ts`, driven by the same `(phaseIndex + progress) / totalPhases` and the app's default motion intensity (0.7). The app's renderers weren't changed; `test/geometry.test.ts` checks positions, radii, opacities, and scale at key points in the cycle.
- Every colour, space, radius, and type size comes from the app's design tokens and `DEFAULT_BREATH_CONFIG`. `src/theme.generated.ts` is a snapshot of the tokens the page uses, written from the app's own theme files, and a check in the app's repository fails when it falls out of date.

## Develop

From the root of [virwave/virwave-breathe](https://github.com/virwave/virwave-breathe) (or from `packages/virwave-mcp` in the VirWave app's repository, where the package is developed):

```bash
npm ci
npm run build      # dist/server.js (MCP SDK and zod bundled in) and dist/player.js
npm test           # vitest: catalog, planner, schema, geometry parity, page safety, delivery, publishing files
npm run typecheck
npm run smoke      # spawns dist/server.js over stdio and exercises every tool, resource, and prompt
```

To try a local build, point a client at it: `claude mcp add virwave-breathe -- node "$(pwd)/dist/server.js"`.

`npm run smoke` always starts the server with `VIRWAVE_OPEN_BROWSER=false`, so it never launches a browser. Set `VIRWAVE_SMOKE_SERVER=/path/to/server.js` to run the same checks against an installed copy (the npm tarball, or an unpacked `.mcpb`).

CI runs the same checks on every push: `.github/workflows/ci.yml` in the public repository, and `.github/workflows/virwave-mcp.yml` in the app's repository (where the root `tsconfig.json` and `eslint.config.js` skip `packages/**`, so this package owns its own checks).

### The public repository is an export

The app itself is private. `npm run export:public -- <folder>` (app repository only) writes the standalone project that becomes virwave/virwave-breathe: this package at the root, plus the few app files it compiles under `vendor/virwave/`, with the path aliases pointed there. The script copies only the files on its allowlist (`scripts/public-files.mjs`), removes a short, documented list of internal comments from the copies without touching any code, and refuses to finish if the code of a copy differs from the app's. It also refuses to finish if any word on its never-ship list would become public. After building the exported folder, `npm run sweep:public -- <folder>` checks the same list against the source, the built `dist/*.js`, and the tarball `npm pack` makes. `test/export.test.ts` fails when the package starts compiling an app file that isn't on the allowlist, so nothing new becomes public without a deliberate change. Changes are made in the app's repository and exported again; the public copy is not edited by hand.

## Release

`package.json` holds the version. `build.mjs` passes it into the server, and `test/package.test.ts` fails if `manifest.json` or `server.json` disagree with it.

```bash
npm run validate:mcpb   # checks manifest.json against the MCPB spec
npm run pack:mcpb       # builds, then writes dist/virwave-breathe.mcpb (not committed)
npm pack --dry-run      # shows exactly what npm would publish
```

Release from the public repository, not from the app's. A readable bundle keeps some source comments, and only the public copies have had the app's internal comments removed; the code in the two builds is the same.

- **npm**: `npm publish` runs the build, typecheck, tests, and smoke first (`prepublishOnly`). Two files run: `dist/server.js` and `dist/player.js`. There are no runtime dependencies.
- **Claude Desktop extension**: `manifest.json`, `icon.png`, and `.mcpbignore` define the `.mcpb`. It runs the same two files.
- **MCP registry**: `server.json`, with `mcpName` in `package.json` to show the npm package belongs to the same name.

## Not yet

- The remaining app shapes (heart, star, rainbow, and the rest)
- The app's pause dissolve (the moving parts fade while paused); here they hold still where they stopped
- The rest of the app's completion screen (stats, journal, favourites, and the glow that blooms behind the title)
- Sound (needs a play gesture; silence is the default)
- MCP Apps (`ui://` resources), so hosts that support it can render the session inline instead of via a file