Codex Storyboard: a local storyboard workspace driven from Codex

The gap Codex Storyboard fills between a script and a folder of clips

Writing a video script inside a chat window is easy. Keeping the shot list, the per-shot prompts, the aspect ratio and the resulting image and video files in one place is not. Codex Storyboard targets that middle layer. The README describes it as a local storyboard workspace for short video and self-media production, where Codex creates a project with shots, dialogue lines, visual descriptions, A-ROLL / B-ROLL classification, durations, media types and generation methods written into a local shot table. The intended audience is people who already talk to Codex and want the assistant to own the bookkeeping rather than pasting JSON between tools. The README states that ordinary users do not need to understand MCP, local APIs or file paths, which tells you the plugin is meant to hide its own plumbing behind prompts such as "open the storyboard" or "create a storyboard project for me". That is a deliberate product choice: the interface is conversation plus a browser table, not a CLI.

How the plugin, the MCP server and the local API fit together

The architecture is three pieces. The Codex plugin starts a bundled local workspace and exposes Storyboard MCP tools. The README states the plugin does not write project JSON directly and does not use browser automation to force a page open; instead it calls a local HTTP API. That API is documented in the README as a list of routes covering projects, shots, design files, media uploads and a generation task queue. The data flow is: Codex creates or edits a project through MCP, the browser table reads and writes through the same local API, and generation tasks move through claim, complete and fail endpoints. A useful detail for anyone worried about token spend: the README says creation tools return only a project summary by default instead of echoing the whole script back into the tool result. On the storage side, plugin mode keeps everything under ~/.codex-storyboard/, with a projects.json index and per-project folders holding project.json, DESIGN.md, media/ and generation/. The web front end is plain HTML, CSS and JavaScript, and the README states the local server uses only the Node.js standard library with no runtime npm dependencies. That last point is the strongest technical claim in the README, and it is easy to verify by reading package.json, which lists no dependencies field at all.

Installing the Codex plugin and creating a first 9:16 project

The README lists two prerequisites: a Codex build that supports plugins, and Node.js 18 or higher on the machine. Installation goes through the plugin marketplace commands, then you restart Codex or open a new conversation so the plugin and its MCP tools reload. The repository also documents the same two commands for local plugin debugging, with a dot in place of the GitHub path.

codex plugin marketplace add Yuuhann1999/codex-storyboard
codex plugin add codex-storyboard@codex-storyboard

After the restart, ask Codex to open the workspace. According to the README the plugin starts the built-in local workspace and returns a clickable link, which the README shows as http://127.0.0.1:43218. The README also notes the local service prefers port 43218 and binds to 127.0.0.1.

@codex-storyboard 打开 Codex 分镜台。

With the workspace open, the first real task is a project. The README gives this example prompt, which fixes the aspect ratio, the topic, the style and the target platform in one sentence.

@codex-storyboard 创建一个 9:16 的短视频分镜项目，主题是“Codex 侧边栏的 5 种用法”，风格干净、节奏快，适合抖音。

Refresh the workspace page and the project and shot table should appear. The README warns about one failure that will look like a broken install: if the current Codex session does not expose tools such as create_storyboard_project, list_storyboard_projects or open_storyboard, open a new conversation or restart Codex, because an existing session does not necessarily reload tool capabilities after a plugin install. If you want to run the workspace from source instead, the README documents cloning the repository and starting the root project, which serves the same address.

git clone https://github.com/Yuuhann1999/codex-storyboard.git
cd codex-storyboard
npm start

DESIGN.md, the generation queue and what gets written back

Style consistency is handled by a per-project Markdown file. When you import a visual spec, the README says it is stored as <data directory>/projects/<project-id>/DESIGN.md, and it can be viewed, replaced or removed later from the visual spec menu in the top right of the workspace. The split of responsibility is explicit in the README: the shot's visual description and generation prompt decide what the shot shows, while DESIGN.md constrains colour, composition, typography, texture and movement language across the project. Where the two conflict, the README says the current shot's explicit requirement wins. That precedence rule is the right one, but it also means a sloppy shot prompt can quietly override your design system, and nothing in the README suggests the workspace flags those conflicts for you. Generation itself is a queue. You click generate on one shot or use batch generation, then ask Codex to process pending assets. Each shot's generation method is one of manual asset, Image Generation, HyperFrames or Remotion. The README is candid that availability of those three depends on whether the corresponding capability or plugin is enabled in your Codex environment, and HyperFrames and Remotion project and intermediate files land in the project's generation/ directory.

Where Codex Storyboard stops being the right tool

The dependency on Codex is the first boundary. Every project creation and every queue run goes through MCP tools inside a Codex session, so if you want a browser-only storyboard editor that a colleague without Codex can use, this is the wrong shape. The second boundary is collaboration. Local-first storage under ~/.codex-storyboard/ means there is no server-side sharing model described in the README, and the local service binds to 127.0.0.1, so two editors on different machines are not a scenario the documentation addresses. Third, the generation pipeline is only as good as the environment it runs in. If Image Generation, HyperFrames or Remotion are not enabled, the queue can still be filled but the README gives no fallback path, and manual upload is the only route left. Fourth, asset handling has hard limits: the README lists PNG, JPEG, WebP and GIF for images, MP4, WebM and MOV for video, and a 100MB per-file maximum. Finally, there are no retrieved releases for this repository, so there is no published changelog to consult before upgrading; package.json carries version 0.6.7, and the last push was on 2026-09-14.

Codex Storyboard versus a general-purpose storyboard or timeline app

The obvious alternative is a conventional storyboard or video editing application, where you draw or import frames yourself and the assistant is not in the loop. The difference in approach is who holds the project state. A general-purpose storyboard app keeps shots in its own database and expects you to type or paste content into its forms. Codex Storyboard inverts that: Codex writes the project and shot rows through MCP, and the web table is a viewer and editor over the same local files. That is better when the script and the shot breakdown are generated in conversation and you want them persisted without copy-paste. It is worse when the storyboard is the input rather than the output, for example when a director sketches frames first and wants an assistant to annotate them, because the README's prompts all start from a topic and a format rather than from existing artwork. A second, narrower alternative is running the repository directly in development mode with npm start, which the README documents for people modifying the workspace source. That path uses a data/ directory inside the repository instead of ~/.codex-storyboard/, which is convenient for hacking on the front end and a poor default for real projects because the data sits next to the code.

Maintenance, upgrade surface and licence

The repository is not archived, and the last push was on 2026-09-14, one day before this review. That is a single data point about recency, not a promise about cadence, and no releases were retrieved, so version history has to be read from package.json, which currently says 0.6.7. The upgrade surface is small in one sense and awkward in another. There are no runtime npm dependencies to update, which removes a whole class of supply-chain churn, but the plugin is installed through the Codex plugin marketplace and loaded into a running Codex session, so the README's own advice applies on every upgrade: restart Codex or start a new conversation so the MCP tools reload. Your project data is separate from the code and lives under the data directory, which you can move with the CODEX_STORYBOARD_DATA_DIR environment variable. Back that directory up before a version jump, because the documentation does not describe a migration step or a rollback path for older project.json files. The licence is MIT, which permits commercial use and modification; this is a description of the licence text, not legal advice, and if you redistribute the plugin you should keep the LICENSE file and copyright notice intact. One privacy note worth repeating from the README: prompts and input assets sent to third-party generation services may fall under those services' privacy terms, even though the workspace itself stays on 127.0.0.1.

Editorial conclusion

Adopt Codex Storyboard if you already run Codex with plugin support and want shot tables, DESIGN.md style rules and generated assets kept on your own disk under ~/.codex-storyboard/. Skip it if you need a hosted, multi-user review tool, or if your Codex environment has no image or video generation capability, because the queue then has nothing to process. Before committing, verify that a fresh Codex conversation exposes create_storyboard_project, list_storyboard_projects and open_storyboard, and check where CODEX_STORYBOARD_DATA_DIR points on your machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Yuuhann1999/codex-storyboard on GitHub