Skip to Content
Starlight

Projects & sharing

A project is one folder with its surfaces (the LED outputs), scenes, media, history and memory. This section shows how to make, open, save and share projects.

What is in a project

Every project is a normal folder on disk. These are the main things in it.

project.yamlThe surfaces (the surfaces: key) and the brand kit
scenes/One .yaml file per scene
assets/, fonts/Imported media and fonts
context/What the project remembers: Claude chats and the brief (below)
extensions/The project's own effects and node types (Extensions)
generations/, renders/AI results and exports. They are never part of a version.
CLAUDE.mdTells Claude what the folder is. Add notes about the venue and the client here (What Claude knows).
.claude/Claude Code's files for this folder: your permission answers, and the project's own skills in .claude/skills/
.mcp.jsonHow Claude Code finds the running app: its address and the project's access token. Never part of a version. Do not share it.
.git/, .starlight/The version history, and this computer's state: the canvas layout, the last open scene, the Claude tabs, the access token and the generation records
.gitignoreKeeps renders, generations and this computer's files out of the versions
  • A project that you work on “With others, through Dropbox” keeps its history, caches, layout and access token on each computer instead, outside the synced folder. Its renders are in the project folder, so everyone gets them (How you work on a project).
  • A shared project's scenes/ folder also holds .locks/, the edit locks. Do not edit them.
  • The file formats are in project.yaml and Scene file.

Make a new project

A new project gets its own folder, its surfaces and a first scene.

  1. Choose File › New Project…, or press ⇧⌘N / Ctrl+Shift+N. The new project sheet opens.
  2. Type a name. The line under location shows the folder that Starlight will make, for example → ~/Documents/Starlight/live-nation-nyc.
  3. Check the location. To pick another place, click the folder button (choose a folder…).
  4. Under surfaces, click blank 1920×1080 or copy from. For copy from, pick a recent project in the list below it.
  5. Under How will you work on this project?, click Just me, on this computer or With others, through Dropbox (How you work on a project). Nothing is chosen at first. create stays grey until you choose.
  6. Click create, or press ⏎ / Enter in the name field. The new project opens.

If a scene of the open project has unsaved changes, Starlight first asks Save changes?, before it makes anything. Cancel makes no project, and the sheet stays open (Save changes before you leave).

  • The name is one line, up to 80 characters. The folder name is made from it, up to 40 characters: Halcyon Arena becomes halcyon-arena.
  • The default location is ~/Documents/Starlight. Missing folders are made.
  • The location only suggests a way. For a folder in Dropbox (or another synced folder), With others has the tag suggested. For a normal folder, Just me has it. You always choose.
  • blank 1920×1080 makes one surface called main.
  • copy from copies only the other project's surfaces, with their sizes and fits. For example, an arena's six surfaces. It never copies scenes, brand or assets.
  • The copy from list shows each recent project with its surface names. It starts on the open project. The button is grey when no recent project has surfaces.
  • Starlight makes project.yaml, with a fixed id: for the project. It also makes a first scene 01-main on every surface, an empty assets/ folder, a CLAUDE.md and the first version.
  • The notice then says, for example, created Halcyon Arena: “With others, through Dropbox”.
  • Starlight never overwrites a folder. It refuses a folder that exists and is not empty. It also refuses a location inside another project. The reason shows under the fields, and nothing is made.
  • If something fails half-way, Starlight removes what it made. Nothing that was there before is touched.
  • To close the sheet without a new project, press Esc, click ×, or click outside it.
  • Other ways to start: new project… on the Projects screen, or new project… in the command palette.
  • Claude can also make a project (The MCP tools). You then open it yourself: it is in File › Projects and File › Open Recent.

How you work on a project

Each project says how you work on it. There are two ways. You choose one when you make the project. You can change it later.

Just me, on this computerGenerations, tabs, version history and renders are kept in the project folder. Your Claude chats are kept on this computer. Open the project on this computer only.
With others, through DropboxScenes, media and renders are in the project folder, and everyone sees them. Your Claude chats, generations, tabs and version history stay on this computer. When you edit a scene, it is locked for the others (Lock a scene). Also choose this if you use the project on two or more computers.
  • The second name follows the folder: through OneDrive, through Google Drive, through iCloud Drive or through Box. For a folder that Starlight does not know, for example a network drive, it is through a network folder.
  • Starlight writes your choice into project.yaml as one line: shared: true (With others) or shared: false (Just me).
  • A folder in Dropbox only suggests “With others”. Starlight never changes the way by itself.

An older project that does not say yet. When you open it from a synced folder, Starlight asks once: How will you work on this project?

  1. Read the two choices. The tag now shows how the project opens today. The tag suggested shows Starlight's suggestion.
  2. Click one choice. Continue stays grey until you do.
  3. Click Continue. If you chose the way it opens now, Starlight only writes the line. Nothing else changes. If you chose the other way, Starlight first shows what it will copy (below).

Click Ask Me Later to decide later. Nothing is written, and Starlight asks again the next time you open the project.

Change the way. Your work must move to the new place first. Starlight copies it for you.

  1. Open Settings › Project. The row how you work shows the way.
  2. Click change…. A list shows what Starlight will copy: your Claude chats, generations, tabs and layout, and version history. Each row shows its size. Starlight counts them first; the numbers say counting… until then.
  3. Check the From and To folders, the total size and the free space.
  4. Renders are not copied. They are in the project folder in both ways, so they stay where they are.
  5. Click Copy and Switch. Starlight closes your open Claude chats, copies, and checks every copy. Then it switches, and the chats open again.
  6. When it says Done, click OK. Show the Folder opens the new place.
  • Nothing is moved or deleted. Starlight only copies. The originals stay where they are.
  • Starlight never replaces a file that is already in the new place. The Done step says how many files were already there.
  • Copy and Switch is grey while Starlight counts, when this computer does not have enough space, and while a generation, an export or a video version runs. The list says why.
  • The way changes only when every copy is complete. If something fails, or you click Stop, nothing is switched. The copies made so far stay, so the next try is faster.
  • If files are online-only, Starlight downloads them first. If a download does not finish, right-click the project folder in Finder (Mac) or File Explorer (Windows), choose Make available offline, and try again.
  • Starlight writes a small note on this computer about what it copied. So it never copies the same thing twice.

On another computer. When someone opens the project on another computer after the way changed, Starlight says so. It lists the work that computer still has in the old place.

  1. Click Copy Them to copy that work to the new place. Nothing is moved or deleted.
  2. Or click Not Now. Starlight does not ask again. Settings › Project then shows a line, The old place still has …, with a copy… button.
  • Renders are not offered here. They stay where they are.
  • If another computer changes the way while the project is open here, a notice says so. Nothing switches. Open the project again to see what to copy.
  • If two people work in “Just me” on the same project at the same time, their tabs and version history can break. Choose “With others” for a project that other people open.

The Projects screen

The Projects screen lists your recent projects, so you can open one with one click.

  1. Choose File › Projects, or type projects in the command palette.
  2. Click a project. Or use ↑ ↓ and press ⏎ / Enter.
  • The screen lists your 5 most recent projects, the newest at the top. A project whose project.yaml is gone drops off the list.
  • Each row shows a small map of the project's surfaces, at their real proportions. Then come its name and its path. Hover a row to see the full path.
  • A line under each name gives details, for example 6 surfaces · With others, through Dropbox or 1 surface · Just me, on this computer.
  • An online-only project says online-only in Dropbox · opening downloads it. A broken one says its project.yaml can't be read.
  • The open project has the tag open.
  • When you click a project, its row says opening… while Starlight checks the folder. Then the screen goes away, and the canvas says opening and the project's name (Switch projects).
  • If the project does not open, the screen comes back and shows the reason.
  • At the bottom: new project… (⇧⌘N / Ctrl+Shift+N) and open… (⌘O / Ctrl+O).
  • Esc, × or a click outside closes the screen.

When no project opens at start. If Starlight cannot open a project when it starts, this screen fills the window. The error is at the top, with retry and copy error.

  • If macOS blocked the folder, the title is Starlight was blocked from reading your project folder.
  • The hint then says: grant Starlight access to Documents in System Settings → Privacy & Security → Files & Folders, or open the folder via Open Project…
  • For any other problem, the title is Starlight couldn't open your project.

Open a project

Open Project opens any project folder, from anywhere on your disk.

  1. Choose File › Open Project…, or press ⌘O / Ctrl+O. The command palette has open project… too.
  2. Pick the project folder, the one with project.yaml in it.
  3. Click Open.

Open Project accepts more than the exact folder:

You pickIt opens
the project folder (the one with project.yaml in it)that project
project.yaml itself (Mac only. On Windows the picker shows only folders)its project
a job folder with one project inside it, for example 2611-halcyon/halcyon-arena/that project
a folder with several projects inside itnothing. The message names them, so you can pick one
any other foldernothing. The message says that there is no project.yaml in it
  • The picker starts in the folder that holds the open project.
  • File › Open Recent and the Projects screen open a recent project in one click.
  • A shared project with online-only files downloads them as it opens.
  • When Starlight starts, it opens your last project. With no recent project, it opens the demo in ~/Documents/Starlight/bolts-demo.
  • If a scene of the open project has unsaved changes, Starlight first asks Save changes? (Save changes before you leave).
  • File › Reload Project from Disk (⌘R / Ctrl+R) reads the open project from disk again. It asks first, and keeps the unsaved edits of every scene as recovery drafts.

Switch projects

Only one project is open at a time. Opening another project switches the whole window to it.

  1. Open the other project from the Projects screen, File › Open Recent or File › Open Project….
  2. If a scene of the project you leave has unsaved changes, Starlight asks Save changes? first. Click Save, Don't Save or Cancel (Save changes before you leave).

While the project opens. The middle of the canvas says opening and the project's name, for example opening Halcyon Arena…. A spinner turns above it while Starlight works, and the old project is greyed out.

  • The line shows for every way you open a project: the Projects screen, File › Open Recent, File › Open Project…, New Project… and retry. It also shows when the project opens again after you change how you work on it.
  • The line shows as soon as you pick the project. First Starlight checks the folder. This can take a few seconds, for example for a project in Dropbox on Windows. While it checks, the line shows the folder's name, and the old project still works: Save changes? can still come.
  • Then the project starts to open. The line shows the name from project.yaml. When Starlight has not read that file yet, it still shows the folder's name.
  • Once the project starts to open, you cannot click, drag, scroll, right-click or drop files on the old project. The keys that zoom and fit the view do nothing.
  • Save (⌘S / Ctrl+S) and Save All do nothing while the line shows. The transport and the panels stay as they are.
  • The keys that change the old project also do nothing: Delete, Undo and Redo, the arrow keys that move the selection, the layer order keys, B, ⇧M, and the keys for the next and previous scene. Space still plays and pauses.
  • The line goes when the new project has loaded on the canvas.
  • If the project does not open, the line goes and the old project stays. The reason shows in the same place as before. For File › Open Recent and File › Open Project…, that is the notice line at the top of the window.
  • When Starlight starts, the canvas says loading project… instead, with the same spinner.
  • Sometimes the project opens, but none of its scenes can open. Then nothing of the old project stays: the canvas is empty, and its middle says why, for example error — this project has no scenes. In Dropbox, the scenes of a shared project may still be downloading. Then the line says so, and the scenes open when they arrive.
  • Each project keeps its own layout and its last open scene.
  • Undo starts empty in the project that you open. ⌘Z / Ctrl+Z never undoes an edit from the project that you left (Undo and redo).
  • Each scene opens with its own saved view, on the canvas and in the node graph. A scene with no saved view shows all of it. The timeline also remembers its zoom and scroll for each scene of each project.
  • Nothing stays selected, soloed or locked from the old project.
  • Panels and dialogs that show work of the old project close: the tile plan, the export sheet, the Versions list, a right-click menu, and the Make Loop, frame and rename dialogs. The New Generation form closes too. The line missing files · render anyway goes.
  • An offer in the Assets panel, for example old file logo.png unused — remove?, goes too. Starlight never removes a file from the project that you open because of an offer from the old project.
  • A ⌘K / Ctrl+K request that still waits for Claude is not sent in the new project. It comes back in the bar, and the line says why. To use it in the new project, send it again.
  • Each project keeps its own Claude chats. They stop when you leave, and continue when you come back.
  • If chats were running when you leave, the notice line says so. For example: 2 Claude chats stayed with Bolts Arena. To bring one here: right-click the Claude panel › resume an earlier chat…. The line is also in Help › Recent Messages….
  • To use one of those chats in the new project, open a copy of it there (Resume an earlier chat, "Chats from your other projects"). The chat itself stays with its project.

Rename a project

Renaming changes the project's display name. The folder on disk keeps its name.

  1. Open Settings: click the gear (top right), or press ⌘, / Ctrl+,.
  2. Click Project.
  3. Click the name field and type the new name.
  4. Press ⏎ / Enter, or click outside the field. To cancel, press Esc.
  • A name is one line, up to 80 characters. If a name is not allowed, the reason shows under the field.
  • The note under the field says a display name: the folder keeps its name.
  • Nothing moves on disk, or on another artist's machine.
  • The rename is saved as a version.
  • It works in a shared project too. The other artists see the new name.
  • The Projects screen shows the new name. The path still shows the folder name.

Copy a project folder

A copied project folder keeps the project's id, the id: line in project.yaml. Starlight files some of a project's work under that id: its Glimpse looks, and in a shared project its version history, generations and Claude chats on this computer. So a copy that keeps the id mixes with the original.

When you open a copy on the computer where the original last opened, Starlight asks first: This looks like a copy of “halcyon-arena”. The question names the id and shows the other folder's full path.

  • Make It Its Own Project gives the folder you are opening a new id, and the project opens with it. Only the id: line changes. The other folder does not change.
  • Leave It keeps both folders as they are, and Starlight does not ask about these two folders again. ⏎ / Enter and Esc choose Leave It.
  • When the folder is in Dropbox or another shared folder, the question says that the new id reaches everyone who works on the project.
  • The same folder reached another way is not a copy, and Starlight asks nothing: through a link, in another case, in a renamed team folder, through a second Dropbox folder, or on a mapped drive and its network path.
  • Starlight also asks nothing when the other folder is gone, has another id, or cannot be read right now (for example, its project.yaml is online-only in Dropbox).
  • Starlight changes the id only when you click Make It Its Own Project. Going back to a version keeps the id the project has now (Save and go back to a version).
  • Starlight cannot see a copy on another computer.

Save and go back to a version

Saving writes the open scene to disk. Every save is also a version: a saved copy of the project that you can go back to.

Save.

  1. Press ⌘S / Ctrl+S.
  2. Check the notice. It says saved <scene>.yaml.
  • A save writes the open scene and where the surfaces sit on your canvas.
  • Other scenes keep their unsaved edits until you save them. To save every scene with unsaved changes, choose File › Save All or press ⌥⌘S / Ctrl+Alt+S. Each scene is saved as its own version.
  • ⌘S / Ctrl+S works everywhere: in a text field (Starlight takes the value you typed first), in a list, in the command palette and in the Claude terminal.
  • The amber dot next to the scene name means "not saved". After a save, the note says, for example, "saved 12s ago".
  • If a save fails, the error SAVE FAILED — <scene>: … gives the reason. It stays at the top of the window until you click its ✕.
  • Sometimes the scene is saved, but the version cannot be made at that moment. Then the notice says saved <scene>.yaml · checkpoint will retry at the next save. Your work is on disk. You do not have to do anything: the next save makes a version with these changes too. This can happen on Windows when another program (Dropbox, OneDrive, an antivirus or another git tool) holds a version file for a moment. Starlight first tries again a few times, for up to about 4 seconds.
  • The same note can follow a delete, a rename or a move in Assets, or a scene rename or delete: the change is done, only its version waits. If versions fail 3 times in a row, a warning stays at the top of the window: Versions are not being saved: …. It says why, and what to do. Your files are still saved. The warning goes away when a version is made again. If a git program stopped and left its lock file (.git/index.lock, more than 2 minutes old), Starlight deletes that file once and tries again.
  • Starlight does not save a scene for you. But it never loses unsaved edits without a warning: every scene keeps them while the project is open, and they are kept as a recovery draft too.

Go back to a version.

  1. Click v in the top-right buttons. The versions list opens, with the newest version first.
  2. Click the version you want. Each row shows how long ago it was made, for example 3m ago, and its name if it has one. Under that, a short line in grey says what changed, for example N surface: slower gold shimmer, loop fixed at 27.8 s (What each version says, below).
  3. If any scene has unsaved edits, Starlight asks first: Restore this version? Your unsaved changes will be lost. Click Restore, or Cancel.
  • Starlight makes a version on every save, and on every change it writes for you. Examples: a ⌘K compose request, a change by Claude, an import, a scene rename or delete, a project rename.
  • The tag current marks the newest version.
  • A restore makes a new version from the restored files. Its line says which version came back, for example restored version from 14:05, and current moves to it. If the files are already the same, no new version is made.
  • To name a version, click ✎ next to it. Type a name and press ⏎ / Enter, or click away. Esc cancels. A name needs a letter or a number.
  • A new project starts with one version. A list with no versions says no snapshots yet.
  • A restore writes back every file as it was in that version. Later versions stay in the list.
  • ⌘Z / Ctrl+Z cannot undo a restore. To go back, click the newer version in the list.
  • A restore does not delete files made after that version. For example, a newer scene stays in the scene list. Delete it by hand if you do not want it.
  • A restore never goes back in context/ (what the project remembers).
  • A restore keeps the project's id, the id: line in project.yaml (Copy a project folder).
  • The history is kept with git (a version tool) on your machine. It works offline and is never uploaded.
  • In a shared project the history is per machine. v lists only your own versions, and they cover only project.yaml, the scenes and extensions. Dropbox keeps its own history of the shared files.
  • In a shared project a restore is refused while another artist is editing a scene that it would change.

What each version says. Every version has a description: one short line that says what changed in it.

  • The line is under the time and the name, in grey. A long line shows on two rows at most. Hold the pointer over it to read all of it.
  • Claude calls versions checkpoints. When you read Claude's messages, a checkpoint is a version in this list.
  • Claude writes it for every change Claude makes. It names the surface, scene or layer, and says what changed and why, in a few words. Example: S surface: seam moved off the singer's face.
  • When Claude finishes a task that made several versions, it can write a new line for the last one, so that this line sums up the whole task.
  • Starlight writes it for the versions it makes for you. Examples: saved 02-walls when you press ⌘S / Ctrl+S, imported logo.png, renamed scene intro to opener, restored version from 14:05. These lines use no AI and cost nothing.
  • Claude never changes the name you typed with ✎. The name is yours.
  • Do you want your own saves described? Ask Claude, for example: describe my last three saves. Claude looks at what changed and writes a line for each.
  • Versions made before Starlight had descriptions have no line. Their rows look as before.
  • The descriptions are kept with the version history, in git. They stay with it when you switch a project between local and shared. In a shared project, like the history, they are on this computer only.

Save changes before you leave

Before unsaved work leaves the window, Starlight asks: Save your changes to "02-walls" before you quit? With several scenes, it counts them and lists their names.

It asks before:

  • you quit (⌘Q, or Quit in the Dock),
  • you close the window (its ✕; on Windows also Ctrl+W, which is Window › Close, and Alt+F4),
  • another project opens (File › Open Project…, File › Open Recent, the Projects screen),
  • a new project is made (File › New Project…). It asks before the project is made.

While an export runs, Starlight asks about the export first (Quit or switch during an export). It asks Save changes? only after the export stops.

  1. Read the question. The second line names the scenes with unsaved changes.
  2. Click one button:
    • Save saves every scene with unsaved changes, then goes on. If a save fails, nothing closes, and the error stays on screen.
    • Don't Save drops the unsaved changes, and their recovery drafts too. Then it goes on.
    • Cancel does nothing. You stay where you are.
  • With nothing unsaved, Starlight asks nothing.
  • On a Mac, the red close button of the window shows a dot while anything is unsaved.
  • If the window does not answer (it is frozen), Starlight asks if you want to go on anyway. Then your edits are only in the recovery drafts.
  • Stopping Starlight from a terminal, or a log-out that stops it, does not ask. The unsaved edits stay as recovery drafts (Get unsaved edits back).
  • Help › Troubleshooting › Force Reload App asks its own question, and keeps drafts.

Undo and redo

Undo takes back your last edit to the open scene. Redo puts it back.

  1. To undo, press ⌘Z / Ctrl+Z.
  2. To redo, press ⇧⌘Z / Ctrl+Shift+Z.

A short notice names the step, for example undid: compose. With nothing to undo it says nothing to undo, and with nothing to redo nothing to redo.

Undo coversUndo does not cover
Every change to the open scene: layers, properties, keyframes, effects, masks and the graph layoutThe view: zoom, pan, focus, the selection, panels and layouts
The scene's length and fpsFile actions: import, and rename, move or delete an asset
A ⌘K compose request, as one stepNew, rename, duplicate or delete a scene, and a project rename
A grade on a generationA version restore, a save, and changes in Settings
Moving a surface on the canvas: one drag, or arrow presses in a row, as one step (Arrange the surfaces). A new, moved or deleted guide, one step each (Rulers and guides)The generations themselves
A drop on the canvas or the graph, and place on canvas, as one step (the file stays in Assets)
Reload after a change by another program or another artist
Restore my changes on the recovery card
A change from outside the window, as one step of its own: Claude, a generation that lands in the scene, or another artist's edit in a shared project (Undo Claude's change)
  • For the things undo does not cover, go back to a version.
  • After a change from outside, the first ⌘Z / Ctrl+Z undoes only that change. Your own edits stay. The notice says undid: external edit, or undid: another artist's edit. The next ⌘Z / Ctrl+Z undoes your last edit. ⇧⌘Z / Ctrl+Shift+Z brings the outside change back.
  • A change from outside clears redo, as your own edits do. A change that only rewrites the file in a new layout, with the same content, is not an undo step.
  • Each scene has its own undo history. When you switch scenes, undo follows the scene you open. A scene keeps its history when you come back.
  • Undo keeps up to 100 steps per scene. One drag is one step.
  • In a text field, ⌘Z / Ctrl+Z undoes your typing instead.
  • Edit › Undo and Edit › Redo undo the scene too. The menu names the step, for example Undo Move Keyframe. In a text field they undo your typing, and read just Undo and Redo.
  • On Windows, Edit › Redo is Ctrl+Y. Ctrl+Shift+Z also redoes, outside a text field.
  • The undo history ends when you quit Starlight, and when you open another project. Each project starts with an empty history, also when you come back to it.

Get unsaved edits back

Starlight keeps a copy of your unsaved changes on this computer, a few seconds after each edit. This copy is a recovery draft. If Starlight closes, crashes or reloads before you save, the draft is not lost.

  1. Open the project again. A card appears in the lower left of the canvas, above the transport. For example: Starlight closed before your changes to "02-walls" were saved.
  2. Read the second line. It says when you last edited the scene and what changed, for example Last edit: today 18:49 · 3 layers changed.
  3. Click Restore my changes to bring the changes back into the scene. Or click Keep saved version to delete the draft. Or click Later to hide the card and decide later.
  4. After a restore, press ⌘S / Ctrl+S to save the changes. Until you save, they are not in the scene file.
  • After a restore, a notice says Your changes to "02-walls" are back. They are not saved yet: press ⌘S to save them. (Ctrl+S on Windows).
  • ⌘Z / Ctrl+Z right after a restore undoes it. The scene goes back to the saved file.
  • Keep saved version asks first: Delete your unsaved changes to "02-walls"? The scene stays as it was last saved. You cannot get these changes back. Click Delete Changes to delete the draft, or Cancel to keep it.
  • Later hides the card. Every draft stays. In the scene list, those scenes have an amber recover tag: click it to see the card again. Or choose File › Recover Unsaved Changes… (palette: recover unsaved changes…). If there is nothing to recover, a notice says No unsaved changes to recover.
  • A draft you put aside with Later is safe: new edits to that scene, and saving the scene, do not replace it. It stays, also after you quit and open the project again, until you restore it or click Keep saved version.
  • Point at a button to see what it does.
  • The first sentence says why the changes were not saved: Starlight closed before…, Starlight reloaded before…, You opened another scene before…, You opened another project before…, or Another program changed "02-walls" before your changes were saved.
  • The changes are counted by comparing the draft with the saved scene, for example 3 layers changed, 1 layer added, layer order changed, scene settings changed or graph layout changed. After three parts, the card says and more. If Starlight cannot read the draft, the card still offers it, without this line.
  • If changes to several scenes were not saved, the card lists them all, for example Starlight closed before your changes to 3 scenes were saved. Each scene has its own row and its own two buttons. The open scene is first. One Later button at the bottom hides the whole card.
  • Starlight only asks when the draft really differs from the saved scene. A draft with no real change is deleted without a question.
  • The draft is deleted when you save the scene, when you click Keep saved version and confirm, when you restore and then save, or when you choose Don't Save before you quit. A draft you put aside with Later is not deleted by a save.
  • The card stays until you choose, until you click Later, or until you save.
  • The card never offers a draft of a scene whose unsaved edits are still open in Starlight (you left that scene for another one). Those edits are already there.
  • Starlight writes a draft about 3 seconds after your last edit. It also writes one when you leave the window, switch scene or project, or reload.
  • Drafts stay in the app's data folder on this computer. They are never in the project folder, so they never sync.
  • A draft that is never offered back is deleted after 30 days.
  • Quitting with unsaved changes asks Save changes? first (Save changes before you leave). Don't Save deletes the drafts too. Quitting with nothing unsaved leaves no draft.
  • Stopping Starlight from a terminal (Ctrl+C) quits it without the question: it releases your edit locks and keeps the last drafts.
  • With unsaved edits in any scene, ⌘R / Ctrl+R asks before it reloads. It keeps a draft of every unsaved scene first. Help › Troubleshooting › Force Reload App (⇧⌘R / Ctrl+Shift+R) always asks first, then keeps a draft.
  • The Reload view button (it shows when the canvas fails) also keeps a draft first.
  • If Starlight cannot keep a draft, it asks you before the edits are lost.

Share a project through Dropbox

A shared project is a project in a synced folder. Dropbox, or a similar service, copies that folder to every artist's computer. Several artists can work in it at the same time.

  1. Put the project folder in Dropbox. Or make it there with File › New Project….
  2. Each artist opens that folder with File › Open Project… (⌘O / Ctrl+O).
  3. Each artist sets their name once in Settings › Project › artist name.
  4. Work as usual. Your first edit of a scene locks it. Another artist's scene shows a padlock with their name.
  • On a Mac, Starlight recognises the folders of Dropbox, OneDrive, Google Drive, Box and iCloud Drive. On Windows it recognises Dropbox, OneDrive and Google Drive. In such a folder, Starlight suggests “With others”. You choose (How you work on a project).
  • Settings › Project › how you work then says, for example, With others, through Dropbox.
  • Scenes, assets and project.yaml sync. Each save is written whole, so the others never get half a file.
  • Renders sync too: exports and saved stills go into the project's renders/ folder (Where the files land).
  • Each machine keeps its own version history, caches, layout and generations outside the synced folder. Settings › Project › how you work has a button that opens that folder. On Windows it is in %APPDATA%\Starlight (Windows: where your data is).
  • Videos are prepared (ingested) in your machine's media cache, not in the shared folder.
  • Cut-outs are saved in the shared folder, in assets/.cutouts/, so every artist sees the same cut-out. A Mac makes each one once, and Windows uses it (Cut a subject out of a photo).
  • HEVC with alpha shows its transparency only on a Mac. If someone opens the project on Windows, use ProRes 4444 or WebM with alpha instead (Video with transparency).
  • The Assets panel says “With others, through Dropbox”. It lists online-only files, with make available offline. To keep the whole project on your Mac, right-click its folder in Finder and choose Make available offline (Online-only files).
  • A scene that is still downloading shows in the scene list as downloading…. It opens when the download ends.
  • project.yaml must download first. Starlight waits up to 30 seconds for it. If it is still not there, open the project again.
  • Generations, their grades and their cost stay on the machine that ran them. The others see the asset you import, with its .gen.json.
  • Exports go to your machine. An export into the shared folder is refused.
  • shared: false in project.yaml (“Just me”) opens a synced folder as a normal project. Its .git folder (the version history) is then in Dropbox. Open it on one computer only.
  • shared: true opens a synced folder that Starlight does not recognise, for example a network drive (NAS), as shared.
  • Do not copy a shared project folder to start a new project. The copy keeps the same id:, so both use one history on your machine. Use File › New Project… with copy from instead.
  • Working offline: A shared project offline.

Lock a scene

In a shared project, a lock shows who is editing a scene. Only that artist can change it.

  1. Open the scene. Looking, switching and playing lock nothing.
  2. Make your first edit. The scene is now locked to you, and the padlock closes.
  3. When you finish, click the padlock to unlock the scene. If you have unsaved edits, Starlight asks you to save first.

The padlock is to the right of the scene name, at the top right. Hover it to see the machine, when the lock started and when that machine was last seen. For example: on studio-mac — since 3 min ago, last seen 12 s ago.

PadlockMeaningClick it to
open, faintFree: nobody is editing the scenelock it now
closedYours: the others see the scene as read-onlyunlock it (it asks to save first)
closed, with a nameThat artist is editing it: read-only for youtake it over (it asks first)
  • The save question says: Save 02-walls before you unlock it? Click Save and Unlock. Cancel keeps it locked.
  • Your lock also ends when you switch scene, close the project or quit. But a scene that you leave with unsaved edits keeps its lock: the lock ends when you save those edits, or drop them (Don't Save, or Reload Project from Disk).
  • Your machine renews the lock every minute. After a crash, your lock ends after 5 minutes without a signal from your machine.
  • The clocks of the computers must be right. A clock more than 5 minutes behind makes its locks look ended to the others.
  • Moving a surface on your canvas locks nothing. That layout is only on your machine.
  • While another artist holds a scene, your machine refuses every change to it. That covers a save, a change by Claude, and a rename or delete of the scene. It also covers an asset replace or move that changes the scene, use theirs, and a version restore.
  • Claude can still change a free scene. That does not lock it.
  • A new artist name applies at once, also to a lock you hold.
  • The Assets panel lists what the other artists are editing, under the shared-project line.

Edit a scene someone else has

A scene that another artist has locked is read-only for you: you can look at it, but not change it.

A bar says, for example, Dana is editing 02-walls — read-only here. If you edit it, Starlight undoes the edit at once. ⌘S / Ctrl+S and Claude's changes to that scene are refused.

  • The notice then says, for example, read-only — Dana is editing 02-walls; save a copy, or take it over from the lock.
  • The bar goes away when Dana unlocks the scene, switches scene, closes the project or quits. It also goes after 5 minutes with no signal from Dana's machine.

Take over the scene.

  1. Ask the other artist first. If you both save, the last save replaces the other one.
  2. Click edit anyway on the bar, or click the padlock.
  3. Starlight asks: Take 02-walls over from Dana? Dana goes read-only and keeps any unsaved edits only as a copy. If you both save, the last save is kept. Click Take Over.

The lock is now yours. Dana's bar then says Sam took over 02-walls — read-only here.

Keep your edits as a new scene.

  1. Click save as a copy on the bar. This button shows only when you have unsaved edits.
  2. Starlight saves your edits as a new scene with the next free name, for example 02-walls-copy, and opens it.

The notice says, for example, saved your edits to 02-walls as 02-walls-copy. The original scene stays as it is on disk.

  • Two artists can lock the same free scene at almost the same time, before Dropbox syncs. Every machine then gives the scene to the same artist: the first one to lock it, or the latest one to take it over.
  • The other artist is told, for example Dana locked 02-walls first — read-only here. Unsaved edits are never lost: use save as a copy.

When another artist saves

Another artist's save arrives through Dropbox. If you have no unsaved edits on that scene, it reloads with their version.

If you have unsaved edits on that scene, nothing is replaced. A bar says Another artist changed "02-walls" (Dropbox sync) while you have unsaved changes. If they deleted or renamed the scene, the bar says so.

  1. To take their version, click Reload. ⌘Z / Ctrl+Z brings your edits back.
  2. To keep your version, click Keep mine. Then press ⌘S / Ctrl+S to save over theirs.
  • After Keep mine, their version is still in Dropbox's version history.
  • Did they change another scene, project.yaml or the fonts? Then everything else reloads, and your open scene keeps its unsaved edits.
  • Did they change a scene that you left with unsaved edits? Your edits stay. A warning says so. When you save that scene, yours replaces theirs.
  • A change by Claude works the same way (Undo Claude's change).

Resolve a conflicted copy

Two machines can save the same file before either sees the other's save. Dropbox then keeps both files: the second one is a conflicted copy.

For example: 02-walls (Dana's conflicted copy 2026-10-18).yaml. Starlight never shows it as a scene. A bar says 2 Dropbox conflicted copies — choose a version.

  1. Click review on the bar. A row opens for each copy, for example 02-walls — Dana's version, 2026-10-18.
  2. For each copy, click keep mine (your file stays) or use theirs (the copy replaces your file).
  3. Check the notice. It names the folder where the copy went.
  • Either way, the copy and any file it replaced move to this machine's archive of conflicted copies. Nothing is deleted.
  • The archive is in the folder that the folder button of Settings › Project › how you work opens.
  • To compare first, open the copy in a text editor. Its full name is in the row's tooltip.
  • hide closes the list again.
  • A copy that is still online-only shows — downloading…. Its buttons work when it is on disk.
  • use theirs refuses a copy that is not valid YAML. Fix or remove that file by hand.
  • Is that scene open with unsaved edits? Then use theirs asks first (When another artist saves).
  • If another artist resolves the same copy first, it is removed from your list too.
  • Starlight finds copies of scenes and of project.yaml. It does not find a conflicted copy of an asset, a font or an extension.

Use media from a shared folder

A project can use media from a folder outside the project, for example the team's Dropbox media folder. The folder is named under media: in project.yaml.

  • Starlight never writes into that folder. Its videos are prepared in this machine's media cache.
  • To add a folder, read the status badges and work offline, see Use linked media.
  • To point the folder at your own copy, see Settings › Media.

What the project remembers

A project keeps plain files about your direction and its AI work. So the next session, on any machine, starts from what was decided.

To see them, open the project folder. On a Mac choose File › Reveal Project in Finder; on Windows, File › Show Project in Explorer. The folder button in Settings › Project works too.

context/sessions/
Every Claude chat in the project, one file each: <date>_<artist>_<chat>.md. The app writes it while the chat runs. It has your words exactly, with the time, your name and the open scene. It also has Claude's replies, and one line for each thing Claude did.
The day's ⌘K compose requests are in a …_compose.md file next to them. Secrets are removed before anything is written. Do not edit these files.
context/direction/: the brief
Dated points of direction, decisions, likes and dislikes, for each scene. Claude adds a point, in your words, when you give direction or feedback. Claude reads every artist's brief before it plans anything.
There is one file per artist and machine (<artist>@<machine>.md), so two artists never write the same file (The brief).
generations/<id>/generation.json
Next to each generation's results: its prompt, model, settings, inputs, cost, status and grade. It is only on the machine that ran the generation.
assets/<file>.gen.json
The same facts, next to an asset you imported from a generation. It is part of each version and syncs with the asset. If you rename or delete the asset, the same happens to this file.
So the other artists, and their Claude, can see how a file was made. The Assets panel hides this file.
Notes on the graph
The sticky notes in the node graph are saved in the scene file. They are part of each version and sync with the scene.
  • A version restore never goes back in context/. Going back to an earlier scene never removes what you said since.
  • In a shared project, context/ syncs through Dropbox.

On this page