Selected item
Assets tab
Use Assets to confirm imported media, read per-clip readiness, filter by type or action needed, and add clips to the base timeline at the playhead.
docs.theshellx.com / Cut manual
Learn Cut from the interface.
Setup, editing, Generate, delivery, and the Debug API in one manual. Use the tree to find the exact tool, menu item, filter, or panel you need.
Interface map
Click a feature to see where it lives.
Recording Studio
Record with F9, keep the original, then edit.
Choose screen and sound
Open Record from the Edit | Record switch. The left side selects a display or, on Windows and macOS, an application window, microphone input, system audio and recording mode. Linux opens its system screen-sharing picker when capture starts. Use Refresh sources after a display or device changes. Test microphone and Test system audio check sound without saving a recording.
Raw or Polished
Raw keeps the original capture. Polished also adds an editable clip with cursor smoothing, zoom-to-cursor and framing to the open project. Turn on Show keystrokes beneath Polished if you want them in the demo; it is off by default. Both modes save the unchanged original MP4 automatically when you stop.
Use the right-side settings
Choose Camera, Background, Video timer, Capture timing or Video quality. That section's controls appear directly below the buttons. You can switch sections without losing draft settings. Current Record choices also stay available when you return to Edit and start with F9.
Choose your camera layout
In Polished mode, enable Camera, choose a device, then select any of the four corners, Circle or Rounded rectangle, and the size. Your placement stays selected until Reset camera layout. Cut saves camera video as a separate editable take. Camera capture is currently supported on Windows and macOS; a missing device or permission leaves it unavailable without preventing screen-only recording.
Preview real captured pixels
Use the source preview below the picture to choose and inspect the actual display or window before Start. Rehearse makes a disposable video-only test without adding a recording or timeline clip. During capture, the preview shows live frames from that recording. If the source becomes unavailable, Cut reports that state and keeps Stop usable. Whole-display capture includes Cut when it is visible; minimize Cut or cover it with the app you are demonstrating to keep it out of the picture.
F9 works without opening Record
With Cut open, press F9 to start or stop using your current Record settings, or your saved settings if you have not opened Record. Cut does not switch to Record or bring its window forward just to start. It uses the open project, or creates a recording project automatically when none is open. When the OS global shortcut is available, F9 also works with Cut minimized and another app focused. Cut shows when only the focused shortcut is available. F12 adds a marker during recording.
Save first, export afterward
Stop saves the unchanged original MP4 to the default export folder in both modes. Polished also adds the editable clip to your project. Afterward, Export MP4 or Export GIF chooses a destination for the polished result; Save a copy copies the original, and Raw offers Add to timeline. Export folder settings changes the default folder. There is no Save location picker before recording.
Two different countdowns
Capture timing controls the delay before Start and whether capture ends after a chosen length or runs until Stop. Video timer adds an overlay: Off, Count up or Count down, with a custom HH:MM:SS duration and quick minute choices. Its Pause, Resume, Reset, Restart and End buttons affect the visible timer only. Reaching zero does not stop capture.
Quality and capture Pause
Choose frame rate and quality in Video quality. An advanced custom frame rate accepts a whole number from 1 to 240 only after Apply or Enter; invalid input keeps the previous rate. Capture Pause & resume is a separate, opt-in macOS capability for an exact display at a whole-number frame rate. That mode excludes Camera, scenes, keystrokes, window capture and quality options. Other platforms explain when Pause is unavailable.
Recording details and recovery
After Stop, the area below the preview reports the recorded streams, pointer information and shortcut status. If Stop fails, Cut checks whether that exact capture is still active before offering Retry Stop; uncertain or ended capture is reported explicitly. Do not assume that an error means the take has saved.
Long recording safety
Microphone and Windows system audio are written continuously with bounded memory. Cut exposes the raw WAV only after it finishes cleanly and stops before the WAV format limit could corrupt a long capture.
Windows system audio
On supported Windows 10 and 11 builds, Cut records system audio without opening the physical output driver. Security software may ask once for the new Cut build; if access is denied, screen and microphone recording continue and the missing stream is reported.
macOS system audio
On macOS 14.2 or newer, Cut records system audio through a Core Audio process tap alongside ScreenCaptureKit. The first recording may request Screen Recording and Audio Capture separately; approve both, restart Cut if macOS asks, and retry. A successful take includes system.wav.
Permissions and unavailable controls
The OS may request screen, microphone, camera or system-audio permission for the feature you choose. Allow the requested access and reopen Cut if the OS requires it. An unavailable device or capability shows its reason; it does not become enabled just because another recording option is ready.
First run
Setup is part of the editor.
FFmpeg
Required for clip probe, proxy media, screen recording, preview
media, and final export. A fresh PC often needs FFmpeg installed
before Cut can work like a video editor. If it is missing,
Preview points directly to the Video processing setup card. On
Windows and Linux x86_64, choose Install there to consent to
Cut's separate verified runtime. On macOS, install Homebrew's complete build with
brew install ffmpeg-full; Cut detects its keg-only
path after restart. The regular Homebrew formula omits filters
used by captions, stabilization, and managed color.
Perception and STT
Optional local model setup for transcripts, word cuts, scenes, OCR, diarization inputs, and caption workflows.
CLI agents
Use your installed Claude Code, Codex, Grok or Antigravity CLI and sign in through its normal command outside Cut. Keep one current command on your normal PATH. Cut checks the capabilities needed for a request rather than requiring a specific provider version. Leave Model empty to use that CLI's configured default.
Background removal
Standard background removal (RVM) works on CPU and can use CoreML on Mac or CUDA on NVIDIA hardware. Premium subject selection requires NVIDIA/CUDA readiness and acceptance of its non-commercial model licence. A usable Apple Silicon Premium choice is deferred; use Standard on Mac in this release.
Offline work
Basic editing and local renders should remain understandable even when AI models, services, or CLI agents are unavailable.
Workflows
Common Cut tasks.
Import and organize
Create or open a project, import local video, audio or image files, check Media Health, filter the asset list, and add clips to the base timeline at the playhead. Use supported self-contained editing formats; playlists, manifests and embedded network references are rejected.
Base track and overlays
Use normal Insert or drag from Assets or Library for the story timeline. Imported picture and sound stay linked when moved or trimmed. Use Alt-drag or an overlay lane only when the clip should sit on top, then use track headers to reorder, mute, or solo lanes.
Edit and retime
Split, trim, ripple delete, lift delete, snap, change speed, grade clips, and keep edits reversible. Q ripple-trims from the playhead to the selected clip's start; W trims to its end, closing the gap for linked picture and sound. Add Video Track and Add Audio Track are available in the timeline toolbar.
Caption and translate
Install speech tools, generate transcripts, create captions, style them, and translate captions or transcript text.
Edit for Clarity
Preview the recipe before running it. The pass transcribes, finds pauses and retakes, removes fillers conservatively, and tightens pacing without forcing a render.
Assemble an editable cut
Choose Repurpose, Shorts or From script in Assemble, review the proposed source ranges, then choose Add reviewed plan to timeline. The result stays editable and is added as one Undo action. Shorts applies its reviewed crop and transcript captions only when the project's aspect matches. If the timeline or transcript changes, make a fresh plan before applying it.
Sequence Index
Open Find and choose Sequence Index to search clips and markers across every sequence. Filter by kind, track, offline media, gaps, effects, or hidden, locked, and muted tracks; compact badges expose the matching state. Open a row to switch and seek, or copy the currently shown path-light rows as spreadsheet-safe CSV for QC handoff.
Generated media lifecycle
Use registered project assets as references, label variations, compare takes, choose a result, and insert or replace from verified project history. Cancelled placeholders remain available for an explicit retry.
Motion discovery and deferred connection
Settings can discover an existing Motion installation and show its status. Only that read-only discovery is qualified in v0.6.114. The existing Edit in Motion, refresh, tracking and round-trip routes remain unqualified; managed installation and connection work is deferred. Do not treat those routes as a tested editing workflow for this release.
Agent Chat changes
Choose an agent, optionally enter a model supported by that CLI, then attach registered assets or a timeline target and send the request. Leave Model empty to use the CLI default. Inspect Preview and Diff after the edit; Step back stays available only while its guarded revert is safe, and Ask replacement rechecks the saved target.
Record and polish
Choose Raw or Polished and your screen and sound settings once. F9 can then start and stop from Edit or another focused app when the global shortcut is available. Both modes save the original MP4; Polished also adds an editable clip to the current project, or an automatically created recording project. Choose optional export destinations after Stop.
Review and export
Read ops, receipts, QC, scopes, and diffs before rendering previews, final files, or platform-ready exports.
Debug API
Automate and inspect Cut.
Local control surface
Use the local API to inspect project state, dispatch editing verbs, watch events, and connect MCP-capable tools to a running Cut server.
| Surface | Path or command | Purpose |
|---|---|---|
| REST verbs | POST /api/verb/{name} |
Dispatch any verb from the live schema. |
| State | GET /api/state |
Read current project and timeline state. |
| Verb catalog | GET /api/verbs |
Read the machine-readable contract generated from schema/verbs.json. |
| Events | GET /api/events (WebSocket) |
Watch operations, job progress, render completion, receipts, and UI state. |
| Frame inspection | GET /api/frame?at_ms=[&h=][&compose=1] |
Inspect a bounded composed/scrub timeline frame at a specific time (default h=540, maximum 2160; use export.frame for a full-resolution still). |
| Installed agent docs | GET /api/agent and /api/agent-doc/<path> |
Discover the complete skill and craft guides, verb schema, feature reference, and Debug API contract installed with this exact build. |
| MCP | cutd mcp |
Expose every Cut verb as an MCP tool for a running Cut server. |
| Motion render status | motion.job.get and motion.job.list |
Name a blocking Motion render with job_id, then poll it from a second request until pollAfterMs disappears. Cut exposes only jobs owned by the open project. |
Local-only security boundary
The supported default is one personal workstation / one trusted interactive environment. The API has no token: loopback is a whole-machine boundary, so any local process or account able to connect can operate the editor. Packaged builds refuse non-loopback binds; Host and Origin checks mitigate browser cross-origin and DNS rebinding but do not authenticate native callers. A debug build's non-local escape permits that bind and skips those browser checks. It adds no Cut authentication and is not a supported remote mode. Remote use requires an independently authenticated and authorized SSH/VPN/ShellX broker or equivalent transport; without it, remote access is refused.