rushes 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/.claude-plugin/marketplace.json +14 -0
  2. package/.claude-plugin/plugin.json +10 -0
  3. package/.mcp.json +8 -0
  4. package/AGENTS.md +110 -0
  5. package/LICENSE +21 -0
  6. package/README.md +204 -0
  7. package/dist/cli/demo.js +339 -0
  8. package/dist/cli/doctor.js +307 -0
  9. package/dist/cli/index.js +11 -0
  10. package/dist/cli/main.js +469 -0
  11. package/dist/core/batches.js +58 -0
  12. package/dist/core/errors.js +37 -0
  13. package/dist/core/exportNotes.js +132 -0
  14. package/dist/core/ids.js +42 -0
  15. package/dist/core/media.js +128 -0
  16. package/dist/core/notes.js +117 -0
  17. package/dist/core/paths.js +17 -0
  18. package/dist/core/project.js +200 -0
  19. package/dist/core/schema.js +220 -0
  20. package/dist/core/script.js +113 -0
  21. package/dist/core/store.js +132 -0
  22. package/dist/core/tabs.js +24 -0
  23. package/dist/mcp/client.js +50 -0
  24. package/dist/mcp/ensure.js +69 -0
  25. package/dist/mcp/stdio.js +47 -0
  26. package/dist/mcp/tools.js +191 -0
  27. package/dist/server/app.js +710 -0
  28. package/dist/server/assets.js +234 -0
  29. package/dist/server/files.js +170 -0
  30. package/dist/server/lock.js +148 -0
  31. package/dist/server/loudness.js +331 -0
  32. package/dist/server/proxy.js +575 -0
  33. package/dist/server/reveal.js +71 -0
  34. package/dist/server/start.js +125 -0
  35. package/dist/server/watch.js +133 -0
  36. package/dist/setup/env.js +42 -0
  37. package/dist/setup/harnesses.js +93 -0
  38. package/dist/setup/setup.js +92 -0
  39. package/package.json +54 -0
  40. package/skills/rushes/SKILL.md +30 -0
  41. package/web-dist/assets/figtree-latin-400-normal-BD4aNku5.woff +0 -0
  42. package/web-dist/assets/figtree-latin-400-normal-g7Dtegnw.woff2 +0 -0
  43. package/web-dist/assets/figtree-latin-500-normal-BWnGEVsr.woff2 +0 -0
  44. package/web-dist/assets/figtree-latin-500-normal-B_yy1phn.woff +0 -0
  45. package/web-dist/assets/figtree-latin-600-normal-BM_oTo4n.woff +0 -0
  46. package/web-dist/assets/figtree-latin-600-normal-Cv_xCTDl.woff2 +0 -0
  47. package/web-dist/assets/figtree-latin-700-normal-BCCt2T1q.woff +0 -0
  48. package/web-dist/assets/figtree-latin-700-normal-th6qEP7c.woff2 +0 -0
  49. package/web-dist/assets/figtree-latin-ext-400-normal-CXAzuTZb.woff2 +0 -0
  50. package/web-dist/assets/figtree-latin-ext-400-normal-Gbh-3PTk.woff +0 -0
  51. package/web-dist/assets/figtree-latin-ext-500-normal-BOEJvrb_.woff +0 -0
  52. package/web-dist/assets/figtree-latin-ext-500-normal-Du0rIuHj.woff2 +0 -0
  53. package/web-dist/assets/figtree-latin-ext-600-normal-CQqsimlV.woff +0 -0
  54. package/web-dist/assets/figtree-latin-ext-600-normal-DJlfifZj.woff2 +0 -0
  55. package/web-dist/assets/figtree-latin-ext-700-normal-BoDi4KL2.woff +0 -0
  56. package/web-dist/assets/figtree-latin-ext-700-normal-CS4sQkGV.woff2 +0 -0
  57. package/web-dist/assets/index-BjDIT_wL.css +1 -0
  58. package/web-dist/assets/index-DF6Rl-Ac.js +3 -0
  59. package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-BEIGL1Tu.woff2 +0 -0
  60. package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-ugxPyKxw.woff +0 -0
  61. package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DJqRU3vO.woff +0 -0
  62. package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DmUKJPL_.woff2 +0 -0
  63. package/web-dist/assets/jetbrains-mono-greek-400-normal-B9oWc5Lo.woff +0 -0
  64. package/web-dist/assets/jetbrains-mono-greek-400-normal-C190GLew.woff2 +0 -0
  65. package/web-dist/assets/jetbrains-mono-greek-500-normal-D7SFKleX.woff +0 -0
  66. package/web-dist/assets/jetbrains-mono-greek-500-normal-JpySY46c.woff2 +0 -0
  67. package/web-dist/assets/jetbrains-mono-latin-400-normal-6-qcROiO.woff +0 -0
  68. package/web-dist/assets/jetbrains-mono-latin-400-normal-V6pRDFza.woff2 +0 -0
  69. package/web-dist/assets/jetbrains-mono-latin-500-normal-BWZEU5yA.woff2 +0 -0
  70. package/web-dist/assets/jetbrains-mono-latin-500-normal-CJOVTJB7.woff +0 -0
  71. package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-Bc8Ftmh3.woff2 +0 -0
  72. package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-fXTG6kC5.woff +0 -0
  73. package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-Cut-4mMH.woff2 +0 -0
  74. package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-ckzbgY84.woff +0 -0
  75. package/web-dist/assets/jetbrains-mono-vietnamese-400-normal-CqNFfHCs.woff +0 -0
  76. package/web-dist/assets/jetbrains-mono-vietnamese-500-normal-DNRqzVM1.woff +0 -0
  77. package/web-dist/index.html +14 -0
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "iamredmh",
3
+ "description": "Rushes: a local review desk for video made with AI agents.",
4
+ "owner": {
5
+ "name": "Red Morley Hewitt"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "rushes",
10
+ "source": "./",
11
+ "description": "A local review desk for video made with AI agents."
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "rushes",
3
+ "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent reads and acts on.",
4
+ "version": "0.2.0",
5
+ "author": { "name": "Red Morley Hewitt" },
6
+ "homepage": "https://github.com/iamredmh/rushes",
7
+ "repository": "https://github.com/iamredmh/rushes",
8
+ "license": "MIT",
9
+ "keywords": ["video", "review", "voiceover", "music", "mcp"]
10
+ }
package/.mcp.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "rushes": {
4
+ "command": "npx",
5
+ "args": ["-y", "rushes", "mcp"]
6
+ }
7
+ }
8
+ }
package/AGENTS.md ADDED
@@ -0,0 +1,110 @@
1
+ # Rushes, for agents
2
+
3
+ Rushes is a local review desk. Your user watches the work in a browser, leaves timecoded notes, edits the script and picks audio variants. You read that feedback, act on it, and reply. Everything is saved in the project's `.rushes/` folder, and one local server is the only thing that writes to it.
4
+
5
+ ## Setup (once per machine)
6
+
7
+ ```bash
8
+ npx -y rushes setup
9
+ ```
10
+
11
+ This registers the Rushes MCP server with every supported harness it finds (Claude Code, Codex, Cursor, Claude Desktop, Gemini CLI), and installs the skill where the harness supports skills. If it added anything, ask the user to restart the app. Use `--dry-run` to preview, and `--only claude-code,codex` to limit it. A harness already registered through the older `github:iamredmh/rushes` launch is recognised as Rushes too; setup switches it to the npm launch in place, never adding a duplicate.
12
+
13
+ If setup doesn't seem to have worked, or the user asks you to check your own environment, call `rushes_doctor` (or `rushes doctor [--json]` from the CLI). It reports the Node version, whether ffmpeg/ffprobe are on PATH, which agent harnesses have Rushes registered, and — run from inside a project — whether its files are valid, whether a server is already running for it, and free disk space. Read-only: it never starts a server or changes anything.
14
+
15
+ ## Project folders
16
+
17
+ Rushes recommends this layout; save your output there rather than wherever's convenient:
18
+
19
+ ```
20
+ my-film/
21
+ renders/ cuts hero-60s_v3.mp4
22
+ audio/
23
+ voiceover/ voice reads gerald.wav
24
+ music/ music beds deep-house.wav
25
+ sfx/ SFX passes sfx_pass-a.wav
26
+ screenshots/ frame grabs hero-60s_v3_00m12.10s_f726.png
27
+ exports/ exported notes, plus anything you save there
28
+ .rushes/ Rushes' own records (hidden; not for editing by hand)
29
+ ```
30
+
31
+ Save renders to `renders/`, voice reads to `audio/voiceover/`, music beds to `audio/music/` and SFX passes to `audio/sfx/`. Screenshots live in `screenshots/` — the user's G key and camera button grab there; Rushes creates the folder itself on the first grab. `rushes_list_assets` (optional `kind`) returns every registered asset plus every screenshot. Call it when the user refers to something they haven't given you a path for — "use the screenshot I just took" — instead of guessing the file name.
32
+
33
+ ## The Assets library
34
+
35
+ The **Assets** tab is a library of every project file, organised into folders: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and, once a cut has one, Proxies. Proxies are listed and deleted from there; you never register or remove one yourself — see proxies, below.
36
+
37
+ Some of it needs no registering. A `*.md`, `*.txt`, `*.pdf`, `*.srt` or `*.vtt` file directly in the project root, and anything saved directly into `exports/`, are found automatically.
38
+
39
+ Everything else, register with `rushes_add_file` (`kind`, `file`, optional `name`, `note` and `video`):
40
+
41
+ - **deliverables** — final masters and platform exports — as `delivery`;
42
+ - **NLE project files** — `.prproj`, `.drp` — as `edit`;
43
+ - **storyboards, references and logos** as `image`;
44
+ - **briefs** as `doc`.
45
+
46
+ The CLI equivalent is `rushes add file <path> --kind K [--name N] [--note T] [--video V]`.
47
+
48
+ When the user wants to share notes with someone else, call `rushes_export_notes` (CLI: `rushes export notes`). It writes every note, grouped by stage and, for Picture, by film and version, to a dated Markdown file in `exports/`, and returns its path.
49
+
50
+ ## A demo project
51
+
52
+ No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. The demo makes a complete example on the user's machine — a cut in two versions, a script, voice reads in two rounds, two music beds, an SFX pass and example notes — all generated locally with ffmpeg. Always pass `--no-browser`: without it the command stays running as the server and never returns. It refuses a folder that isn't empty.
53
+
54
+ ## Locked tabs and the prompts they copy
55
+
56
+ Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
57
+
58
+ > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
59
+
60
+ ## The loop
61
+
62
+ 1. **Register what you made.**
63
+ - A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. When the cut is likely to play badly in a browser (4K or larger, over 1.5 GB, or a codec such as ProRes), the reply carries `proxySuggested: true` and `proxyReason`; Picture then offers the user a proxy. Prefer H.264 MP4 to begin with and this won't come up.
64
+ - A VO script: `rushes_set_script` with sections `{start, end, current}` in seconds. It merges by `id`: send only the sections you changed, with their ids, plus any new ones without an id. Sections you leave out are kept, with their takes. Pass `replace: true` only when you mean to replace the whole script. `rushes_get_script` reads the whole script back.
65
+ - A voice read: `rushes_add_variant` with `stage: "voice"` and `round` (the round's name, e.g. "Round 2 · Gerald, tone" — reads in one round are compared side by side; a new direction gets a new round, a small fix to a marked word can stay in the current one). Say in `description` what the read is, or what changed from the one it's based on. `rushes_add_take` stays in the file format and API for compatibility only; voiceover work doesn't use it.
66
+ - Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`. Give it `meta: {description: "..."}`, shown on its lane card in place of `bpm`/`key`; SFX passes also take `cues` (`{name, t}` in seconds), labelled on the waveform.
67
+ - The storyboard's shots, once you have the first cut: `rushes_set_shots` with `video`, optional `version` (defaults to the newest) and `shots` as `{start, name, tag?}`. Send new timings whenever a later cut moves them.
68
+ 2. **Open it for the user:** `rushes_open`. Each project's dashboard lives at its own address, `/p/<id>/` — safe to run more than one project at once. A tab unlocks as soon as it has something in it.
69
+ 3. **Wait for feedback.** The user presses **Send to agent**, which saves a batch and gives them a prompt to paste to you. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections.
70
+ 4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — Voiceover only ever uses `point` or `whole`; it has no Range scope), `t`, `tOut`, `on` (the lane, variant, take, cue or section it's about), `text`, and optionally `box` (normalised 0 to 1), `grab` (a PNG path in `screenshots/`; older notes may point to `.rushes/grabs/`) and `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set). On an audio stage, `on` is `"<laneId>/<variantId>"` for a music bed, SFX pass or voice read (the lane and variant ids `rushes_add_variant` returns) — on Voiceover the lane id is the round's slugged name, so `on` names the round and the read together — or `"<laneId>/<variantId>:<cueId>"` for an SFX cue. On Mix it's `null` for the whole mix, `"vo"` for the VO lane (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or SFX lane. Older notes may carry a bare variant id, `"vo"` on Voiceover itself, a section id, `"<sectionId>:<takeId>"` for a take, `"<variantId>:<cueId>"` or a bare cue id; Rushes still lists these with a sensible label, but none of them name a read any more. On Music, Sound effects and Mix, a note can also carry `marks` — short feedback like `Fall` (bring the level down over the range) or `Quieter 3 dB` (3 dB lower over the range). `rushes_list_notes`, `rushes_get_batch` and exported notes all show them. Marks are the user's, like a note's text and times — you read and act on them, you don't set them. Voiceover notes carry no marks: a note there is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — about the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead).
71
+ 5. **Register the new cut** with `rushes_add_version` and note what changed. If the video is locked, the reply carries `warning: "Picture is locked at vN"`; the version is still added.
72
+ 6. **Reply to every note** in one `rushes_reply` call. For each, set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. If you didn't fix a note, leave it `todo` and say why in `reply`.
73
+ 7. **Audio batches.** On Voiceover, Music, Sound effects or Mix, call `rushes_get_picks` first, so you know which read or variant is in use before you fix anything. On Mix, it also returns `levels: { voice?, music?, sfx? }` in dB — where the user wants each lane to sit. Don't try to change these; they're set from the dashboard's sliders and only tell you the balance the user has already chosen. Then fix each note:
74
+ - **Voiceover:** register a new whole read with `rushes_add_variant` (`stage: "voice"`) — a new round for a new direction (another voice, a different tone), or the current round for a small fix to a marked word. Say in `description` what changed.
75
+ - **Music or Sound effects:** make the new bed or pass the text and marks ask for, and register it as in step 1.
76
+
77
+ Then reply as in step 6. Mix plays the newest round's picked voice read; takes are never mixed.
78
+ 8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and a flagged section goes back to draft. If voiceover already exists, re-record the picked voice with the corrected script and register it with `rushes_add_variant` as a new read in a new round.
79
+
80
+ ## Tools
81
+
82
+ The MCP server has seventeen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes` and `rushes_doctor`. Each takes an optional `project` folder, which defaults to the folder the harness started in.
83
+
84
+ ## Rules
85
+
86
+ - Never edit `.rushes/*.json` by hand while the server is running. Use the tools, or the CLI (`rushes add`, `rushes notes`, `rushes reply`).
87
+ - Picks — which variant is in use per lane — are set from the dashboard only (**Use** / **Unpick**). No tool or CLI command sets one; read them with `rushes_get_picks`. Section take picks remain in the file format for compatibility only; nothing sets them any more.
88
+ - A project whose voiceover exists only as takes from before rounds keeps Voiceover locked until a voice read exists, but open notes on those takes still count towards Send to agent and can be answered with `rushes_reply`.
89
+ - You own a note's `reply`, `fixT` and `fixVersion`. The user owns its text, times and box. Either of you can set `status`.
90
+ - After the first cut, send the storyboard's shots with `rushes_set_shots`; when a new cut moves them, send new timings.
91
+ - Lock picture with `rushes_lock_picture` only when the user says picture is locked. Pass `version: null` to unlock.
92
+ - Times are seconds from the start of the video, as numbers (e.g. `31.05`).
93
+ - A server you start through the tools stops by itself after two hours with nothing connected. The next tool call starts it again. `rushes stop` stops it now.
94
+ - Prefer H.264 MP4 for cuts: browsers can't play ProRes, and some can't play HEVC.
95
+
96
+ ## Without MCP
97
+
98
+ ```bash
99
+ npx -y rushes open
100
+ npx -y rushes add version renders/hero_v2.mp4 --video "Hero 60s" --note "logo hold"
101
+ npx -y rushes notes --stage picture --status todo --json
102
+ npx -y rushes reply n_8f2k3a "Held the phone 0.5 s longer" --done --fix-t 12.9 --fix-version v2
103
+ npx -y rushes add variant voice gerald.wav --name Gerald --round "Round 1 · Voices"
104
+ npx -y rushes add shots shots.json --video "Hero 60s" --version v2
105
+ npx -y rushes add file brief.pdf --kind doc
106
+ npx -y rushes export notes
107
+ npx -y rushes doctor --json
108
+ ```
109
+
110
+ `shots.json` is a JSON array of `{name, start, tag?}`, or that array wrapped as `{"shots": [...]}`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Red Morley Hewitt
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,204 @@
1
+ # Rushes
2
+
3
+ A local review desk for video made with AI agents.
4
+
5
+ Your agent renders a cut, writes a voiceover script or generates music beds. Rushes shows that work stage by stage in your browser:
6
+
7
+ - **Script:** your edits sit beside the agent's lines.
8
+ - **Picture:** timecoded notes, ranges, boxes on the frame and frame grabs.
9
+ - **Voiceover, Music, Sound effects:** variants you can switch between with no gap.
10
+ - **Mix:** everything playing together.
11
+
12
+ Your notes are saved as plain files in your project. The agent reads them, fixes things and replies on each one, and you see each reply arrive.
13
+
14
+ It runs on your machine. There's no account, no API key and no server to sign up for. You need [Node.js](https://nodejs.org) 20.19 or newer (or 22.12+ on the 22 line).
15
+
16
+ > Status: early. The Script, Picture, Voiceover, Music, Sound effects and Mix tabs, the MCP tools and the CLI all work today.
17
+
18
+ ## Get started
19
+
20
+ Tell your agent:
21
+
22
+ > Use github.com/iamredmh/rushes as my review tool for video, voiceover and music.
23
+
24
+ That's all. Your agent reads the next section and sets itself up.
25
+
26
+ ## For agents: set yourself up
27
+
28
+ If your user asked you to use Rushes, do this:
29
+
30
+ 1. Run this once. It finds every supported harness on the machine and registers the Rushes MCP server, plus the Rushes skill where the harness supports skills:
31
+
32
+ ```bash
33
+ npx -y rushes setup
34
+ ```
35
+
36
+ (Before publishing to npm, the GitHub form also works: `npx -y github:iamredmh/rushes setup`.)
37
+
38
+ It prints one line per harness. Existing config is kept and a `.rushes.bak` backup is written first. Run it with `--dry-run` first if you want to show the user the changes before making them. A machine already set up through the GitHub form is recognised as Rushes too — setup switches it to the npm launch instead of adding a second registration.
39
+ 2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
40
+ 3. From then on, follow [AGENTS.md](AGENTS.md). In short: register what you made, call `rushes_open`, wait for the user to press **Send to agent**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
41
+
42
+ The MCP server has seventeen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes` and `rushes_doctor`.
43
+
44
+ If you can't run commands, give the user the matching line from **Manual setup** below.
45
+
46
+ ## Manual setup
47
+
48
+ | Harness | How |
49
+ |---|---|
50
+ | **Claude Code**: plugin, which includes the skill | `/plugin marketplace add iamredmh/rushes` then `/plugin install rushes@iamredmh` |
51
+ | **Claude Code**: MCP only | `claude mcp add --scope user rushes -- npx -y rushes mcp` |
52
+ | **Codex** | add to `~/.codex/config.toml`:<br>`[mcp_servers.rushes]`<br>`command = "npx"`<br>`args = ["-y", "rushes", "mcp"]` |
53
+ | **Cursor** (`~/.cursor/mcp.json`), **Claude Desktop** (`claude_desktop_config.json`), **Gemini CLI** (`~/.gemini/settings.json`) | `{ "mcpServers": { "rushes": { "command": "npx", "args": ["-y", "rushes", "mcp"] } } }` |
54
+
55
+ On Windows, `rushes setup` writes the launch as `cmd /c npx -y rushes mcp` (in JSON: `"command": "cmd", "args": ["/c", "npx", "-y", "rushes", "mcp"]`), because harnesses can't start `npx` directly there. Do the same if you set it up by hand.
56
+
57
+ ### Other harnesses
58
+
59
+ Any MCP client that can launch a local stdio server works. Point it at `npx -y rushes mcp`. Agents with no MCP support can use the CLI instead (`rushes add`, `rushes notes`, `rushes reply`): see [AGENTS.md](AGENTS.md).
60
+
61
+ ChatGPT's apps can't run local MCP servers yet. Use Codex, OpenAI's agent, instead.
62
+
63
+ ## Use it yourself
64
+
65
+ ```bash
66
+ cd your-project
67
+ npx -y rushes open # opens the review desk in your browser
68
+ npx -y rushes stop # stops it
69
+ ```
70
+
71
+ Each project opens at its own address, `http://127.0.0.1:4580/p/<id>/` — safe to run several projects at once.
72
+
73
+ A server your agent starts in the background stops by itself after two hours with nothing connected.
74
+
75
+ ### Try it first: `rushes demo`
76
+
77
+ No project to hand? Build one:
78
+
79
+ ```bash
80
+ npx -y rushes demo # creates ./rushes-demo and opens it
81
+ ```
82
+
83
+ It generates a complete example on your machine — a 30 s test film in two cuts, a short script, voice reads in two rounds, two music beds, an SFX pass, and example notes on Picture, Voiceover, Music and Mix — so every tab has something in it from the start. Nothing is downloaded and nothing ships with Rushes; it's all made locally with ffmpeg and, where available, your system's text-to-speech. It needs ffmpeg — without it, `demo` says so and points you at `rushes doctor`. It refuses to write into a folder that isn't empty. Pass a folder name to put it somewhere else, and `--no-browser` to skip opening it.
84
+
85
+ ### Health check: `rushes doctor`
86
+
87
+ ```bash
88
+ npx -y rushes doctor # Node, ffmpeg, which agents have Rushes, this project, free disk space
89
+ npx -y rushes doctor --json # the same checks as data
90
+ ```
91
+
92
+ Each check prints ✓ or ✗ with a plain fix, e.g. `✗ Claude Code — the Rushes MCP server isn't registered. Fix: rushes setup --only claude-code`. Only the Node version (and, inside a project, its files) has to pass; ffmpeg is recommended (proxies and loudness need it) but not required, and doctor warns when your ffmpeg was built without libx264, which proxies and the demo encode with. Run it from inside a project folder to add file, server and disk checks. Agents get the same checks from the `rushes_doctor` tool.
93
+
94
+ ## Shortcuts
95
+
96
+ In the Picture tab:
97
+
98
+ - **Space** play or pause
99
+ - **←/→** step one frame (Shift: ten)
100
+ - **I/O** set in and out
101
+ - **B** draw a box
102
+ - **G** grab a frame
103
+ - **N** new note
104
+
105
+ In the Voiceover, Music, Sound effects and Mix tabs:
106
+
107
+ - **Space** play or pause
108
+ - **←/→** step one frame (Shift: ten)
109
+ - **I/O** set in and out
110
+ - **N** new note
111
+
112
+ Anywhere:
113
+
114
+ - **1–7** switch tab (7: Assets)
115
+ - **[ / ]** previous/next film
116
+ - **?** shortcuts
117
+ - **Esc** close
118
+
119
+ ## Locked tabs
120
+
121
+ Every tab is visible from the start, in workflow order, even before there's anything in it. A locked tab isn't a dead end: open it and it explains itself — what the tab is for, what unlocks it, and a **Copy prompt for your agent** button that copies a ready-to-paste request naming your project, the film, and the tool your agent should use, e.g.:
122
+
123
+ > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
124
+
125
+ Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets tab follows the same rule.
126
+
127
+ ## Screenshots and the Assets library
128
+
129
+ Press **G**, or the camera button, to grab the current frame. It's saved as a PNG to `screenshots/`, named for the film, version and timecode — grabbing the same frame twice overwrites the same file.
130
+
131
+ The **Assets** tab (key `7`) is a library with a folder sidebar: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and Proxies. Each folder has search and a sort order; Screenshots, Images, Cuts and Delivery also get a grid/list toggle, and Screenshots, Cuts and Delivery get a film filter — every other folder is list-only. Audio plays inline, one at a time, and Markdown or text files get a read-only preview. Every item has five actions: Download, Save as (Chrome and Edge only — other browsers just get Download), Open, Show in Finder and Copy path. **Open** appears, and is accepted, only for a fixed list of safe, non-executable types — never scripts, apps or archives. Top-level `.md`, `.txt`, `.pdf`, `.srt` and `.vtt` files, plus anything in `exports/`, are picked up automatically; everything else your agent registers with `rushes_add_file`. The Exports folder also has an **Export notes** button, which writes every note to a dated Markdown file there.
132
+
133
+ Rushes recommends this layout for a project folder:
134
+
135
+ ```
136
+ my-film/
137
+ renders/ cuts hero-60s_v3.mp4
138
+ audio/
139
+ voiceover/ voice reads gerald.wav
140
+ music/ music beds deep-house.wav
141
+ sfx/ SFX passes sfx_pass-a.wav
142
+ screenshots/ frame grabs hero-60s_v3_00m12.10s_f726.png
143
+ exports/ exported notes, plus anything you save there
144
+ .rushes/ Rushes' own records (hidden; not for editing by hand)
145
+ ```
146
+
147
+ Rushes creates `screenshots/` itself on the first grab. It never creates the other folders — they're a convention for agents to follow.
148
+
149
+ ## Packs, picture lock and shots
150
+
151
+ A project with more than one film gets numbered pills in the header — `[`/`]` switch between them, and each film remembers its own version and playhead. The header reads **Picture vN**, with a lock button beside it: lock a film at a cut and the dashboard opens on that cut until you unlock it. A version can carry a shot list from the storyboard, shown as a strip under the timeline, and every Picture note records the shot it falls in.
152
+
153
+ ## Proxies
154
+
155
+ Some cuts play badly in a browser: 4K or larger, over 1.5 GB, a codec browsers can't play reliably (ProRes, DNx, HEVC 10-bit — anything that isn't H.264, VP9 or AV1), or one that threw a playback error. Rushes checks with ffprobe as the cut is added, and if it's likely to struggle, a bar appears under the player saying why in a few words, with a **Create proxy** button. It makes a lightweight 1080p H.264 copy on your drive — your original file is never changed — with visible progress and **Cancel**. Notes, timecodes and frame numbers are identical on the proxy and the original.
156
+
157
+ Once it's ready, a **Proxy / Original** switch appears on the player (defaults to Proxy, remembered per film). **Grab Frame** always takes the still from the original at full quality, whichever one you're watching. Tick "Create proxies for new cuts like this automatically" (off by default, saved per project) to skip the offer next time. The **Assets** tab has a **Proxies** folder listing each one with its size and a **Delete proxy** button; deleting removes only the proxy file, never the original.
158
+
159
+ Without ffmpeg, no proxy is ever offered.
160
+
161
+ ## Audio review
162
+
163
+ The Voiceover, Music, Sound effects and Mix tabs share one audio engine, so switching what you hear is instant and never restarts playback or knocks picture out of sync.
164
+
165
+ Voiceover works in rounds: the same script read by a few voices, then variations of whichever one you pick. The current round is open; earlier rounds fold into one row each, and clicking a row opens it so its reads play too.
166
+
167
+ - **Use** picks a music bed, SFX pass or voice read — shown as **In use**. Clicking a lane auditions it without changing the pick. An **Unpick** button beside In use clears the pick. On Music and Sound effects the first bed or pass is auditioned; on Mix the lane is empty; on Voiceover, with nothing clicked, the current round's pick plays, or else its first read.
168
+ - **Blind** (Music and Voiceover) renames the beds `Bed 1`, `Bed 2`… — on Voiceover, each round's reads `Read 1`, `Read 2`… — in a shuffled order and masks their descriptions, so you can compare without knowing which is which.
169
+ - On Voiceover, a note is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead). There's no Range scope and no Rise/Fall/Louder/Quieter marks there.
170
+ - On Music, Sound effects and Mix, a note can carry marks: toggle **Rise**, **Fall**, **Louder** or **Quieter** (with a dB amount, 3 by default) to say how a range should change — "Fall" or "Quieter 3 dB".
171
+ - **Mix** shows a loudness readout — integrated LUFS, true peak, and the music's level under the VO — measured over exactly what Mix plays, using the newest round's picked voice read. It needs **ffmpeg** on your PATH; without it, the readout shows "—". After a timeout or an error, click the readout to measure again.
172
+ - Each **Mix** lane (Voiceover, Music, Sound effects) has a level slider, −24 dB to +6 dB in 0.5 dB steps, shown as e.g. `−14.0 dB`. Double-click resets it to 0; arrow keys move it 0.5 dB at a time. Levels are saved with your picks, never change a file, and the loudness readout is measured with them applied.
173
+
174
+ ## What gets saved
175
+
176
+ ```
177
+ your-project/.rushes/
178
+ project.json videos, versions, audio lanes and variants
179
+ script.json VO sections: the agent's line, your version, direction, takes
180
+ notes.json every note, with the agent's replies
181
+ picks.json which variant or take is in use, and each Mix lane's level
182
+ batches.json what you sent to the agent
183
+ ```
184
+
185
+ Add `.rushes/` to git if you want your review history kept with the project — and `screenshots/` alongside it, since notes point to the grabs there. Keep `proxies/` out of git: proxies can run to gigabytes, and Rushes can always make them again. Rushes ignores its own temporary files.
186
+
187
+ ## Develop
188
+
189
+ ```bash
190
+ git clone https://github.com/iamredmh/rushes && cd rushes
191
+ npm install
192
+ npm test
193
+ npm run rushes -- open ../some-project
194
+ ```
195
+
196
+ ffmpeg and ffprobe are optional. With them installed, Rushes reads frame rates and durations and can make browser-playable copies.
197
+
198
+ ## Publishing (maintainers)
199
+
200
+ Run `npm login` once in Terminal — it confirms in your browser. Then, with the maintainer's OK at the time, `npm publish`. npm may ask for a one-time code; enter it when it does.
201
+
202
+ ## Licence
203
+
204
+ MIT © Red Morley Hewitt