Moontide README

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 code that plays in your browser and changes without ever stopping.

▶ Watch the demo on YouTube (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 where you can edit notes, the Song grid with the sections of a piece, the history as a list or a tree, a mixer with groups and lights 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, 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:

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:

node --version

It must print v22 or higher. If Node is missing or older, install the LTS version from 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 and sign in once. Moontide works with either; Claude Code is the one tried most.

4. Add Moontide to Claude

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

claude mcp get moontide

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

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

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

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

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. npx can keep using a copy it already downloaded; to move to the newest release, add Moontide again with @latest:

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

Uninstall

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.

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 Claude Code documentation. Do not allow broad node commands.

Musical reference

Claude gets a factual reference of the exact Strudel version the page runs, through the get_strudel_reference tool (also offered as MCP resources), covering nine topics: Strudel vs TidalCycles, mini-notation, pattern functions, effects and sound controls, the sound palette, music theory in Strudel, transitions, song structure, and MIDI output. It holds facts only: what exists and how to write it. Moontide ships no mood vocabulary, no style material and no model pieces; Claude translates your words with its own knowledge of music theory, then tells you in one line what it chose. Ask for a surprise in your own words: there is no menu command for it. Set a frame for the session, for example gradual changes, and Claude follows it for every change until you lift it. Say what matters to you (a melody, a rhythm) and Claude keeps it, and asks before a full rewrite.

Small edits and harmony

Claude can change a few lines of a long piece without sending it again, through the edit_code tool; a change that waits for its bar is edited, and your hand edits are kept.

The code can say which harmony it means with one top-level line, for example const harmony = 'C:minor', placed above the patterns. It plays nothing and is never a track. The Jam view then shows two lines, "Declared:" and "Heard:", side by side.

Song structure

Every new piece Claude writes starts with one const song at the top. It names the sections with their lengths in cycles, says which version (variation) of each track plays in each section or that the track rests, and may put tracks into groups. It is still ordinary Strudel, and the same code plays in plain Strudel. A small request on an older piece is made in place and does not restructure it. A piece without a song plays and looks as before.

For a piece with a song, the Parts view is called Song. The Song grid shows the tracks under foldable groups, with one column per section and the playing section marked.

• Click a section header to launch that section on the next line the toolbar names: the end of the playing section, the next phrase or the next bar. Click again to cancel.
• Click a cell to pick another variation for that track and section, or a rest. It takes over with your usual hand-edit timing.
• A fixed variation says whether its notes fit the section's harmony: fits, does not fit, or cannot check. It only says; it never blocks.
• Play after Stop starts from the first section. The Jam view's Declared line follows the playing section.

The Mixer draws the groups as frames that fold together with the grid. One click on a group's M or S mutes or solos every track below it, as one change. There is no group fader, because plain Strudel has no gain for a group. A small light on each strip and each group blinks when its note is heard. With motion off in the Session drawer, a light stays lit while notes come.

On the Timeline, click a note to select it. Drag it up or down, or press the Up and Down keys, to change its pitch by semitones. Delete, Backspace or "Make a rest" turns it into a rest. Two buttons change its velocity by a tenth. The page checks an edit before it writes it, says first when one edit changes the note in several places, and uses your hand-edit timing. A note the page cannot edit says why. Your gesture then opens the Ask box with a ready-made request, and it goes to Claude only when you press Enter. Drag across one lane, or hold Shift and press Left or Right, to select a range of whole cycles, and use "Ask Claude" to send it.

A right-click on a section, a track, a cell or a group asks Claude about that thing.

History

Every version that plays is kept: Claude's own changes and your Ctrl+Enter edits, each with its time, who made it and a short label. Failed code and stops are not versions.

Ask Claude things like "go back to the previous version", "the one from 3 changes ago", "the one with the bass", or "keep this one, call it Take two", and "list my favorites". The Session drawer shows the number of the version that is playing, in its Last change card, for example v42.

The history file lives in your OS's per-user data folder:

• macOS: ~/Library/Application Support/moontide/history.jsonl
• Linux: $XDG_DATA_HOME/moontide/history.jsonl, or ~/.local/share/moontide/history.jsonl
• Windows: %APPDATA%\moontide\history.jsonl

Set MOONTIDE_DATA_DIR to use another folder. The history is one text file with one entry per line, and survives the end of the Claude session.

The history keeps the last 1000 versions; older ones are dropped in batches and Claude is told. Favorites are never dropped.

If a line of the file cannot be read, Claude is told which lines; they stay in the file untouched. If the file cannot be read or written at all, the music keeps working and Claude is told.

Run one Moontide at a time with the same history file. Two at once can give two versions the same number.

Troubleshooting

"Failed to connect" right after installing. The first start downloads the package, and Claude Code gives up after 30 seconds. Wait a little and check again with claude mcp list. If it keeps failing, start Claude Code with a longer limit: MCP_TIMEOUT=60000 claude. In PowerShell, use $env:MCP_TIMEOUT = "60000"; claude.

Moontide is missing in another folder. It was added without --scope user. Add it again with the Install line.

The page did not open. Claude's replies name its address. Open it yourself, or ask Claude to start Moontide again: it gives the address and opens a new tab when no page is connected.

Several Moontide tabs. Each Claude session that started Moontide has its own page and port. The tab title says "Moontide · · ", with the folder that session runs in, and the Session drawer shows the same. Ask Claude which tab is its own: it answers with the address, the port and the tab title.

No sound. Click once in the page. Check that the browser tab is not muted, and keep the page open.

Claude Desktop does not find npx. Put the full path in "command": the path printed by which npx on macOS or where npx on Windows, written here as <full path printed by which npx>. This is common advice and has not been tried here. The Claude Desktop logs are in ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows.

MIDI says to use Chrome or Edge. Web MIDI is missing in that browser.

Status

Early and personal. It runs on one setup: a Mac, Chrome, Claude Code and Claude Desktop, and, for MIDI, a Roland SC-55, the Munt MT-32 emulator and a Roland JUPITER-Xm. It has not been tried anywhere else. The test suite runs on Windows, Linux and macOS in CI, but nobody has played music on Windows or Linux yet. There are known bugs. Feedback is welcome, but support is not something I can promise.

Known limits:

• Tried by hand only on macOS, with Chrome, Claude Code and Claude Desktop.
• Windows and Linux are untested by hand. Edge, Safari and Firefox are untested.
• Internet access is needed.
• MIDI needs Chrome or Edge.
• Run one Moontide at a time with the same history file.
• The first start through npx downloads the package and can be slow.

Network and privacy

• The server listens on 127.0.0.1 only and refuses requests for any other host name.
• Moontide's own server code makes no outbound request and sends no telemetry.
• The page loads @strudel/repl 1.3.0 and acorn 8.18.0 from unpkg, pinned to exact versions with integrity hashes.
• Strudel then fetches sound lists and samples from raw.githubusercontent.com and cdn.jsdelivr.net. No hash covers those.
• The code Claude writes runs in the page and may load samples from other addresses.
• The history stays in the local data folder described above.

Contributing and security

Bug reports and ideas are welcome as issues (use the bug form). How pull requests are handled is in CONTRIBUTING.md.

Security problems go through a private report, never a public issue. See https://github.com/konni-arcadia/moontide/security/policy.

Credits

This builds on other people's work:

• Felix Roos, Alex McLean and the Strudel contributors: Strudel (source: https://codeberg.org/uzu/strudel), the live-coding engine that plays every note.
• Alex McLean and the TidalCycles community: TidalCycles, the pattern language Strudel ports to JavaScript.
• The sample makers whose sets Strudel loads by default, including the TidalCycles Dirt-Samples and the Versilian Community Sample Library (VCSL).
• Anthropic: the Model Context Protocol and its TypeScript SDK, which let Claude talk to Moontide.
• The acorn authors: the JavaScript parser the page uses to read the code.

License

Moontide plays Strudel, which is under AGPL-3.0-or-later. Moontide uses the same license. It loads Strudel from unpkg at run time and does not ship it. The license text is in LICENSE. Moontide is not affiliated with, or endorsed by, the Strudel or TidalCycles projects, or Anthropic.

Konni — built with an AI coding assistant.