# Edit a Desktop Project from Your Agent Source: [Edit a Desktop Project from Your Agent]() Documentation index: [llms.txt]() Last updated: 2026-10-24 Keep your conversation in an external agent on the same computer and use ChatCut Desktop’s local tools to edit a selected project. Project selection and supported editing work do not require a project window. This guide covers **ChatCut Desktop 0.7.21 on macOS**; use [ChatCut Desktop](https://chatcut.io/docs/desktop-app) for installation and local MCP connection setup. ## Before you start Connect your agent to ChatCut Desktop’s local `chatcut_desktop` tools, rather than the hosted [Agent Plugin](https://chatcut.io/docs/agent-plugin). If you have just connected it, start a new agent conversation so it can load the tools. Keep the project package and any source media available on this computer, with the file access your agent needs. Closing Desktop does not make every operation offline. Account services, your agent’s provider and hosted AI features can still need network access, sign-in, credits or provider quota. A service that uses reference media may need to upload it. Review the actual action and any confirmation before proceeding. ## 1\. Find the correct project Ask your agent to list projects and show enough information to distinguish the intended local package: Prompt ```text Use ChatCut Desktop's local tools. List projects without changing them. Show the project IDs, names, and any returned local package locations or location errors. I am looking for [project name or known package location]. Do not create or edit a project yet. ``` Replace the bracketed text with your actual project name or known location. The Desktop catalog can include both account projects and packages registered on this machine. Compare the **project ID**, returned package location and expected contents; a matching name alone is insufficient. A local-only Desktop project is a `.chatcutproject` package. It does not appear in the Web editor or a hosted connector’s project list. An account project appearing in the Desktop catalog does not by itself establish that its local package and media are available. If you want a new project, explicitly ask the agent to create one instead of choosing a similar name. `create_project` creates and selects a local package and leaves its window closed by default. Keep the returned project ID for subsequent work. ## 2\. Select it and inspect before editing Give the agent the actual ID from the list and ask it to select that project with `target_project`, then read its project map with `read_project`. Have it inspect the existing timelines and assets relevant to your task. Use their returned identities when choosing where the edit belongs. Targeting a local project selects it for that agent client without opening or switching a Desktop window. Reading the project establishes what is there; selecting it alone does not import footage or create a cut. If the read shows unexpected media or timelines, resolve the project identity before editing. ## 3\. Request one editable result Use an actual project ID and an absolute path to footage you have permission to use. This example requests an import because the recording is not already in the project: Prompt ```text Use the local ChatCut Desktop project [project ID]. Select it without opening a window, then inspect its timelines and assets. Import [absolute path to my recording] and make an editable first cut on a new timeline named [review timeline name]. Remove clear false starts, repeats and long pauses while preserving the meaning, original picture and voice, and natural breathing. Use only this footage. Leave captions, generated media and export until I have reviewed the cut. Report the project and timeline IDs, what changed, and anything still pending. ``` Replace all bracketed values before sending. If the footage is already imported, replace the import instruction with a reference to the actual asset returned by the project read. State a passage or important point that must remain when editing only part of a recording. The agent can use `push_asset` for a readable local file when the task calls for importing it. Importing makes media available to the project; the requested timeline edit is a separate result. Let media processing or transcription finish before judging a speech edit, and read any question or error rather than resubmitting the whole task. ## 4\. Inspect the result and continue Ask the agent to read back the same project and resulting timeline. Check its identity, retained clips, order and duration against the requested edit. A successful tool reply or summary alone does not prove that the saved project contains the intended cut. For a visual review, start ChatCut Desktop and ask the agent to show that same project. `target_project` with `openWindow=true` can show or focus its project window when Desktop is already running; it does not launch a closed app. Inspect the requested timeline in the Viewer and Timeline. For speech, play from the first word to the last with sound on and check meaning, breaths and joins. See [Talking Head Edit](https://chatcut.io/docs/talking-head-edit) for review criteria. Keep revising in the same project using the actual timeline and clip references. For example, ask to restore one clipped breath while leaving the other cuts unchanged. Export only when you want a delivered file; follow [Desktop Local Export](https://chatcut.io/docs/desktop-local-export) and open the resulting file to check it. Closing a window is not a completion or cancellation signal for an edit, import or render. Inspect the operation’s reported state and resulting project or file before assuming it finished. ## If the workflow stops | What you see | What to do | | --- | --- | | Only hosted/Web tools or no Desktop tools | Follow the [local connection setup](https://chatcut.io/docs/desktop-app), then start a new agent conversation. Do not create a Web project to stand in for a missing local one. | | A local project is absent, ambiguous or has a location error | Compare the full project ID and package location. Confirm the package is available on this computer. Keep the original package; report the returned error rather than creating another project with the same name. | | A project was created but its window did not open | Keep the returned ID. Select that existing project instead of repeating project creation. Start Desktop first if you want its window shown. | | Media is missing or an import fails | Check the original file path, access and processing state. For media already in the project, use the relevant [relink recovery](https://chatcut.io/docs/my-assets#repair-missing-or-interrupted-media) instead of importing duplicates. | | The cut is missing or speech is not ready | Read the same project and intended timeline, check pending processing or transcription, and identify the unfinished step. Resume that step with its actual target rather than repeating completed work. | | A tool requires a window, sign-in or another service | Follow that operation’s requirement. Window-free project selection does not mean every tool works with Desktop closed or without the network. | For an unresolved failure, keep the project and original files. Report the project ID, package location, Desktop version, failed step and exact message through **Feedback** or your existing support conversation.