
agent-storyboard
Create storyboard projects, generate image and video assets per shot, add voiceover, and see results land in the right row.
- version
- 0.8.0
- GitHub stars
- 400
Install
/plugin install agent-storyboard@agent-storyboardRun it inside Claude Code after adding the marketplace with /plugin marketplace add Yuuhann1999/agent-storyboard.
Contents
Discovered from sourceSkills 2
Manage Storyboard Projects
Use the Agent Storyboard MCP project tools. Never control the browser, never run npm start manually during normal use, and never edit data files directly.
If the current agent session does not expose Storyboard MCP tools such as create_storyboard_project, list_storyboard_projects, or open_storyboard: in Codex, use tool_search to search for agent storyboard and load the deferred tools; in Claude Code, check that the agent-storyboard MCP server is connected (/mcp). Only if they still cannot be found, tell the user to start a new conversation or restart the agent so plugin tools are reloaded. Do not silently fall back to editing local data files directly.
Open the storyboard
If the user asks to open, start, launch, or show Agent Storyboard:
- Call
open_storyboard. - Return the local URL as a clickable link.
- Tell the user to open the link in the agent's side panel or in a browser.
- Do not launch Chrome, shell
open, Computer Use, or Browser automation just to open the page.
The plugin starts the bundled local app automatically. Project data is stored outside the plugin cache by default.
Create a project
- Turn the user's request into a complete shot list before calling the tool.
- Call
create_storyboard_projectonce with the project title, aspect ratio, all shots, and optional absolutedesignPath. - Do not create shots one at a time.
- Return the created project ID and the project URL from the tool result. Tell the user to open that URL or refresh the storyboard if it is already open.
- If any shot uses
remotionorhyperframes, mention that generation requires the corresponding plugin or local toolchain before processing assets.
Each shot should include:
rollType:A-ROLLfor primary presentation or spoken footage;B-ROLLfor supporting visuals.mediaType:imageorvideo.duration: seconds.dialogue: spoken line for the shot.visualPrompt: concrete visual description used for asset generation.generator:manual,image-gen,hyperframes, orremotion.notes: editing, pacing, transition, or production notes.
Choose generator deliberately:
manual: recorded presenter footage, screen recordings, or existing local material.image-gen: a static generated visual.hyperframes: designed motion graphics or interface animation.remotion: programmatic React-based video composition.
Find and inspect
- Use
list_storyboard_projectsfirst when the project ID is unknown. Passquerywhen the user gives a title. - Use
get_storyboard_projectonly when complete shot content is needed. - Do not fetch every full project merely to find one title.
Update
Use one update_storyboard_project call:
titleoraspectRatiofor project metadata.appendShotsfor new shots.shotUpdatesfor specific existing shots.deleteShotIdsfor removed shots.designPathto import or replace DESIGN.md.removeDesign: trueto remove it.
Fetch the complete project first only when shot IDs or existing content are required.
Apply copied visual-arrangement prompts
When a copied prompt contains a target project ID and asks to generate a director-style visual arrangement, treat it as an execution request that must write back to the storyboard page. Do not answer with a Markdown table only.
- Call
get_storyboard_projectwith the provided project ID. - Build the complete shot list internally, preserving the original dialogue and mapping the arrangement into
visualPromptandnotes. - Call
update_storyboard_projectonce to applyshotUpdates,appendShots, and only necessarydeleteShotIds; never delete the project or its media for this workflow. - Do not enqueue image, video, HyperFrames, or Remotion generation during the arrangement step.
- After the write, return a concise summary of the number of shots written, full-check conclusions, unresolved material decisions, and the project URL. Do not repeat the full table in chat.
If no completed aligned voice timeline is provided, do not invent timestamps. Use duration: 0 and record 时长待录音后确定 in notes; when an aligned timeline exists, derive seconds from its exact millisecond phrase boundaries.
Delete
Project deletion permanently removes the project and its local media. Ask for explicit confirmation immediately before calling delete_storyboard_project.
Token discipline
- Create the complete project with one MCP call.
- Prefer project summaries over full project reads.
- Return concise results instead of repeating the full script after it has been written.
Process Agent Storyboard Tasks
Task recovery
While processing a long render, call heartbeat_storyboard_generation_task
at least every 10 minutes. Tasks expire after 30 minutes without a heartbeat.
If the user released a task or its ID changed, stop attempting to complete it;
never attach a late output to a replacement task automatically.
Process the local storyboard queue. The MCP tools start the bundled local app automatically when needed and default to http://127.0.0.1:43218.
If the current agent session does not expose Storyboard MCP tools such as list_storyboard_generation_tasks, claim_storyboard_generation_task, or complete_storyboard_generation_task: in Codex, use tool_search to search for agent storyboard and load the deferred tools; in Claude Code, check that the agent-storyboard MCP server is connected (/mcp). Only if the tools still cannot be found, tell the user to start a new conversation or restart the agent so plugin tools are reloaded.
Mandatory B-roll motion gate
For every B-ROLL shot routed to hyperframes or remotion, plan_broll_motion is mandatory. Do not claim the task, write a composition, download media, render, or complete the task before this gate is confirmed. The MCP server rejects both claim and completion when the confirmed plan is missing.
Reuse-first template policy (mandatory)
Treat the local template roots and the two required repositories as the primary production library. Before designing a new composition, identify a concrete reusable template, component, shot skeleton, GIF/MP4, or other directly usable media candidate from the inspected sources. If a source has no suitable candidate, record that explicit empty result and the reason. Select the closest existing candidate, reuse it directly whenever it fits, and make only the minimum changes needed for the shot's dialogue, visual hierarchy, palette, typography, and duration.
Do not start from a blank composition when an existing candidate can carry the shot's core semantic structure. If no candidate fits, adapt the closest existing skeleton and record the original path plus the mismatch and adaptation boundary. A from-scratch motion system is an exception: use it only after the plan records the local roots and both repositories searched, the concrete mismatch, why adaptation would fail, and the smallest new structure required. The confirmed plan must carry this evidence in selectedTemplate, motionSkeleton, sources, and researchNotes.
Before asking for confirmation, research the shot in this order:
- Read every available local B-roll template under the project's template roots or the active workspace template directory. Record the roots checked, including an explicit empty result.
- Inspect both required reference repositories, even when a local candidate exists:
https://github.com/heygen-com/hyperframes-launchesandhttps://github.com/Vincentwei1021/video-shotcraft. For each repository, record a concrete candidate path or an explicit "no suitable candidate" result with the reason. - Choose the best reusable candidate across the local roots and repositories. Prefer direct reuse; if it needs changes, keep the adaptation minimal and preserve the source skeleton's relationships and phase order.
- When an external reference is useful, inspect public X posts and their attached media. Prefer a directly usable public GIF/MP4/video over a screenshot; use a screenshot only when the media cannot be accessed. Record the source URL and a rights/source note, and never invent an account, post, quote, or asset URL.
Call plan_broll_motion with approval: "proposed" and include the shot's duration, dialogue, audience takeaway, brollType (有素材 / 无素材 / 纯文字), and semanticStructure (对比 / 聚合 / 筛选 / 层级 / 因果 / 替换 / 展开). Name the selected reusable local or repository template/component/media path first; if adapting, name the source skeleton and the exact mismatch; include any direct media sources and only the minimum UI changes: background, anchor color, font, and personalization. Show that proposal to the user and wait for confirmation.
After the user confirms, call the same tool again with approval: "confirmed", researchComplete: true, both required repository URLs in reviewedSources, and complete selectedTemplate, motionSkeleton, and uiChanges. Only then continue to claim and implement the task. If no suitable local or external motion exists, report the gap and ask for a decision rather than silently inventing a new motion system.
Workflow
-
Call
list_storyboard_generation_taskswith statuspending. -
Inspect the generators used by the pending tasks and verify the matching local capabilities before claiming anything:
image-genrequires an image generation capability. If your agent has its own (Codex: the built-inimagegenskill and tool), use it. If it does not (for example Claude Code), use thegenerate_storyboard_imagetool, which generates through the local Codex CLI; checkinspect_storyboard_environmentfirst and confirm the "AI 生图" item is ready.hyperframesrequires the HyperFrames and HyperFrames CLI skills.remotionrequires the Remotion skill and its local rendering toolchain.
If a required capability is unavailable, do not claim affected tasks. Report the exact missing capability and continue with tasks whose generators are available.
-
Probe the local environment with read-only checks before deciding to install anything:
- Check Node.js, npm, and pnpm availability and versions.
- Check whether the task
outputDir, active workspace, or chosen render directory already haspackage.json, a lockfile, andnode_modules. - Check for local CLIs with existing project commands such as
pnpm exec ...,npm run ..., or executable files undernode_modules/.bin. - Check for global CLIs only with non-installing commands such as
command -v,where, or direct--versionafter the command is found. - Check whether Chromium, FFmpeg, or tool-specific render caches already exist when the selected renderer needs them.
Do not use commands that can implicitly download packages as probes. Do not run
npx remotion,pnpm dlx, or package-managerexecforms that will install missing packages merely to test availability. -
Prefer existing render environments. Use local project dependencies first, then compatible global CLIs. Install only when a required tool is missing, incompatible, or no local dependency set exists. Any install must be explicit and must go into the task
outputDiror a dedicated renderer cache, not into the user's unrelated project. -
Process available tasks one at a time.
-
For eligible B-roll tasks, complete the mandatory motion gate above. For all other tasks, continue directly to claiming after capability checks.
-
Before generating, call
claim_storyboard_generation_task. -
If the claimed task has
hasDesign: true, read the complete Markdown file at the exact absolutedesignPathbefore generating anything. Apply it as the project-wide visual system:visualPromptdefines the concrete shot subject and requested content.DESIGN.mddefines shared visual style, color, typography, composition, texture, and motion language.- An explicit shot requirement takes precedence if it conflicts with the general visual system.
-
Route by
generator:image-gen: with your own image generation, use the built-inimagegenskill and tool. Without one, callgenerate_storyboard_imagewith thetaskIdinstead: it claims a pending task, appliesDESIGN.mdand the reference image, keeps the task alive, verifies the file, and completes or fails the task by itself (skip steps 7, 10 and 11 for that task; expect 1 to 6 minutes per image and process tasks one at a time). TreatvisualPromptas the primary prompt and honor the task'saspectRatio. If the task includesreferenceImagePath, use that local image as the visual reference/input for the generation or edit. Copy the final verified image into the active workspace before completing the task.hyperframes: use the HyperFrames and HyperFrames CLI skills. Start from the selected local or repository template/component/media skeleton, reuse it directly or make the smallest documented adaptation, then create the composition with the task'swidth,height, duration, andvisualPrompt. Lint, inspect, render to MP4, and verify the output.remotion: use the Remotion skill. Start from the selected local or repository template/component/media skeleton, reuse it directly or make the smallest documented adaptation, then render an MP4 with the task'swidthandheightmatching the task duration, and verify the output.
-
Technically verify each generated video before completion: the file exists, is readable, has the requested
widthandheight, has a duration close to the task duration, and has a valid video stream/codec. Then visually inspect representative frames to ensure the render is not blank, black, or the wrong composition. -
Call
complete_storyboard_generation_taskwith the exact absolute output path and correct media type. -
If generation or verification fails, call
fail_storyboard_generation_taskwith the concise cause. -
Continue until no processable pending tasks remain.
Output locations
Use the exact absolute outputDir supplied by the task. Keep all generated source code, intermediate files, and final outputs for that task inside this directory. The MCP completion tool copies the final image or video into the storyboard media directory.
Guardrails
- Do not mark a task complete until the exact local file has been visually or technically verified.
- Do not silently switch a requested HyperFrames task to Remotion, or vice versa.
- Do not use external API keys for Image Generation when the built-in image tool is available.
- Do not process
manualgenerator rows. - Do not create a blank composition or invent a new motion system before checking the local templates and both required repositories. If no existing material fits, keep the plan's explicit mismatch evidence with the task output.
- Preserve the requested duration for video tasks.
- Preserve
projectId,aspectRatio,width, andheight; never return an asset to a different project. - Never guess, truncate, or partially read
DESIGN.mdwhenhasDesignis true. - Do not apply a DESIGN.md from the active workspace or another project; only use the task's exact
designPath. - Do not write video project files outside the task's exact
outputDir.
MCP servers 1
Sponsors
Details
- Marketplace
- Yuuhann1999/agent-storyboard
- Source
- plugins/agent-storyboard
- Category
- Productivity