# VideoDraft ADE agent reference VideoDraft ADE is the Mac agent workspace for filmmaking and software development. Work with Claude Code, Codex, Grok Build, OpenCode, or VD Code in local tasks. Vibe Code uses project files, terminals, and Git tools; Vibe Film uses production tools and the native VideoDraft Editor. ## Platform support - VideoDraft ADE and VideoDraft Editor require an Apple silicon Mac on macOS 15 or later, for both Vibe Code and Vibe Film. ## Core model - A project groups related work such as a film, campaign, client, or channel. - A task is a persistent folder where an agent reads and writes files. - The sidebar, some menus, and agent tools still call a task a workspace. They are the same thing. - A project can have many tasks. Use a new task for a separate outcome, or for concurrent work that may touch the same files. - A task can have many chats. - A chat belongs to one agent for its lifetime. Choosing a model from a different agent starts a new chat in the same task. - An editor project is a local `.vdproject` package. One can be linked to a task and shared by its chats. ## Getting started - Sign in to VideoDraft, then connect Claude Code, Codex, Grok Build, or OpenCode from Settings > Providers, or choose managed VD Code. - [Vibe Film setup](https://videodraft.ai/docs/getting-started#film-mode): Select VideoDraft mode and start with a brief, references, or footage. - [Vibe Code setup](https://videodraft.ai/docs/getting-started#code-mode): Select Code mode and open a project, repository, or folder. ## App modes - Vibe Film uses VideoDraft mode for scripts, generated media, editing, and finished videos. - Vibe Code uses Code mode for repositories, branches, diffs, checks, pull requests, and terminals. - Switch from the mode control at the top of the sidebar, or press Cmd + O. - Project and task context menus can show an item in VideoDraft mode, Code mode, or both. - A chat keeps the app mode captured by its first real user message, even if the visible app mode changes later. ## Task rules - Work inside the assigned task unless the user directs another location. - Save scripts, briefs, shot lists, notes, and other documents in the task folder. - Save generated or fetched images, video, and audio under `media/` unless the user directs another location. - Show finished media in chat with a Markdown link to its local path, such as [shot](./media/shot.png), [clip](./media/clip.mp4), or [track](./media/track.mp3). - Do not use SendUserFile or another file-send tool to display media. The Markdown link in message text creates the visible media card. - Inspect images through `media/previews/` when possible. Create a smaller JPEG preview with sips when one is missing. Open the original only for pixel-exact work. - Never add `media/` or another user-content folder to `.gitignore`. Ignored paths disappear from app mentions and change tracking. - Use `.context/` for scratch notes and handoffs. Keep finished work outside `.context/`. - Opened folder projects are edited in place. There is no hidden copy. - Link another task or folder only when the task needs that material. ## Bundled VideoDraft CLI - Use the videodraft skill as the operating manual before calling production tools. - If the skill is not exposed, use the exact bundled executable path supplied by ADE to run `skills show skill`. - For every videodraft shell call in ADE, use the exact app-bundled executable path from the chat instruction. Never substitute PATH, npx, npm, Homebrew, or a global copy. - The default installed path is `/Applications/VideoDraft.app/Contents/Resources/sidecar/vendor/path/videodraft`. The path injected by ADE is the authoritative one. - Inspect the current tool and model catalogs instead of assuming a model or capability is available. - Useful discovery commands, with `` replaced by the injected bundled path: - ` --help` - ` tools list` - ` tools list --lane assets` - ` tools list --lane asset_io` - ` tools list --lane project_data` - ` tools list --lane production` - The CLI can upload local inputs, batch asynchronous jobs, download results, and report cost. ## Outside ADE: MCP connector and standalone CLI - These are for agents and terminals that are NOT running inside VideoDraft ADE. Inside ADE, use the bundled path above instead. - MCP server URL: `https://app.videodraft.ai/api/mcp`, streamable HTTP, protocol version negotiated per client. - Connector name: `VideoDraft`. The in-app connector screens ask for a name as well as a URL. - Auth is OAuth 2.1 with PKCE and dynamic client registration, so every client below needs only the URL. Access lasts 30 days and refreshes automatically. A personal access token from `https://app.videodraft.ai/mcp-keys` is the fallback for hosts that cannot do OAuth. - Claude: Customize > Connectors > Add custom connector, then the name and URL, then authorize in the browser. - Claude Code: `claude mcp add --transport http videodraft https://app.videodraft.ai/api/mcp`, then `/mcp` in a session to sign in. - Codex: `codex mcp add VideoDraft --url https://app.videodraft.ai/api/mcp`, or Settings > MCP servers > Add server under Streamable HTTP. Codex signs in; it does not need a pasted token. - ChatGPT: enable Developer mode under Settings > Security and login, add a connector with that URL, set auth to OAuth. - Cursor: add `{"mcpServers": {"videodraft": {"url": "https://app.videodraft.ai/api/mcp"}}}` to `mcp.json`. - Call `get_tool_catalog` for a lane before choosing tools. Lanes: assets, asset_io, projects, project_data, production, library, account. - Resources, browsable without a tool call: `videodraft://guidance`, `videodraft://schema/project`, `videodraft://projects`, `videodraft://projects/{project_id}`. - State the model and settings and confirm before expensive work. Call `get_credits_balance` only when the user asks or is budgeting. Video, shot-image batches, upscales, and avatar renders are the largest spends. - Project-less generations land in a per-connection AI Studio session; `name_current_ai_studio_session` gives it a useful title. - Rate limit: 300 requests per minute per token. Revoke access at Settings > API Keys, where OAuth grants appear as `OAuth: `. - Standalone CLI: `npm install -g videodraft`, then `videodraft login`. Requires Node 20.18.1+. MIT licensed, published on npm as `videodraft`. - `videodraft skills install` writes the VideoDraft agent skill into Claude Code, Codex, and Cursor. - The connector and the CLI expose the same tools, the same auth, and the same credit balance as VideoDraft Studio and the Mac app. - Both can arrange a hosted project's timeline (clips, order, and durations). Neither cuts a local timeline: frame-accurate cutting, color, captions, mixing, and interchange export are VideoDraft Editor, inside the Mac app. - Public references: https://videodraft.ai/mcp and https://videodraft.ai/cli. ## Workspace MCP inside ADE - Every ADE chat gets a built-in MCP server named `videodraft_workspace`: Claude Code, Codex, Grok Build, OpenCode, and VD Code, in both app modes. There is nothing to install or enable. - It is separate from the MCP connector above. It runs inside ADE and only sees ADE itself. - Use it instead of asking the user to repeat context from another chat or task. The bundled `videodraft-ade` skill explains when to use it. - `ade_whoami`: the current chat, task, and project. - `ade_list_projects`, `ade_list_workspaces` (up to 100 per call), and `list_chats` (up to 100 per call, with a cursor): enumerate projects, tasks, and chats. - `get_workspace_status`: a task's state and its open chats. - `read_chat`: another chat's transcript in pages of turns, with user prompts and assistant prose only, never tool output. 8,000 characters by default and 30,000 at most per call. - `search_transcripts`: find past chats by text. All words must match. Returns up to 20 chats with snippets. - `get_workspace_diff`: what changed in the task. Start with `stat: true`, then request specific files. - `diff_comment`: post review findings inline on the diff. Each comment names a file, a line and optional end line, a side (old or new), and a body. - `get_terminal_output`: recent output from the Run tab or a terminal, 1,000 lines by default. - `computer_use_status`: whether Computer Use is enabled and what setup is missing. - Read in pages and snippets. Never pull whole transcripts. ## Choose the simplest path Use asset generation for a standalone deliverable: - Image - Video clip - Voiceover or dialogue - Music or sound effect - Voice-changed or dubbed audio - Image or video upscale - Media description These are complete deliverables and do not require a VideoDraft project. Use the editor for: - A local `.vdproject` - Timeline assembly and cutting - Existing footage - Layouts, transitions, titles, captions, color, effects, or audio placement - A final local export Use a hosted project only when the user explicitly asks for one. That covers an editable web project, a hosted storyboard or production workflow, or a hosted export. Also use it when the editor is unavailable. Do not silently switch from a local failure to hosted production. ## VideoDraft Editor - Inside ADE on a supported Mac, agents receive editor tools automatically through the `videodraft_editor` MCP server. - The editor starts headlessly, meaning it runs with no window on screen. An Open Editor click is not required for agent editing. - A hidden or closed editor window does not stop headless editing. - To show the UI, use the exact editor executable path supplied by ADE, run `show`, then run `status`. Claim success only when status reports `mode: visible`. - Opening a project headlessly selects the project for tools but does not reveal a window. - Start by listing, opening, or creating the intended project. Never confuse a hosted project ID with a local `.vdproject`. - Read the current timeline revision before editing. - Send project mutations serially and carry forward the fresh revision from each result. - Import cloud-generated or local media, wait until it is ready, then place it on the timeline. - Use timeline and media views to verify content and composition before export. - Editor projects, edits, previews, and exports run locally. - For narration-led edits, cut the voiceover first, then cut the shots to it. - Trim dead air, the quiet stretches with no speech, then cut filler words, then place B-roll against the locked read. - Finishing tools stay live and editable: captions, color, audio, effects, transitions, and multi-angle layouts. Prefer them over regenerating media. - Export H.264, H.265, or ProRes for delivery. - For interchange, XML (XMEML) is preferred for both Premiere Pro and DaVinci Resolve. FCPXML is preferred for Final Cut Pro and also carries titles. - Neither interchange format carries color or effects. XML also omits titles. Deliver a flat render when the look must survive the handoff. Current build limits, so you do not attempt them: - There is no audio denoise. The control and the audio_denoise tool were removed, not disabled. Video noise reduction (texture.denoise) is a separate, working effect. - Speaker identification detects speech but cannot attribute it to a speaker. - Audio analysis refuses sources longer than 30 minutes. - Dead-air removal only cuts speech. Dynamic music you have not transcribed is not reliably protected, because a quiet intro or fade can read as dead air. Transcribe musical sources first. - XMEML flattens a speed ramp to its average rate. FCPXML carries the ramp. - No reverse playback, frame blending, or optical-flow interpolation. ## Agents and parallel work - VideoDraft ADE supports Claude Code, Codex, Grok Build, OpenCode, and managed VD Code. - Connect providers from Settings > Providers. Claude Code and Codex use their local CLI sign-ins or an API key. Grok Build uses Sign in with Grok. OpenCode uses the user's own API key from Google AI Studio, DeepSeek, xAI, OpenRouter, or OpenCode Zen. Managed VD Code uses the signed-in VideoDraft account. - VD Code has a weekly usage limit that is separate from VideoDraft credits. The 7-day window starts with first use, and the full limit returns when it closes. At the limit the chat stops with "Usage limit hit." - The usage pill in the left sidebar footer opens Usage Limits, with a tab for each connected provider. The VideoDraft tab shows Available credits, Monthly credits, VD Code weekly, and Buy credits. - Users can set the model and thinking level per chat. - Plan mode lets the user review an approach before changes. OpenCode chats offer Auto, Plan, and Ask modes. - Messages sent during an active turn can queue for the next turn. A turn is one message plus the agent's full response. - Chats can continue streaming while the user moves to another chat. - The safest concurrency boundary is one active writing agent per task folder. - Use another task when work is unrelated or may overwrite the same files. - Claude can delegate a task to Codex when both agents are connected and the relevant command or setting is available. - Every finished turn offers Copy and Fork. Fork starts a new chat from that point, in a new tab or a new task. Earlier turns also offer Reset to this point, which restores task files to that point and drops later turns, in both app modes. - Failed turns offer Retry. Interrupted turns offer Continue. - Split the center panel with Cmd + \ or by right-clicking a tab and choosing Split right. Move a tab with Move to next pane. Open a chat in its own window with Open in new window or Cmd + Shift + N. A previewed file keeps an italic tab title until you double-click it or choose Keep open. - ADE installs the `videodraft` and `videodraft-ade` skills for every agent. Users can add their own `SKILL.md` folders under a skills folder in `.claude`, `.agents`, `.opencode`, or `.grok`, in the project or the home folder. ## Project settings - Each project can carry `.videodraft/settings.toml` at the project root. Edit it from Settings > Projects. - Layers resolve lowest to highest: `~/.videodraft/settings.toml`, then `/.videodraft/settings.toml` (committed), then `/.videodraft/settings.local.toml` (gitignored). - A project with no settings file behaves exactly as before. Parse errors degrade to an empty layer rather than failing. - Files to copy: ADE copies gitignored files matching the configured globs into each new task. The default glob is `.env*`, and a repo-root `.worktreeinclude` overrides the setting. - ADE skips symlinks, binaries, files over 5 MB, and existing destinations. - Environment variables reach the setup script, the Run tab, and the agent process. They apply when a chat starts, so restart the chat or run /restart after changing them. - Run commands appear in the Run button dropdown in the right panel. - Each task gets its own VIDEODRAFT_PORT so parallel tasks can run servers without colliding. ## Git and pull requests - In a git-backed project, each task gets its own worktree and branch. A worktree is a second checkout of the same repo, so the task has its own copy of the files. - Parallel tasks never touch each other or the main checkout. - A new task branches off the repository default branch. New task from branch starts from any remote branch or open pull request instead. - The chosen base becomes the task target: the diff base and the pull request base. Retarget from the menu next to the branch name in the chat header. - Retargeting is blocked while the agent runs or a pull request is open. - A folder opened in place is edited directly and never gets a worktree. - Review opens a fresh chat scoped to the current diff, using the Review model, and its findings appear inline on the diff. /codex-review and /codex-challenge get an independent Codex read. /security-review checks pending changes. - Users leave their own inline comments by clicking + in the diff gutter on a line or range, typing in "Add a comment for the AI", and choosing Comment. Pending comments attach to the next normal message in that chat, not to slash commands or queued messages. - Pull request actions use the GitHub CLI: Create PR, Create draft PR, Create PR manually, View PR, squash merge, auto-merge, Resolve conflicts. - The Checks section of the git status panel shows CI results. When checks fail, Fix errors sends the failures to the agent. - Status rows show Waiting for PR review, PR changes requested (with Add comments to prompt), and Automated review running. - After a merge, Continue starts a fresh branch in the same task keeping its chats. Archive closes it out. - While a PR is open, the Git panel lists its unresolved review threads. Resolved and outdated threads are filtered out. - Adding those threads to the chat hands the agent the reviewer comments as context. - ADE hides or disables mutating git actions while any chat in the task is streaming. - Git controls appear in Code mode. VideoDraft mode hides them, though worktrees still back each task. ## Remote control - Remote control does not move the chat. The chat keeps running locally with its files, tools, and environment. Remote devices are live windows into it. - History carries over, messages stay in sync both ways, and tool approvals appear on both sides. The Mac must stay running. - Claude chats: run /remote-control, or use Claude Remote Control in the chat header, which offers Enable, Disconnect, and Copy pairing code. - Continue in the Claude mobile app or the browser. Run the command again, or choose Disconnect, to stop. - Remote control requires a claude.ai login on a Pro, Max, Team, or Enterprise plan. API key authentication does not work. - Remote control is available on Claude chats. Codex chats run locally only. ## Computer Use - Computer Use lets a Codex chat operate Mac apps and work in the user's existing browser tabs. Codex chats only. It is off by default. - Turn it on in Settings > Computer use with Enable Computer use. It requires macOS 15 or later and an unlocked Mac. - Under Mac permissions, grant Screen Recording, Accessibility, and Background input, then choose Check permissions. macOS lists the helper as VideoDraft Computer Use. - App access is Auto by default, or Ask. In Ask mode a prompt offers Allow for this task, Always allow, or Decline, and Always allowed apps lists standing approvals. - Keep apps in the background, on by default, lets Codex work without bringing apps to the front. - Tools: open_app, observe, act (click, type, drag, press_key, paste), wait, foreground and release_foreground, list_apps, list_windows, close_app, batch (1 to 12 steps), open_browser, and browser_call. - The live app view offers Stop task, Hide app view, Move to floating window, Show in chat, and Hide for this task. - It cannot control ADE itself, the Codex app, terminal apps (Terminal, iTerm2, kitty, Ghostty, WezTerm, Alacritty, Warp), or System Settings. - A locked Mac stops desktop control with "Unlock the Mac to use desktop apps." It is not available to remote devices. Plan mode and Enterprise data privacy turn it off. - Scheduled runs can use it only with "Allow Computer Use with Codex Auto" turned on, and they cannot ask for new approvals. - VideoDraft Browser Companion works in existing tabs in Chrome, Edge, Brave, Opera, and Vivaldi. Set it up from Settings > Computer use > External browsers: pick the Browser, choose Set up next to Background browser access, load the folder that opens with Load unpacked in the browser's Developer mode, choose Allow this profile to connect and then Copy token in the companion, and paste the token into Connection token and Save. ADE stores the token in Keychain. - Agents can call `computer_use_status` from the workspace tools to check what setup is missing. ## Scheduled tasks - Tasks can run manually on demand, once at a future time, or on a recurring cadence: hourly, daily, weekdays, or weekly. - Scheduled runs use the unattended Auto permission mode and cannot stop to ask for permission. - The prompt should include inputs, expected output, success criteria, and what to do when something is missing. - ADE must be open for exact-time execution. - Due tasks can catch up on the next launch after sleep. - Keep computer awake prevents idle system sleep while VideoDraft is open. The display can still sleep. - Each run creates a chat that the user can inspect from the Scheduled page. ## Main controls - Cmd + K: Command Center - Cmd + /: Keyboard Shortcuts - Cmd + ,: Settings - Cmd + P: Prompt Library - Cmd + N: New task - Cmd + Shift + F: History - Cmd + [ / Cmd + ]: Navigate back or forward - Cmd + Shift + [ / Cmd + Shift + ]: Previous or next tab - Ctrl + Shift + Tab / Ctrl + Tab: Previous or next tab - Cmd + W: Close current tab - Cmd + T: New chat tab - Cmd + Shift + N: Open the current chat in its own window - Cmd + \: Split the center panel into side-by-side tabs - Cmd + Opt + Left / Cmd + Opt + Right: Focus the previous or next pane - Cmd + L: Focus composer - Cmd + D: Start or stop dictation - Cmd + U: Add attachment - Cmd + F: Find in chat - Cmd + O: Toggle Code / VideoDraft mode - Opt + T: Cycle thinking level - Cmd + Opt + T: Toggle light and dark theme Slash commands depend on the current agent, app mode, and chat. Type / in the composer for the authoritative menu. - Most chats: /clear, /plan, /model, /fast, /compact, /restart, /add-dir. - Claude chats: /remote-control, plus the Claude CLI commands /context, /loop, /schedule, /security-review, /review, /init, /usage, /insights. - Claude chats with Codex connected: /ask-codex and /codex-resume. /codex-review and /codex-challenge are git-workflow commands, so they appear in Code mode only. - Codex chats: /goal, with its pause, resume, and clear forms. ## Right panel Top tabs: - Files: the task folder as a tree. Click a file to preview it, including images, video, and 3D models, and double-click to pin it as a tab. - Activity: what the agent is doing right now. - Changes: the diff against the task target. Code mode. - Git: branch, review, and pull request actions. Code mode. - Editor: the linked editor project. VideoDraft mode. Bottom drawer: - Setup: the project setup script. - Run: a long-lived dev server. - Terminal: one or more shell tabs in the task folder, with project environment variables set. Link extra folders with the plus menu in the composer, or with /add-dir. Links belong to the task, are shared by every chat in it, and survive restarts. ## Privacy and permissions - ADE, its background process, the chat history, tasks, terminals, and the editor all run on the Mac. - The selected agent provider receives chat and file content needed for its turns. - Connected Claude Code, Codex, and Grok Build use the user's provider account, and OpenCode uses the user's own API keys. Managed VD Code requests go through VideoDraft's managed service. - VideoDraft generation services receive the inputs needed when a media tool is called. - Dictation streams microphone audio to Deepgram using a short-lived token from the signed-in VideoDraft session. - A signed-in VideoDraft desktop session creates an app-owned CLI credential. It does not overwrite the user's personal videodraft CLI configuration. - File access starts with the current task and expands through attachments and explicitly linked folders. - Scheduled tasks should use narrower scopes than interactive work, because they run unattended. - Notifications are optional and are used for background response and attention alerts. - Microphone permission is optional and requested when dictation starts. - Screen Recording permission is optional and required for browser-preview screenshots and for Computer Use. Restart VideoDraft after granting it. - Accessibility and Background input permissions are optional and required only for Computer Use. - When a VideoDraft workspace manages Enterprise data privacy, it turns off AI chat titles, custom MCP servers, importing custom agent configuration, VD Code, Grok Build, Computer Use, dictation, and telemetry. Workspace MCP stays on. - Available permission modes depend on the selected agent. When an action needs approval, review its request in the chat before allowing or denying it. ## Updates and completion - VideoDraft checks for signed app updates and downloads them in the background. - Use VideoDraft > Check for Updates in the macOS menu bar to check manually. - Updates apply on restart. Restart behavior is available in Settings > General. - Save finished results in the task folder. - Show finished media with local Markdown links. - Put the key outcome and essential information in the final response. - State errors directly and preserve the user's draft or source files when possible.