moontide

# Moontide

> The moon guides the tide.

**A hobby project: Claude plays live music for you. Describe a mood, a theme or an idea, and
Claude writes [Strudel](https://strudel.cc) code that plays in your browser and changes without
ever stopping.**

[![npm version](https://img.shields.io/npm/v/moontide-mcp)](https://www.npmjs.com/package/moontide-mcp)
[![CI](https://github.com/konni-arcadia/moontide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/konni-arcadia/moontide/actions/workflows/ci.yml)

[![Moontide demo: Claude starts a dungeon theme from a few words, then changes it on requests typed in the page](https://i.ytimg.com/vi/kT4UdEi2Z-8/maxresdefault.jpg)](https://youtu.be/kT4UdEi2Z-8)

▶ [Watch the demo on YouTube](https://youtu.be/kT4UdEi2Z-8) (3 minutes, with sound)

## How this was made

Moontide is a personal project. Most of the code, research and documentation was
written by an AI coding assistant working under my direction. I set the goals, listened to
every change, tried it on my own instruments, judged the results by ear, and made the
decisions. I am responsible for what is here, errors included.

## Why

Curiosity. I wanted to see how far an AI assistant can go at making real music, not a
technical demo, when it is given a good instrument. Strudel is that instrument: a live-coding
language where a change lands on the next cycle, with no cut, and where the music is plain text
that both of us can read.

So Claude writes the code, and the code stays on screen while it plays. You can watch it, edit
it by hand, go back to any earlier version, or point at something in the page and ask for a
change.

## What it does

- You talk ("start something dreamy in D minor", "darker", "add a bass"). Claude writes
  Strudel code, and a browser page plays it at once. Each change takes over within a fraction
  of a second, without stopping the music.
- The code is always visible and editable. Every version that played is kept, and Claude can
  bring any of them back.
- Around the code, the page shows the music in several views: the named tracks on a timeline,
  the parts of a piece, the history as a list or a tree, a mixer whose moves rewrite the code,
  and a jam view with the scale on a piano or a guitar.
- A right-click on anything in the page sends Claude a request with that context.
- The same code can play real MIDI instruments from the page, through Web MIDI.

Moontide does not start from scratch. The music engine is
**[Strudel](https://strudel.cc)**, the JavaScript port of TidalCycles by Felix Roos, Alex McLean and the
Strudel contributors. Moontide is the bridge between Claude and a Strudel page.

## How it works

```
 you ──talk──► Claude ──MCP (stdio)──► Moontide ──WebSocket (localhost)──► browser page
                                          │                                 Strudel plays
                                          └─ history file on your disk      the code, sound
                                                                            and Web MIDI out
```

1. Moontide runs as an MCP server that Claude connects to. It starts nothing until you ask
   for music or say "start Moontide".
2. It then opens a page in your browser with a Strudel editor.
3. Claude writes the code, the page plays it, and you watch the code come alive.
4. Claude can stop the music at any point. The page has its own Play and Stop button too.
5. Right-click anything in the page to ask Claude about it. A right-click on the Timeline also
   sends the moment under the pointer: the cycle and the beat, the version that was playing, and
   the notes sounding there or starting in the same sixteenth, with their velocities and, for a
   MIDI track, its instrument and channel. The Session drawer (the Session button in the top
   bar) says whether page requests are live (they reach Claude right away) or wait for Claude
   (they reach it with its next action). Its (i) explains how to switch.

## Install

The short version, for someone who already has Node 22 or later and Claude Code:

```bash
claude mcp add --scope user moontide -- npx -y moontide-mcp
```

Then start a new Claude session and ask for music. The steps below explain each part.

### 1. What you need

- **Node 22 or later**, with npm and npx (they come with Node).
- **Claude Code or Claude Desktop.** Moontide is an MCP server: Claude talks to it.
- **Chrome**, the browser Moontide was tried with. For MIDI (Web MIDI), use Chrome or Edge.
- **Internet access**: Strudel and its sounds load from the web.
- **Speakers or headphones.**

### 2. Check Node

In a terminal, run:

```bash
node --version
```

It must print `v22` or higher. If Node is missing or older, install the LTS version from
[nodejs.org](https://nodejs.org). On macOS with Homebrew, `brew install node` works too. Open a
new terminal afterwards and check again.

### 3. Get Claude

Install Claude Code or Claude Desktop from [claude.com](https://claude.com/claude-code) and sign
in once. Moontide works with either; Claude Code is the one tried most.

### 4. Add Moontide to Claude

<details open>
<summary>Claude Code (tested on macOS; Linux untested)</summary>

In a terminal, run:

```bash
claude mcp add --scope user moontide -- npx -y moontide-mcp
```

With `--scope user`, Moontide is available in every folder. The default scope (local) works
only in the folder where you ran the command, and the scope `project` shares it through a
`.mcp.json` file.

Keep the name `moontide`. The page-request commands below use it.

Check the install with:

```bash
claude mcp get moontide
```

The same line is meant for Linux. It is untested there.

</details>

<details>
<summary>Claude Desktop (tested on macOS; Windows untested)</summary>

Open Settings, then Developer, then Edit Config. The file is:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add Moontide to it:

```json
{
  "mcpServers": {
    "moontide": {
      "command": "npx",
      "args": ["-y", "moontide-mcp"]
    }
  }
}
```

If the file already has an `mcpServers` block, add the `moontide` entry inside it. Quit Claude
Desktop fully and start it again. Claude Desktop has no Linux version.

</details>

<details>
<summary>Windows with Claude Code (untested)</summary>

From PowerShell or Command Prompt (not Git Bash), run:

```bash
claude mcp add --scope user moontide -- cmd /c npx -y moontide-mcp
```

Check it with `claude mcp get moontide`. The command must read `cmd` with `/c npx -y moontide-mcp`. If it shows `C:/` instead of `/c`, edit the `moontide` entry in the `.claude.json` file of your user folder so it reads `"command": "cmd", "args": ["/c", "npx", "-y", "moontide-mcp"]`.

This form comes from community reports. It has not been tried here.

</details>

<details>
<summary>From the source code</summary>

To run Moontide from a copy of this repository instead of npm:

```bash
git clone https://github.com/konni-arcadia/moontide.git
cd moontide
npm ci
npm run build
```

Then add it with the full path of `dist/index.js`, written here as `<folder>`:

```bash
claude mcp add --scope user moontide -- node <folder>/dist/index.js
```

`npm test` runs the test suite. The real-browser checks (`npm run probe:page`) need Chrome.

</details>

### 5. First music

1. Start a new Claude session. Nothing opens yet: Moontide waits until you want it.
2. Ask for music, for example "Play something calm to start the day" or "Give me a slow, warm
   groove". Or say "start Moontide". In Claude Code, `/mcp__moontide__start` does the same.
3. The page opens in a new tab at http://localhost:5757, or on another port when 5757 is busy.
   Claude's replies name the address. The tab title names the folder Claude runs in and the
   port, for example "Moontide · my-project · 5757".
4. Click once anywhere in the page. Browsers start sound only after a click.
5. Ask for changes: "darker", "add a bass", "slower".

Set `MOONTIDE_NO_BROWSER=1` in the environment and starting Moontide opens no tab. Open the
address from Claude's reply yourself.

### Update

To see the version that runs, run `npx -y moontide-mcp --version`. Releases are listed in
[CHANGELOG.md](https://github.com/konni-arcadia/moontide/blob/main/CHANGELOG.md). npx can keep
using a copy it already downloaded; to move to the newest release, add Moontide again with
`@latest`:

```bash
claude mcp remove moontide --scope user
claude mcp add --scope user moontide -- npx -y moontide-mcp@latest
```

### Uninstall

```bash
claude mcp remove moontide --scope user
```

In Claude Desktop, remove the `moontide` entry from the config file and restart it. Moontide
keeps its history and settings in your data folder (see History); delete that folder if you
want them gone too.

### MIDI instruments (optional)

Moontide can play MIDI instruments from the code through Web MIDI. It ships ready models for the
Roland MT-32 and SC-55. You can describe your own instruments and models, add sound catalogs and
send MIDI clock. The setup is in
[docs/midi.md](https://github.com/konni-arcadia/moontide/blob/main/docs/midi.md).

## Page requests without a permission prompt

In the Code tab of the Claude app, ask Claude to turn page requests on or off. Claude calls
Moontide's `set_page_requests` tool. In Claude Code in a terminal, type
`/mcp__moontide__page-requests-on` to make them live or `/mcp__moontide__page-requests-off` to
make them wait. Live, Claude starts a monitor, which lasts at most 30 minutes and is started
again when a tool reply asks. Waiting, tool replies stop offering to start it until page
requests are turned on again. Page requests need an open page, so start Moontide first. These
names assume the server was added as `moontide`.

Claude Code asks permission before it starts the monitor for page requests, because it runs a
command. You can approve it each time. If you want a narrower permission rule instead, see the
permissions section of the C