rushes 0.4.0 → 0.5.1

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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "rushes",
3
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.4.0",
4
+ "version": "0.5.1",
5
5
  "author": { "name": "Red Morley Hewitt" },
6
6
  "homepage": "https://github.com/iamredmh/rushes",
7
7
  "repository": "https://github.com/iamredmh/rushes",
package/AGENTS.md CHANGED
@@ -8,7 +8,7 @@ Rushes is a local review desk. Your user watches the work in a browser, leaves t
8
8
  npx -y rushes setup
9
9
  ```
10
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.
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. An entry the user adjusted themselves (a full path to `npx`, an `env`) that still launches `rushes mcp` is left as it is, and a Codex entry written in a form setup can't edit makes setup stop with "change it by hand" rather than add a second one.
12
12
 
13
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
14
 
@@ -47,6 +47,44 @@ The CLI equivalent is `rushes add file <path> --kind K [--name N] [--note T] [--
47
47
 
48
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/`, writes the Change Log beside it as `exports/change-log-<date>.md`, and returns both paths.
49
49
 
50
+ ## Starting a film
51
+
52
+ When the user wants a new video ("start a new film", "make a launch video", "a new project in Rushes"), plan it with them in Rushes before you build anything. They approve the brief, the script and the storyboard first, so nothing gets built that they haven't seen.
53
+
54
+ 1. **Create the project** unless one exists: `npx -y rushes new <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. It makes the project, `renders/` and `audio/voiceover`, `audio/music` and `audio/sfx`, and a `brief.md` to fill in. It refuses a folder that is already a Rushes project and never overwrites a `brief.md` that is there. Always pass `--no-browser`: without it the command stays running as the server and never returns.
55
+ 2. **Interview, briefly.** Ask at most three questions, and only ones whose answer changes the film: length and formats, who it is for, tone. Give each a recommended answer with its trade-off ("30 seconds fits a feed; 60 leaves room for the demo"). Never send a list of ten.
56
+ 3. **Write `brief.md`.** Its sections, in order, are Title, Purpose, Audience, Length and formats, Tone, Include and avoid, Built with, Open questions and References. Fill every one, keep the `Status: draft` line, and tell the user to open Planning › Brief in Rushes, change any row and press **Approve brief**. Rushes then sets `Status: approved` in the file itself. Never approve it yourself or change that line, and if they say it's approved in chat while the file still says `draft`, ask them to press Approve. When they press **Send to agent** on the Brief page, read `brief.md` again and keep their wording: your last version is shown as Current, so read the file before you rewrite it.
57
+ 4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in Planning › Script. Read `rushes_get_script` and wait until every section is `approved`.
58
+ 5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
59
+
60
+ ```markdown
61
+ ## Shot 02 · Drop a folder
62
+ Tag: ACTION
63
+ Length: 5
64
+ Still: storyboard/shot-02.png
65
+ Status: draft
66
+ Direction:
67
+
68
+ A folder of clips lands in the window from the right.
69
+ ```
70
+
71
+ `Length` is planned seconds (they become the cut's shot starts), `Still` is a project-relative picture (png, jpg, webp or gif), best saved under `storyboard/`, and `Direction` is the user's line. Make a still for each shot if your tools can; the Storyboard page shows any still the file names, registered or not. The user reads and approves each shot in Planning › Storyboard, and Rushes sets `Status: approved` itself: never set or change a shot's status yourself. When they press **Send to agent** there, read `storyboard.md` again, keep their wording, and update the still if what happens has changed.
72
+ 6. **Build only when all three are approved** (`rushes_status` reports `build`: `ready`, and what it is `waitingOn`). If the user says "just build it", do. Build in whatever tool suits the film, and name each scene after its planned shot. Then register the cut with `rushes_add_version`: a film's first cut starts with the storyboard's shots by itself (each `start` the running total of the lengths before it), so call `rushes_set_shots` only when the real timings differ (a cut brought in with `rushes_scan` or `rushes_bring_in` does not: send its shots with `rushes_set_shots`). A film with no script has nothing to wait on there: the script is only waited on when the film has one. While the plan isn't all approved the reply carries `planWarning`: a nudge, not a refusal.
73
+
74
+ The brief and the storyboard are Markdown files the user reads and approves on their own pages under Planning. Use the same file names so the next session finds them.
75
+
76
+ ## Picking up a film that's underway
77
+
78
+ When the user asks to open or review a film they started in the chat, or the project already has files but no `brief.md`, don't make them start again. Rebuild the plan from what you have, then say what you did.
79
+
80
+ 1. **Open the project**, or create it where the work is: `npx -y rushes new <folder> --no-browser` (it never overwrites a `brief.md` and leaves every other file alone), then `rushes_open`.
81
+ 2. **Write `brief.md` from the conversation.** Fill each section from what the user actually said. Mark anything you had to infer with `(inferred)` so they can check it. Where the chat never touched a section, write `Not discussed yet.` rather than inventing something. Put ideas they floated but didn't settle, and anything you couldn't answer, under Open questions. Keep `Status: draft`, and never approve it yourself.
82
+ 3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in Planning › Script). Copy storyboard stills into a `storyboard/` folder in the project: copy them, never move them, so the originals stay where the user's other tools expect them. Write the shots into `storyboard.md` in the shot format above, each with `Status: draft` and a `Still:` line naming its copy (the Storyboard page shows any still the file names). Register other reference images with `rushes_add_file` (`kind: "image"`). Renders, voice reads and music beds go in as usual (`rushes_add_version`, `rushes_add_variant`). Run `rushes_scan` for audio and cuts in the folder; it doesn't look for images, so naming the stills in `storyboard.md` (or registering other images) is yours to do: you know where you saved them.
83
+ 4. **Say what you filled in:** what came from the user's words, what you inferred, what you registered, and what you looked for and couldn't find ("I found four of the six stills"). Ask them to read `brief.md` under Assets › Scripts & docs.
84
+ 5. **If the chat is one you can't see** (another session, another tool), say so and ask the user to paste it or point you to it. Don't reconstruct a brief from memory of a conversation you didn't have.
85
+
86
+ When a user starts briefing in the chat, offer to keep `brief.md` up to date as you go: run `rushes new` first, so the next session, or another tool, can pick it up.
87
+
50
88
  ## A demo project
51
89
 
52
90
  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.
@@ -76,7 +114,7 @@ Every tab is visible from the start, in workflow order, even before it has anyth
76
114
  - **Music or Sound effects:** make the new bed or pass the text and marks ask for, and register it as in step 1.
77
115
 
78
116
  Then reply as in step 6. Mix plays the newest round's picked voice read; takes are never mixed.
79
- 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.
117
+ 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 the section goes back to draft, as any section does when you change its line: a flag has been acted on, and the user approved the old words, not the new ones, so they approve again. 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.
80
118
 
81
119
  ## Opening a project, and the files that go with the cut
82
120
 
@@ -119,7 +157,8 @@ The MCP server has twenty-two tools: `rushes_open`, `rushes_status`, `rushes_add
119
157
  ## Without MCP
120
158
 
121
159
  ```bash
122
- npx -y rushes open
160
+ npx -y rushes new my-film --no-browser
161
+ npx -y rushes open my-film
123
162
  npx -y rushes add version renders/hero_v2.mp4 --video "Hero 60s" --label "logo hold" --note "held the logo 0.5 s longer"
124
163
  npx -y rushes add format renders/hero_v2_9x16.mp4 --video "Hero 60s"
125
164
  npx -y rushes notes --stage picture --status todo --json
package/README.md CHANGED
@@ -1,28 +1,162 @@
1
- # Rushes
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/brand/lockup-dark.svg">
4
+ <img alt="Rushes" src="docs/brand/lockup.svg" height="56">
5
+ </picture>
6
+ </p>
2
7
 
3
- A local review desk for video made with AI agents.
8
+ <h3 align="center">Your agent shoots. You give notes.</h3>
4
9
 
5
- Your agent renders a cut, writes a voiceover script or generates music beds. Rushes shows that work stage by stage in your browser:
10
+ <p align="center">
11
+ The review desk for video made with AI agents. Pin notes to the exact frame, edit the script,<br>
12
+ pick the voice and the music. Your agent reads every note and fixes it.
13
+ </p>
6
14
 
7
- - **Script:** your edits sit beside the agent's lines.
8
- - **Picture:** timecoded notes, ranges, boxes on the frame and frame grabs.
9
- - **Picture waveform:** the cut's own audio, drawn quietly in the timeline, so you can see where the sound is.
10
- - **Voiceover, Music, Sound effects:** variants you can switch between with no gap.
11
- - **Mix:** everything playing together.
15
+ <p align="center">
16
+ <a href="https://www.npmjs.com/package/rushes"><img alt="npm" src="https://img.shields.io/npm/v/rushes?style=flat-square&color=7C93FF&labelColor=1C1E22"></a>
17
+ <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-7C93FF?style=flat-square&labelColor=1C1E22"></a>
18
+ <a href="https://nodejs.org"><img alt="Node.js 20.19 or newer" src="https://img.shields.io/badge/node-%E2%89%A5%2020.19-7C93FF?style=flat-square&labelColor=1C1E22"></a>
19
+ <img alt="Runs on your machine" src="https://img.shields.io/badge/runs-on%20your%20machine-4CC38A?style=flat-square&labelColor=1C1E22">
20
+ <img alt="Works through MCP" src="https://img.shields.io/badge/works%20through-MCP-A78BFA?style=flat-square&labelColor=1C1E22">
21
+ </p>
12
22
 
13
- 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.
23
+ <p align="center">
24
+ <a href="#get-started">Get started</a> &nbsp;·&nbsp;
25
+ <a href="#how-it-works">How it works</a> &nbsp;·&nbsp;
26
+ <a href="#every-stage-in-one-place">The tabs</a> &nbsp;·&nbsp;
27
+ <a href="#your-notes-are-plain-files">Plain files</a> &nbsp;·&nbsp;
28
+ <a href="#faq">FAQ</a> &nbsp;·&nbsp;
29
+ <a href="#for-agents-set-yourself-up">For agents</a>
30
+ </p>
14
31
 
15
- 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).
32
+ https://github.com/user-attachments/assets/b9b3d872-297a-4afc-8657-902d11d175a1
16
33
 
17
- > Status: early. The Script, Picture, Voiceover, Music, Sound effects and Mix tabs, the MCP tools and the CLI all work today.
34
+ ## Chat is a poor place to review a film
35
+
36
+ More and more video is made by agents. Claude, Codex and the rest can write the script, render the cut, and generate the voiceover, the music and the sound effects. What they can't do is show you the work. You get a folder of files and a filename. Then you type "the logo bit at the end feels off" into a chat box, and the agent asks which logo, and where.
37
+
38
+ Rushes is the desk that's missing. It shows each stage of the work in your browser, lets you mark it up the way an editor would, and hands every note back to your agent with the exact moment, box or line it's about.
39
+
40
+ <p align="center">
41
+ <img src="docs/assets/chat-vs-rushes.jpg" alt="On the left, a chat where a vague note about a logo gets the reply 'Which logo, and where in the video?'. On the right, the same note in Rushes: a frame at 0:27.40 with a dashed box round the logo, the note, and the agent's reply that the hit moved from 27.9 s to 27.4 s." width="880">
42
+ </p>
18
43
 
19
44
  ## Get started
20
45
 
21
46
  Tell your agent:
22
47
 
48
+ > Use github.com/iamredmh/rushes to start a new film.
49
+
50
+ That's all. Your agent reads [the setup steps for agents](#for-agents-set-yourself-up) and sets itself up. Then it asks you up to three questions, writes a brief and a script for you to approve, sketches the shots, and only builds once you've said yes.
51
+
52
+ Already have a film? Tell your agent:
53
+
23
54
  > Use github.com/iamredmh/rushes as my review tool for video, voiceover and music.
24
55
 
25
- That's all. Your agent reads the next section and sets itself up.
56
+ If you started it in the chat, your agent writes the brief from the conversation and registers the script, stills and files you've already made, and says what it had to guess.
57
+
58
+ 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).
59
+
60
+ No project to hand? `npx -y rushes demo` builds an example on your machine and opens it.
61
+
62
+ > Status: early. The Script, Picture, Voiceover, Music, Sound effects and Mix tabs, the MCP tools and the CLI all work today.
63
+
64
+ ## How it works
65
+
66
+ <p align="center">
67
+ <img src="docs/assets/loop.png" alt="The loop in four steps. One, the agent registers a cut, a script or a mix. Two, you review it in the browser and pin notes. Three, you press Send to agent and your notes go as one batch. Four, the agent fixes each note and replies on it. The next version comes back to step two until picture is locked." width="880">
68
+ </p>
69
+
70
+ Your agent registers what it makes. You review it in the browser. When you press **Send to agent**, your notes go as one batch, saved as plain files in your project. The agent reads the batch, fixes each note and replies on it, and you see each reply arrive.
71
+
72
+ ## Every stage in one place
73
+
74
+ Six tabs, in the order the work happens; the first, Planning, is a menu that holds Brief and Script. A tab unlocks as soon as it has something in it, and a locked tab tells you what to ask your agent for.
75
+
76
+ ### Picture: point at the exact frame
77
+
78
+ <img src="docs/assets/screens/picture-review.jpg" alt="The Picture tab on the first cut of a launch film, paused at 0:03.00. A dashed box is drawn round the word 'shot.' at the end of the headline. Four open notes are listed beside the video, two with frame grabs." width="880">
79
+
80
+ Pin a note to a moment, to a range, or to a box drawn on the frame. Grab a frame to show what you mean. Every note records the shot it falls in.
81
+
82
+ ### The agent replies on every note
83
+
84
+ <img src="docs/assets/screens/picture-fixed.jpg" alt="The Picture tab on version two of the film, paused at 0:14.40 on a count-up that now lands on '11 min'. In the notes, a green tick and the agent's reply sit under the note that asked for the change." width="880">
85
+
86
+ When the agent delivers a new cut, each note shows where it landed in the new version and what the agent did about it. A green tick means it's done. Anything the agent didn't fix stays open, with a reason.
87
+
88
+ ### Planning: the brief, then your edits beside the agent's lines
89
+
90
+ <img src="docs/assets/screens/script-review.jpg" alt="The Script tab. Each section shows the agent's current line on the left and the user's rewrite on the right. Two sections are outlined as changed, each with a short direction such as 'Two short sentences. Easier to say.'" width="880">
91
+
92
+ Rewrite a line, add a direction, flag it or approve it. The bar on each row shows whether the line still fits its slot. When the agent adopts your edit, it records the next voice read from the corrected script.
93
+
94
+ Planning is one tab with a menu, so planning never crowds the review stages. **Brief** shows `brief.md` in your project folder: the agent's version of each section beside yours. Edit a row and Rushes writes it into the file; press **Approve brief** and it sets the file's status line. If your agent rewrites `brief.md`, the page follows without a reload. **Storyboard** works the same way over `storyboard.md`: a row per shot with its still (click it to enlarge), the agent's description beside yours, a direction line and a tick to approve it. When the brief, every script line (if the film has a script) and every shot are approved, the Planning tab shows a green check and its menu says **Ready to build**, with a prompt to copy. Rushes never stops your agent building before then: it only says what is still waiting.
95
+
96
+ ### Voiceover: compare reads, round by round
97
+
98
+ <img src="docs/assets/screens/voiceover.jpg" alt="The Voiceover tab. The current round, 'George, slower', is picked and in use. The earlier round is open below it with two reads, George and Eliza, side by side. A note on the earlier round has the agent's reply: Round 2 is George at 93% pace." width="880">
99
+
100
+ Reads of the same script sit side by side in rounds. Switch between them with no gap in playback, or turn on **Blind** to hide which is which. Leave a note on a whole read, or at a point in it.
101
+
102
+ ### Music: audition the beds
103
+
104
+ <img src="docs/assets/screens/music.jpg" alt="The Music tab with three beds, each with its waveform. Bed B is in use. Two open notes are marked on the waveforms: a 'Fall' on bed A and a 'Rise' on bed B." width="880">
105
+
106
+ Switch beds instantly while the picture plays. Mark a range as **Rise**, **Fall**, **Louder** or **Quieter**, and your agent gets it as a note it can act on.
107
+
108
+ ### Sound effects: layers by sound
109
+
110
+ <img src="docs/assets/screens/sound-effects.jpg" alt="The Sound effects tab with one pass open into its layers. There is one row per sound (tick, thud, blip, chime, whoosh, counter, thump, snap), each with a count and a mark wherever it plays." width="880">
111
+
112
+ Every cue is labelled on the waveform. Open the pass into **layers by sound**: one row per sound, with a count, and a tick wherever it plays. Click a layer's file to hear that sample on its own.
113
+
114
+ ### Mix: everything together
115
+
116
+ <img src="docs/assets/screens/mix.jpg" alt="The Mix tab. Voiceover, music and sound effects each have a lane with mute and solo buttons and a level slider. Below them, integrated loudness, true peak and the level of the music under the voice are shown. A note asks for the music to be 2 dB quieter through the middle." width="880">
117
+
118
+ Voiceover, music and effects play together against the picture. Set each lane's level, mute or solo it, and read the loudness and true peak (with ffmpeg installed).
119
+
120
+ ### The Change Log
121
+
122
+ <img src="docs/assets/screens/change-log.jpg" alt="The Change Log drawer open over the Picture tab. It lists, newest first, the picks, the sound effects pass, the music beds, the picture lock, the agent's replies to five notes, the voiceover reads and the script, each marked as by the agent or by you." width="880">
123
+
124
+ Rushes keeps a running log of what happened: each cut, read, bed and pass as it arrives, notes sent, and the agent's replies. Export it as Markdown for whoever needs to catch up.
125
+
126
+ ## Why Rushes
127
+
128
+ - **Notes your agent can act on.** Each one carries its stage, a timecode or range, an optional box on the frame, a frame grab, and the shot it falls in.
129
+ - **One batch at a time.** **Send to agent** covers the tab you're on, because you review one stage at a time.
130
+ - **Versions keep their history.** Notes follow the work from cut to cut, and you can lock picture when it's done.
131
+ - **Local, with no sign-up.** No account, no API key, nothing uploaded. It runs on your machine.
132
+ - **Works with the agent you already use.** One MCP server for Claude Code, Codex, Cursor, Claude Desktop and Gemini CLI, a plugin and skill for Claude Code, and a command line for anything else.
133
+ - **Plain files, so the work is yours.** Notes, script and picks live in your project folder. Commit them with the rest.
134
+
135
+ ## Your notes are plain files
136
+
137
+ <p align="center">
138
+ <img src="docs/assets/files.png" alt="A project folder with renders, audio, screenshots and a hidden .rushes folder holding notes.json, script.json, picks.json, batches.json and project.json. Beside it, a note from notes.json: the stage, the time, the text, the box on the frame, the status 'done', and the agent's reply." width="880">
139
+ </p>
140
+
141
+ Rushes keeps your review in a `.rushes/` folder in the project. The agent reads those files, fixes the work and writes its reply back, and a single local server is the only thing that writes to them. Add `.rushes/` to git if you want your review history kept with the project. More in [What gets saved](#what-gets-saved).
142
+
143
+ ## FAQ
144
+
145
+ **Does my video leave my machine?** No. Rushes serves the review desk from your own computer and reads your project folder from disk. There's no upload, no account and no key.
146
+
147
+ **Which agents does it work with?** Any that can run a local MCP server: Claude Code, Codex, Cursor, Claude Desktop and Gemini CLI today. Agents with no MCP support can use the command line. See [Manual setup](#manual-setup).
148
+
149
+ **Can I use it without an agent?** Yes. Review, leave notes, and run **Export notes** for a dated Markdown file you can send to a person. The agent loop is where it pays off most.
150
+
151
+ **Does it need ffmpeg?** No, but it helps. With ffmpeg installed Rushes reads frame rates and durations, makes browser-playable proxies of heavy cuts, and measures loudness on Mix. Run `rushes doctor` to check.
152
+
153
+ **Can it handle big files?** Cuts that play badly in a browser (4K and above, huge files, ProRes and similar) get an offer of a light 1080p proxy. Your original is never changed. See [Proxies](#proxies).
154
+
155
+ **Where do I report a bug or ask for something?** [Open an issue](https://github.com/iamredmh/rushes/issues). Please say which agent and operating system you're using, and attach the output of `rushes doctor`.
156
+
157
+ ---
158
+
159
+ The rest of this page is the reference: setup for agents, manual setup, the command line, shortcuts and every feature in detail.
26
160
 
27
161
  ## For agents: set yourself up
28
162
 
@@ -38,7 +172,7 @@ If your user asked you to use Rushes, do this:
38
172
 
39
173
  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.
40
174
  2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
41
- 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`.
175
+ 3. From then on, follow [AGENTS.md](AGENTS.md). If the user wants a new film, start with **Starting a film** in AGENTS.md: plan it with them first, then build. Otherwise, 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`.
42
176
 
43
177
  The MCP server has twenty-two tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `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`, `rushes_log`, `rushes_get_log`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor`.
44
178
 
@@ -75,6 +209,14 @@ Each project opens at its own address, `http://127.0.0.1:4580/p/<id>/` — safe
75
209
 
76
210
  A server your agent starts in the background stops by itself after two hours with nothing connected.
77
211
 
212
+ ### Start a film: `rushes new`
213
+
214
+ ```bash
215
+ npx -y rushes new my-film # creates ./my-film and opens it
216
+ ```
217
+
218
+ It makes the project folder with `renders/` and `audio/` ready, and a `brief.md` for your agent to fill in with you. You say yes to the brief, the script and the storyboard before anything is built. A folder that's already a Rushes project is refused, and an existing `brief.md` is never overwritten. Pass `--name` to set the project's name and `--no-browser` to skip opening it.
219
+
78
220
  ### Try it first: `rushes demo`
79
221
 
80
222
  No project to hand? Build one:
@@ -115,7 +257,7 @@ In the Voiceover, Music, Sound effects and Mix tabs:
115
257
 
116
258
  Anywhere:
117
259
 
118
- - **1–7** switch tab (7: Assets)
260
+ - **1–7** switch tab (1: Planning, which opens the page you used last; 7: Assets)
119
261
  - **[ / ]** previous/next film
120
262
  - **Alt+←/→** previous/next format (Picture)
121
263
  - **?** shortcuts
@@ -2,7 +2,7 @@ import { access, readFile, statfs as nodeStatfs } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
  import { RUSHES_DIR, Store } from "../core/store.js";
4
4
  import { FILES } from "../core/schema.js";
5
- import { harnesses, LEGACY_DETAIL, legacyMcpLaunches, mcpLaunch, mentionsLegacySource, mergeJson, mergeToml } from "../setup/harnesses.js";
5
+ import { harnesses, LEGACY_DETAIL, legacyMcpLaunches, mcpLaunch, mentionsLegacySource, mergeJson, mergeToml, RegistrationFormError } from "../setup/harnesses.js";
6
6
  import { realSetupEnv } from "../setup/env.js";
7
7
  import { canonicalRoot } from "../server/lock.js";
8
8
  import { hasFpsMode, parseFfmpegVersion } from "../server/proxy.js";
@@ -182,7 +182,10 @@ async function harnessCheck(h, env) {
182
182
  return { ...base, ok: true, detail: LEGACY_DETAIL };
183
183
  return { ...base, ok: false, detail: "the Rushes MCP server isn't registered.", fix: `rushes setup --only ${h.id}` };
184
184
  }
185
- catch {
185
+ catch (e) {
186
+ // A valid file whose rushes entry is written in a form setup doesn't edit: it is registered.
187
+ if (e instanceof RegistrationFormError)
188
+ return { ...base, ok: true, detail: "the Rushes MCP server is registered, in a form setup doesn't edit." };
186
189
  return { ...base, ok: false, detail: `${path} exists but isn't valid, so registration can't be checked.`, fix: `Fix ${path}, then run: rushes setup --only ${h.id}` };
187
190
  }
188
191
  }
package/dist/cli/main.js CHANGED
@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
3
3
  import { basename, resolve } from "node:path";
4
4
  import { Store } from "../core/store.js";
5
5
  import { ffmpegRunner, makeDemo, sayAvailable, sayRunner } from "./demo.js";
6
+ import { makeProject } from "./new.js";
6
7
  import { startServer, DEFAULT_PORT } from "../server/start.js";
7
8
  import { ensureServer, findServer } from "../mcp/ensure.js";
8
9
  import { AlreadyRunningError, canonicalRoot } from "../server/lock.js";
@@ -17,6 +18,7 @@ import { formatTag } from "../core/formats.js";
17
18
  import { onLabel } from "../core/notes.js";
18
19
  import { setup } from "../setup/setup.js";
19
20
  import { realSetupEnv } from "../setup/env.js";
21
+ import { HARNESS_IDS } from "../setup/harnesses.js";
20
22
  import { runDoctor, realDoctorEnv } from "./doctor.js";
21
23
  export const HELP = `rushes ${VERSION}: a local review desk for video made with AI agents
22
24
 
@@ -28,6 +30,7 @@ Usage
28
30
  rushes stop [dir] stop the project's running server
29
31
  rushes init [dir] [--name NAME] create the .rushes folder
30
32
  rushes demo [dir] [--no-browser] create an example project with generated media (default ./rushes-demo), then open it
33
+ rushes new <folder> [--name NAME] [--no-browser] start a film: the folders and a brief.md to fill in, then open it
31
34
  rushes setup [--only claude-code,codex,...] [--dry-run]
32
35
  add Rushes to every agent harness on this machine
33
36
  rushes mcp run the MCP server over stdio
@@ -59,7 +62,7 @@ Usage
59
62
  rushes log add --area mix -- "-3 dB on the bed"
60
63
 
61
64
  Options
62
- --dir DIR project folder for commands that talk to the server (default: current folder)
65
+ --dir DIR project folder (default: current folder); where a command takes [dir], that wins
63
66
  `;
64
67
  const OPTIONS = {
65
68
  port: { type: "string" },
@@ -92,11 +95,11 @@ const OPTIONS = {
92
95
  help: { type: "boolean", short: "h" },
93
96
  version: { type: "boolean", short: "v" },
94
97
  };
95
- // "demo" is here too: without --no-browser it ends by running "open" (a server that keeps
96
- // running), so index.ts must not process.exit() the moment main() first resolves. With
98
+ // "demo" and "new" are here too: without --no-browser each ends by running "open" (a server that
99
+ // keeps running), so index.ts must not process.exit() the moment main() first resolves. With
97
100
  // --no-browser nothing is left open, so the process still exits on its own once main() resolves.
98
- const LONG_RUNNING = ["open", "serve", "mcp", "demo"];
99
- /** Does this command line start something that keeps running (open, serve, mcp, demo)? Flags before the command are skipped. */
101
+ const LONG_RUNNING = ["open", "serve", "mcp", "demo", "new"];
102
+ /** Does this command line start something that keeps running (open, serve, mcp, demo, new)? Flags before the command are skipped. */
100
103
  export function longRunningCommand(argv) {
101
104
  try {
102
105
  const [cmd] = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true }).positionals;
@@ -205,7 +208,8 @@ export async function main(argv, io) {
205
208
  switch (cmd) {
206
209
  case "open":
207
210
  case "serve": {
208
- const root = await canonicalRoot(resolve(io.cwd, rest[0] ?? "."));
211
+ // The folder is the argument, or --dir, or the current folder: `status` and `doctor` already read it so.
212
+ const root = await canonicalRoot(rest[0] ? resolve(io.cwd, rest[0]) : dir);
209
213
  const show = (url) => {
210
214
  if (cmd === "open" && !o["no-browser"])
211
215
  (io.openBrowser ?? openBrowser)(url);
@@ -241,9 +245,12 @@ export async function main(argv, io) {
241
245
  const idle = o["idle-minutes"] === undefined ? undefined : Number(o["idle-minutes"]);
242
246
  if (idle !== undefined && !(Number.isFinite(idle) && idle > 0))
243
247
  return usage(io, "--idle-minutes must be a number of minutes above 0");
248
+ const port = o.port ? Number(o.port) : DEFAULT_PORT;
249
+ if (!Number.isInteger(port) || port < 0 || port > 65535)
250
+ return usage(io, "--port must be a whole number from 0 to 65535");
244
251
  let s;
245
252
  try {
246
- s = await startServer(root, { port: o.port ? Number(o.port) : DEFAULT_PORT, idleMs: idle ? idle * 60_000 : undefined });
253
+ s = await startServer(root, { port, idleMs: idle ? idle * 60_000 : undefined });
247
254
  }
248
255
  catch (e) {
249
256
  // Another server won the race between the check above and our start.
@@ -267,7 +274,7 @@ export async function main(argv, io) {
267
274
  return 0;
268
275
  }
269
276
  case "stop": {
270
- const root = await canonicalRoot(resolve(io.cwd, rest[0] ?? "."));
277
+ const root = await canonicalRoot(rest[0] ? resolve(io.cwd, rest[0]) : dir);
271
278
  const url = await findServer(root);
272
279
  if (!url)
273
280
  return io.out(`Rushes isn't running for ${root}`), 0;
@@ -276,11 +283,27 @@ export async function main(argv, io) {
276
283
  return 0;
277
284
  }
278
285
  case "init": {
279
- const root = resolve(io.cwd, rest[0] ?? ".");
286
+ const root = rest[0] ? resolve(io.cwd, rest[0]) : dir;
280
287
  await new Store(root).init(o.name ?? basename(root));
281
288
  io.out(`Created ${root}/.rushes`);
282
289
  return 0;
283
290
  }
291
+ case "new": {
292
+ // §24.10 step 1. The folder is the argument or --dir; with neither there is nothing to make.
293
+ const target = rest[0] ? resolve(io.cwd, rest[0]) : o.dir ? dir : undefined;
294
+ if (!target)
295
+ return usage(io, "rushes new <folder> [--name NAME] [--no-browser]");
296
+ // An unquoted "My Film" is two words: refuse rather than quietly make ./My and drop "Film".
297
+ if (rest.length > 1)
298
+ return usage(io, "rushes new <folder> [--name NAME] [--no-browser] (one folder only: quote a name with spaces)");
299
+ const made = await makeProject(target, { name: o.name });
300
+ io.out(`Created ${made.dir}`);
301
+ io.out(made.briefWritten ? "Wrote brief.md for your agent to fill in with you." : "Kept the brief.md that was already there.");
302
+ // Like `demo`: opens the desk unless told not to. "new" is in LONG_RUNNING for the same reason.
303
+ if (o["no-browser"])
304
+ return 0;
305
+ return main(["open", made.dir, ...(o.port ? ["--port", o.port] : [])], io);
306
+ }
284
307
  case "demo": {
285
308
  const target = resolve(io.cwd, rest[0] ?? "rushes-demo");
286
309
  const say = (await sayAvailable(sayRunner)) ? sayRunner : null;
@@ -293,7 +316,11 @@ export async function main(argv, io) {
293
316
  return main(["open", dir], io);
294
317
  }
295
318
  case "setup": {
296
- const only = o.only ? o.only.split(",").map((x) => x.trim()) : undefined;
319
+ const named = o.only ? o.only.split(",").map((x) => x.trim()).filter(Boolean) : undefined;
320
+ const unknown = named?.filter((x) => !HARNESS_IDS.includes(x));
321
+ if (unknown?.length)
322
+ return usage(io, `--only takes ${HARNESS_IDS.join(", ")}; ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not one`);
323
+ const only = named;
297
324
  const results = await setup(io.setupEnv ?? realSetupEnv(), { only, dryRun: o["dry-run"] });
298
325
  const mark = { added: "+", "would-add": "~", already: "=", "not-found": "-", failed: "!" };
299
326
  for (const r of results) {
@@ -312,10 +339,20 @@ export async function main(argv, io) {
312
339
  return 0;
313
340
  case "status": {
314
341
  const root = rest[0] ? resolve(io.cwd, rest[0]) : dir;
315
- const { tabs } = await (await ensureServer(root, io.ensure)).get("/api/tabs");
342
+ const { tabs, brief, storyboard, build } = await (await ensureServer(root, io.ensure)).get("/api/tabs");
343
+ // The second column starts in the same place on every line: as wide as the longest label shown.
344
+ const w = storyboard?.exists ? "storyboard".length : 8;
316
345
  for (const t of tabs) {
317
- io.out(`${t.stage.padEnd(8)} ${t.unlocked ? "open " : "locked"} ${t.todo ? `${t.todo} to do` : ""}`.trimEnd());
346
+ io.out(`${t.stage.padEnd(w)} ${t.unlocked ? "open " : "locked"} ${t.todo ? `${t.todo} to do` : ""}`.trimEnd());
318
347
  }
348
+ // §24 step 2: brief.md, when there is one: its status and how many sections the user has changed.
349
+ if (brief?.exists)
350
+ io.out(`${"brief".padEnd(w)} ${String(brief.status ?? "draft").padEnd(6)} ${brief.changed ? `${brief.changed} changed` : ""}`.trimEnd());
351
+ // §24.12: storyboard.md, and whether the plan is approved, once planning has begun.
352
+ if (storyboard?.exists)
353
+ io.out(`${"storyboard".padEnd(w)} ${storyboard.approved} of ${storyboard.shots} approved${storyboard.changed ? `, ${storyboard.changed} changed` : ""}`);
354
+ if (build?.started)
355
+ io.out(`${"build".padEnd(w)} ${build.ready ? "ready" : `waiting on ${build.waitingOn.join(", ")}`}`);
319
356
  return 0;
320
357
  }
321
358
  case "doctor": {
@@ -0,0 +1,84 @@
1
+ import { mkdir, stat, writeFile } from "node:fs/promises";
2
+ import { basename, join, resolve } from "node:path";
3
+ import { oneLineOf } from "../core/labels.js";
4
+ import { Store } from "../core/store.js";
5
+ // §24.10 step 1: `rushes new <folder>` starts a film in Rushes. It makes the project, the folders
6
+ // README and AGENTS recommend, and a brief.md for the agent to fill in with the user. The Assets tab
7
+ // already finds a Markdown file in the project root, so nothing here needs the dashboard to change.
8
+ import { BRIEF_FILE } from "../core/brief.js";
9
+ export { BRIEF_FILE };
10
+ /** The sections of brief.md, in order. AGENTS.md names every one; test/docs-start.test.ts keeps the two in step. */
11
+ export const BRIEF_SECTIONS = ["Title", "Purpose", "Audience", "Length and formats", "Tone", "Include and avoid", "Built with", "Open questions", "References"];
12
+ export function briefTemplate(name) {
13
+ return `# Brief: ${name}
14
+
15
+ Status: draft
16
+
17
+ Your agent drafts this with you. Change anything. Nothing gets built until you say the brief is approved.
18
+
19
+ ## Title
20
+ _The working title._
21
+
22
+ ## Purpose
23
+ _What this film is for, in one sentence._
24
+
25
+ ## Audience
26
+ _Who watches it, and what they already know._
27
+
28
+ ## Length and formats
29
+ Length: _seconds_
30
+ Formats: _for example 16:9, 9:16_
31
+
32
+ ## Tone
33
+ _How it should sound and feel. A film or two you would point at._
34
+
35
+ ## Include and avoid
36
+ Include: _what has to be in it._
37
+ Avoid: _what must not be._
38
+
39
+ ## Built with
40
+ _The tool your agent will build it in, or leave this blank._
41
+
42
+ ## Open questions
43
+ _Ideas floated but not settled, and anything the agent had to guess._
44
+
45
+ ## References
46
+ - _Brand files, screenshots, a film you like._
47
+ `;
48
+ }
49
+ async function exists(path) {
50
+ try {
51
+ await stat(path);
52
+ return true;
53
+ }
54
+ catch (e) {
55
+ if (e.code === "ENOENT")
56
+ return false;
57
+ throw e;
58
+ }
59
+ }
60
+ /**
61
+ * Turns `folder` into a Rushes project ready for the planning flow. The folder may be new or already
62
+ * hold files; nothing in it is overwritten. A folder that is already a Rushes project is refused.
63
+ */
64
+ export async function makeProject(folder, opts = {}) {
65
+ const root = resolve(folder);
66
+ if (await exists(join(root, ".rushes"))) {
67
+ throw new Error(`${root} is already a Rushes project. Open it with: rushes open "${root}"`);
68
+ }
69
+ // One clean line for both the project name and the brief's title; a blank name falls back to the folder's.
70
+ const name = oneLineOf(opts.name ?? "") || basename(root) || "Film";
71
+ await Promise.all(["renders", join("audio", "voiceover"), join("audio", "music"), join("audio", "sfx")].map((d) => mkdir(join(root, d), { recursive: true })));
72
+ await new Store(root).init(name);
73
+ let briefWritten = true;
74
+ try {
75
+ // "wx": fails instead of replacing a brief the user already wrote.
76
+ await writeFile(join(root, BRIEF_FILE), briefTemplate(name), { flag: "wx" });
77
+ }
78
+ catch (e) {
79
+ if (e.code !== "EEXIST")
80
+ throw e;
81
+ briefWritten = false;
82
+ }
83
+ return { dir: root, briefWritten };
84
+ }