DemoVexa is a desktop app that reads your code and turns it into finished product demo videos, with a script, voiceover and your real UI animated. No screen recording.
Since you asked what I'd do differently: I'd make project_lookup return a stable caption ID and have caption.patch accept only that ID, never the text. Agents often fix a repeated line, like "Click Save", and a text match can land on the wrong one without any error. The expectedRevision check catches stale plans, but not a correct plan aimed at the wrong object. I'd also let preview_frames return a before and after pair for the same timestamp. A single frame tells the agent the result looks fine, while a pair shows what the edit actually changed. The lease plus one undo step per batch is the part I'd copy straight away. It keeps the human in charge without slowing the agent down.
Thanks — that's a real failure mode, and you're right that expectedRevision doesn't catch a correct plan aimed at the wrong object. Today the write path is already ID-only: project_lookup can filter by text, time, or entityId, but every hit includes a stable id, and caption.patch (also caption.update / caption.remove) requires captionId and never matches on text. The remaining gap is the lookup itself: a repeated line like "Click Save" just comes back as a list, with no uniqueness error, so an agent can still pick the wrong id — I'll file that. I'll also file a same-timestamp before/after pair for preview_frames; right now it only returns current-state PNGs (up to 6 times), and command_preview is a structural dry-run that doesn't render.
DemoVexa is a desktop app that reads your code and turns it into finished product demo videos, with a script, voiceover and your real UI animated. No screen recording.
Good to know the write path is already ID only, that covers the worst case. For the lookup gap, one cheap option is returning the match count plus a bit of the neighbouring caption text with each hit, so an agent can tell two "Click Save" lines apart by context instead of by position. You could also let the agent pass an expected count and fail when the lookup finds more than that. That turns a silent wrong pick into an error it has to resolve before it patches anything. In practice, do agents tend to call project_lookup by text first, or do they usually come in with a timestamp?
Your expected-count idea is close to what I ended up writing in PR #35 (github.com/frankShan001/CutVoke/pu...). project_lookup now returns matchCount and an ambiguous flag after all filters are applied. There's also an opt-in requireUnique that returns AMBIGUOUS_MATCH when more than one item matches, even with limit=1. Returning neighbouring caption text with each hit is a good next step. I haven't done that yet, and I'll add it to issue #28.
On text vs timestamp: CutVoke has no telemetry, so I can't answer from data. Most requests quote the line ("fix the 'Click Save' caption"), so the agent usually searches by text first. The updated Skill tells it to narrow with a time filter when the user gives one, or ask, instead of taking the first hit.
DemoVexa is a desktop app that reads your code and turns it into finished product demo videos, with a script, voiceover and your real UI animated. No screen recording.
Nice, matchCount plus an opt-in requireUnique is a cleaner version of what I had in mind, and keeping it opt-in means existing calls don't change behaviour. Telling the agent to narrow by time or ask, instead of taking the first hit, fits how people actually phrase these requests, since a quoted line is often all they give. One case I'd test: the same caption text on two tracks at the same moment, like a callout and a subtitle both saying "Click Save". Does the time filter separate those, or would it need a track filter as well?
Good case, and the honest answer is no, the time filter won't separate them. Captions in CutVoke are one flat list on the sequence, not per track, so a callout and a subtitle that both say "Click Save" at the same moment both come back from textContains + atSeconds. With PR #35 the agent at least sees matchCount: 2 and ambiguous: true instead of silently patching the first hit. To tell them apart today it can ask for fields like y, fontSize or background (the subtitle usually sits low, the callout higher and styled differently), and then ask the user which one if that's still unclear. I opened your scenario as a good first issue so it gets a test and a line in the agent guidance: github.com/frankShan001/CutVoke/is.... A real track or role field for captions is the bigger fix, and I've left that open for discussion there.
The lease + expectedRevision + edit.batch-as-one-undo-step is the right shape for a stateful editor MCP — it treats the agent as a guest on a project a human still owns. One thing I'd add to the "see pixels" path: let preview_frames also return a short audio snippet or a peak around each cut, because a clean still can hide a click or a dropped syllable. That fits how you already treat captions as objects rather than a burned-in layer. Disclosure: I build Vidmoat, a hosted AI video editor where you (or Claude/Cursor over MCP) edit a real timeline by chat and then render an MP4 — complementary when people want that same inspectable-project idea without running the local engine. Nice that the tool catalog stays lazy and that transcript cuts can be auditioned before they land.
You're right — a clean still can hide a click or a dropped syllable, and preview_frames today doesn't help with that. It only returns rendered PNGs (up to 6 timestamps, captions included). The human editor can already audition a transcript range before transcript.delete, and an agent can dry-run the impact with command_preview, but neither gives the agent a short audio snippet or a peak around the cut; audio.analyze is a whole-file loudness/BPM read, not a cut-local listen. I'll file this so the "see pixels" path can also return sound. And thanks for the note about Vidmoat — local vs hosted does feel complementary, as you said.
I'm the maker of AwesomeVideo, a hosted captioning MCP server, so I've hit some of the same walls from the other side (stateless jobs, long renders). Two things that helped us, in case they map to your export path:
Don't make the agent hold a call open for a whole render. Our tools wait inside the call for up to about 45 seconds, then return a job id with step, progress and pollAfterSeconds. Models poll much more politely when the server tells them when to come back; without that hint they either spin or give up early.
Make retries resumable, not just idempotent. We save transcription in 30-second chunks, so a retry after a timeout only redoes what's missing. For a timeline export, caching rendered segments between cuts that didn't change might give you the same effect, since agents tend to re-export after every small fix.
The lease plus expectedRevision design is nicer than anything we have for a human editing at the same time. Curious whether you've seen agents actually renew the lease during long jobs, or whether they mostly let it lapse.
Thanks — both export notes are useful. Long renders already use export.enqueue (it returns a jobId immediately) and export_job (a non-blocking poll with status plus a progress object: phase, fraction, processed time); the guide tells agents to poll about once a second with a bounded timeout. We don't yet return pollAfterSeconds, and retries are idempotent via commandId but not resumable — we also don't cache unchanged segments between cuts — so I filed those as #31 and #32. On the lease: I don't have telemetry (the editor is local-first and doesn't phone home), so I can't quote a renew-vs-lapse rate. The API supports edit_lock action=renew, TTL is clamped to 5–300 seconds, and nothing auto-renews; our demos usually acquire a two-minute lease and release it without renewing. The guide tells agents to renew before expiry and to drop the lease before a long export; if they lapse, it expires on its own, which is why I'm adding a human take-over control in #26 (draft PR #27 is the first slice, not merged).
The expectedRevision guard paired with transactional batches (edit.batch as one human undo step) is the cleanest way to prevent agent drift.
One operational edge case with lease locks is agent failure. When a model hits a tool error or context limit midway through, a global project lease leaves the UI locked until the TTL expires. Adding an explicit "break lease" button in the human UI, paired with a diff view of any uncommitted fragments, keeps the operator in control.
Scoping leases to individual track IDs rather than the entire project also helps. An agent can spend twenty seconds generating and previewing captions on Track 1 while a human trims background music on Track 2 without lock contention.
Thanks, both points are fair. Today the lease is project-wide and the agent picks a TTL (clamped to 5–300 seconds), so if the agent dies it unlocks on its own, but the human can be stuck read-only for up to a few minutes. There's no break-lease button yet, and there should be. The agent guide tells agents never to steal a lease, but the person at the keyboard should always be able to. Track-scoped leases are a nice idea for exactly the captions-vs-music case. I opened an issue for both: github.com/frankShan001/CutVoke/is...
We're a place where coders share, stay up-to-date and grow their careers.
Since you asked what I'd do differently: I'd make project_lookup return a stable caption ID and have caption.patch accept only that ID, never the text. Agents often fix a repeated line, like "Click Save", and a text match can land on the wrong one without any error. The expectedRevision check catches stale plans, but not a correct plan aimed at the wrong object. I'd also let preview_frames return a before and after pair for the same timestamp. A single frame tells the agent the result looks fine, while a pair shows what the edit actually changed. The lease plus one undo step per batch is the part I'd copy straight away. It keeps the human in charge without slowing the agent down.
Thanks — that's a real failure mode, and you're right that
expectedRevisiondoesn't catch a correct plan aimed at the wrong object. Today the write path is already ID-only:project_lookupcan filter by text, time, orentityId, but every hit includes a stableid, andcaption.patch(alsocaption.update/caption.remove) requirescaptionIdand never matches on text. The remaining gap is the lookup itself: a repeated line like "Click Save" just comes back as a list, with no uniqueness error, so an agent can still pick the wrong id — I'll file that. I'll also file a same-timestamp before/after pair forpreview_frames; right now it only returns current-state PNGs (up to 6 times), andcommand_previewis a structural dry-run that doesn't render.Good to know the write path is already ID only, that covers the worst case. For the lookup gap, one cheap option is returning the match count plus a bit of the neighbouring caption text with each hit, so an agent can tell two "Click Save" lines apart by context instead of by position. You could also let the agent pass an expected count and fail when the lookup finds more than that. That turns a silent wrong pick into an error it has to resolve before it patches anything. In practice, do agents tend to call project_lookup by text first, or do they usually come in with a timestamp?
Your expected-count idea is close to what I ended up writing in PR #35 (github.com/frankShan001/CutVoke/pu...). project_lookup now returns matchCount and an ambiguous flag after all filters are applied. There's also an opt-in requireUnique that returns AMBIGUOUS_MATCH when more than one item matches, even with limit=1. Returning neighbouring caption text with each hit is a good next step. I haven't done that yet, and I'll add it to issue #28.
On text vs timestamp: CutVoke has no telemetry, so I can't answer from data. Most requests quote the line ("fix the 'Click Save' caption"), so the agent usually searches by text first. The updated Skill tells it to narrow with a time filter when the user gives one, or ask, instead of taking the first hit.
Nice, matchCount plus an opt-in requireUnique is a cleaner version of what I had in mind, and keeping it opt-in means existing calls don't change behaviour. Telling the agent to narrow by time or ask, instead of taking the first hit, fits how people actually phrase these requests, since a quoted line is often all they give. One case I'd test: the same caption text on two tracks at the same moment, like a callout and a subtitle both saying "Click Save". Does the time filter separate those, or would it need a track filter as well?
Good case, and the honest answer is no, the time filter won't separate them. Captions in CutVoke are one flat list on the sequence, not per track, so a callout and a subtitle that both say "Click Save" at the same moment both come back from textContains + atSeconds. With PR #35 the agent at least sees matchCount: 2 and ambiguous: true instead of silently patching the first hit. To tell them apart today it can ask for fields like y, fontSize or background (the subtitle usually sits low, the callout higher and styled differently), and then ask the user which one if that's still unclear. I opened your scenario as a good first issue so it gets a test and a line in the agent guidance: github.com/frankShan001/CutVoke/is.... A real track or role field for captions is the bigger fix, and I've left that open for discussion there.
The lease + expectedRevision + edit.batch-as-one-undo-step is the right shape for a stateful editor MCP — it treats the agent as a guest on a project a human still owns. One thing I'd add to the "see pixels" path: let preview_frames also return a short audio snippet or a peak around each cut, because a clean still can hide a click or a dropped syllable. That fits how you already treat captions as objects rather than a burned-in layer. Disclosure: I build Vidmoat, a hosted AI video editor where you (or Claude/Cursor over MCP) edit a real timeline by chat and then render an MP4 — complementary when people want that same inspectable-project idea without running the local engine. Nice that the tool catalog stays lazy and that transcript cuts can be auditioned before they land.
You're right — a clean still can hide a click or a dropped syllable, and
preview_framestoday doesn't help with that. It only returns rendered PNGs (up to 6 timestamps, captions included). The human editor can already audition a transcript range beforetranscript.delete, and an agent can dry-run the impact withcommand_preview, but neither gives the agent a short audio snippet or a peak around the cut;audio.analyzeis a whole-file loudness/BPM read, not a cut-local listen. I'll file this so the "see pixels" path can also return sound. And thanks for the note about Vidmoat — local vs hosted does feel complementary, as you said.I'm the maker of AwesomeVideo, a hosted captioning MCP server, so I've hit some of the same walls from the other side (stateless jobs, long renders). Two things that helped us, in case they map to your export path:
step,progressandpollAfterSeconds. Models poll much more politely when the server tells them when to come back; without that hint they either spin or give up early.The lease plus
expectedRevisiondesign is nicer than anything we have for a human editing at the same time. Curious whether you've seen agents actually renew the lease during long jobs, or whether they mostly let it lapse.Thanks — both export notes are useful. Long renders already use
export.enqueue(it returns ajobIdimmediately) andexport_job(a non-blocking poll withstatusplus aprogressobject:phase, fraction, processed time); the guide tells agents to poll about once a second with a bounded timeout. We don't yet returnpollAfterSeconds, and retries are idempotent viacommandIdbut not resumable — we also don't cache unchanged segments between cuts — so I filed those as #31 and #32. On the lease: I don't have telemetry (the editor is local-first and doesn't phone home), so I can't quote a renew-vs-lapse rate. The API supportsedit_lock action=renew, TTL is clamped to 5–300 seconds, and nothing auto-renews; our demos usually acquire a two-minute lease and release it without renewing. The guide tells agents to renew before expiry and to drop the lease before a long export; if they lapse, it expires on its own, which is why I'm adding a human take-over control in #26 (draft PR #27 is the first slice, not merged).The expectedRevision guard paired with transactional batches (edit.batch as one human undo step) is the cleanest way to prevent agent drift.
One operational edge case with lease locks is agent failure. When a model hits a tool error or context limit midway through, a global project lease leaves the UI locked until the TTL expires. Adding an explicit "break lease" button in the human UI, paired with a diff view of any uncommitted fragments, keeps the operator in control.
Scoping leases to individual track IDs rather than the entire project also helps. An agent can spend twenty seconds generating and previewing captions on Track 1 while a human trims background music on Track 2 without lock contention.
Thanks, both points are fair. Today the lease is project-wide and the agent picks a TTL (clamped to 5–300 seconds), so if the agent dies it unlocks on its own, but the human can be stuck read-only for up to a few minutes. There's no break-lease button yet, and there should be. The agent guide tells agents never to steal a lease, but the person at the keyboard should always be able to. Track-scoped leases are a nice idea for exactly the captions-vs-music case. I opened an issue for both: github.com/frankShan001/CutVoke/is...