Projects and history

A Cue project is one plain file, and Cue keeps a history of every change to it, by you or by an agent, across sessions.

Project files

A project is a .cueproj file: plain JSON that diffs and versions well, with its own icon in Finder. Older .cue.json projects open too and are renamed to .cueproj when opened.
New projects get their own folder in your projects folder, ~/Movies/Cue by default. Change it in Settings → General → Projects, where you can also choose to reopen the last project on launch.
Media stays where it is on disk. Its paths are stored relative to the project when possible, so a project folder can move with its media.
Cue saves as you work. ⌘S saves right away, and File → Save As… (⇧⌘S) saves a copy somewhere else and switches to it; the media stays where it is.
Exports go to an export folder next to the project unless you choose another place.

The projects overview

Cue opens on the projects overview unless it reopens your last project. Get back to it with the button at the left of the header or File → Show All Projects (⇧⌘O).

Every project in the projects folder and every recent one, newest first, with a poster frame.
Search by name, and sort by most recent or by name.
Each project can be duplicated, shown in Finder or removed from the recent list.
Projects that moved, were deleted or cannot be read are marked as such.
Agent access copies the command that connects an MCP client (see AI and agents).

Collections group projects like folders, for example the pieces of one video: its edit, graphics made as their own projects, other versions. They are listed on the left of the projects overview with how many projects each holds.

Make one with + next to Collections, then drag projects onto it, or use a project's menu → Move to collection.
A project is in one collection at most. Duplicates join the original's collection.
Rename or delete a collection from its right-click menu. Deleting one never deletes its projects.
Agents use list_collections, create_collection, move_to_collection, rename_collection and delete_collection.

Packaging a project

File → Package Project… puts the project and every media file it uses into one zip that opens anywhere, to share or archive it. Long footage is trimmed to the parts the edit uses, with one-second handles, so a few shots from a feature film stay small. Caches and history are left out; Cue makes them again. Agents use package_project, optionally with a README of credits.

Projects as media

Place one project inside another, like a pre-composition shared between projects: Media → Add another project as media… (or add_project_media). Cue renders it, graphics included, and renders it again when that project changes: when you open this one, come back to Cue, or export. Its media has a Project badge that opens the source project.

Relinking moved media

When a project opens, Cue looks near the project for files that were moved. Anything still missing is shown as offline, with a bar over the editor:

Click Relink media.
Locate one missing file. Other missing files in the same folder are found with it.
Or search a whole folder for the missing media.

When everything is found, the dialog says so and the bar goes away.

Agents see offline media in get_state and can fix it with find_offline_media or relink_media.

History

⌘Z and ⇧⌘Z undo and redo, for your edits and an agent's alike. Beyond that, every change is kept with who made it and when, in a hidden .cue-history folder next to the project (Cue adds it to .gitignore).

The History panel lists every step, grouped by day, across sessions. Filter it to Everything, You or Agents.
Each step shows which timeline it changed, so edits in nested or other sequences are easy to find.
Click a step and choose Go back to this point to restore the project to how it was right after it.
Restoring is a step of its own, so ⌘Z takes you back to where you were.

The Agent workspace (⌥6) docks the history beside the viewer, so you can follow what an agent changes as it works.