1# jevstrudel
2
3[Strudel](https://strudel.cc) — the JavaScript port of TidalCycles — with two
4additions: an MCP bridge so Claude can play and edit code in a browser
5session, and the jev panel on the REPL's left, which holds everything this
6fork adds (the song browser, who is listening, your account, how to
7connect your AI, and everything the site stores, for anyone to read) so it
8is never mistaken for Strudel's own, and Jev at
9work in a pane under the editor. The
10songs live here too: pick one and it opens there with its spec, its code
11loads, and it plays from the top. The public site also hosts an MCP for everyone's own
12AI (`/ai/`, `worker/README.md`, The hosted MCP): signed in, a visitor
13connects Claude Code or Claude, which plays into their own tab's sandbox
14and publishes songs Jev screens.
15
16## What this repo is made of
17
18It is a fork, kept as three layers so each can be updated on its own:
19
20| Branch | What it is |
21|---|---|
22| `strudel-upstream` | Strudel's `main`, from [codeberg.org/uzu/strudel](https://codeberg.org/uzu/strudel) (remote `strudel`) |
23| `strudel-llm` | The MCP fork as published, [calvinw/strudel-llm-mirror](https://github.com/calvinw/strudel-llm-mirror) (remote `strudel-llm`) |
24| `strudel-llm-rebased` | The fork's 9 commits rebased onto `strudel-upstream` |
25| `jevstrudel` | `strudel-llm-rebased` plus this project: the songs, samples, vocal tools, the flake, and the song browser |
26
27Both remotes have push disabled; this repo only ever reads from them.
28
29## Running it
30
31`buck2 run //:dev`, inside the devshell (`nix develop`, or direnv), is the
32working tree with hot reload on <http://localhost:4322/>: edit the site, a
33song or a sample and the page updates. Beside it runs the jevstrudel Worker
34(`worker/`) with the Jev relay and an MCP hub: `.mcp.json` runs
35`nix run .#mcp`, a small stdio proxy, so Claude can play code into an open
36tab. Either side can restart without the other. The proxy's
37`use_environment` tool switches it to the public site's hosted MCP, signed
38in as you with a passkey, and back (`tools/mcp/`).
39
40`buck2 run //:preview` is the last listen before a deploy: the deploy's own
41static build with the production Worker (the relay, no MCP) on
42<http://localhost:4324/>.
43
44`buck2 run //:check-songs` plays every song fast in a silent headless tab
45on the dev server and reports what Jev did, and anything that failed.
46`nix flake check` evaluates every song in Node against a stand-in Jev.
47
48`nix build .#static` is the site alone, for any static host: the REPL and
49song browser with the sample pack bundled, and no MCP. `nix run .#deploy`
50publishes it with the Jev relay as a public Cloudflare Worker at
51<https://jevstrudel.deizel.workers.dev>; the Cloudflare token comes from
521Password on each run.
53
54The devshell also has `speak TEXT OUT.wav` and `vocode IN.wav OUT.wav
55--chord "a2 a3 c4 e4"` (a Windows speech voice, and a vocoder that makes a
56chord sing it), and `ffmpeg` for cutting vocal clips.
57
58Audio comes out of the browser (on Windows), so nothing in WSL needs a sound
59server.
60
61## Layout
62
63Everything upstream (`packages/`, `website/`, …) is Strudel's, with the
64MCP fork's changes on top. This project adds:
65
66- `songs/<theme>/<song>/` — one folder per song: `SPEC.md` and `song.js`.
67- `samples/<sound>/` — the sample pack: every folder is a sound
68  (`samples/jeff/jeff.mp3` plays as `s("jeff")`). Songs load it with
69  `samples('jev-samples/strudel.json')`, which the site builds.
70- `tools/vocals/` — the vocal tools' sources; `tools/mcp/` — the MCP proxy;
71  `tools/measure/` — each song's mix, measured; `tools/events/` — the
72  Worker's telemetry, read back; `tools/jev-history/` — Jev's decision
73  history per song, from the stored performances; `tools/worktree-samples/` —
74  a worktree's own samples in the headless tools.
75- `website/src/jev/` — the song browser, `jev()` (TypeSafe's API as Strudel patterns) and link previews.
76- `worker/` — the Cloudflare Worker: the Jev relay, and the MCP hub in dev.
77- `nix/`, `flake.nix` — how jevstrudel is built and run.
78- `BUCK`, `.buckconfig`, `toolchains/`, `tools/dev/`, `tools/check-songs/` —
79  the `//:dev`, `//:preview` and `//:check-songs` targets.