Codex Slides

Codex Slides

Run Codex Slides as an interactive product inside Codex. The live Browser

workspace is the primary experience; MCP and the bundled CLI are transports

for opening the workspace and performing deterministic operations, not a reason

to hide the presentation workflow in a long-running Codex turn.

Browser-first default

For every new deck request, unless the user explicitly asks for a headless,

unattended, one-call, or CLI-only run:

• Call open_codex_slides / CLI open without a project id, immediately

navigate the returned URL in Codex's in-editor Browser, and verify that the

Codex Slides home/create screen is visible.

• Keep the Browser open. Enter the user's request in the home composer, attach

or assign source files in the UI, and submit it there. This creates a durable

project before clarification starts. If UI submission is not reliable, use

start_project / CLI start-project only as a deterministic fallback, then

navigate its returned project URL immediately.

• Continue in the live project workspace. Let Codex Slides show and own each

checkpoint: requirements/clarifying questions, research progress, editable

outline confirmation, visual-inspiration or style selection, and rendering.

Answer or manipulate each step in the Browser; when a choice materially

changes the result and the user's prompt does not resolve it, leave that

checkpoint visible and ask the user.

• During research and rendering, keep the project workspace visible so the

user sees progress and can steer. Do not leave Codex showing only a generic

"working" message while a hidden tool completes the whole deck.

• After rendering, inspect the deck in the same Browser workspace. Use its

agent composer, slide controls, mark mode, Play, Design Files, and brand

system for follow-up work. Export only after visual review.

Do not call deep_research, create_outline, rank_inspiration,

render_deck, or create_deck before opening the Browser for a normal deck

request. Do not default to create_deck; it is the explicit unattended fast

path. A user's request such as "make a six-slide deck and show me" still uses

the Browser-first guided flow unless they specifically ask Codex to finish it

in the background without checkpoints.

Choose a transport

• Use the codex_slides MCP tools when they are exposed in the current

session and a structured tool call is convenient.

• Otherwise run scripts/codex-slides.mjs. Pass inputs with --json,

--input-file, or command flags. It installs, builds, and starts the local

app when necessary.

• Do not treat MCP as a prerequisite. Both transports use the same API and

return the same project URLs.

Every Browser-capable response includes a browserHandoff. Follow its exact

URL instead of rebuilding one, because it can focus a slide, panel, version,

mode, checkpoint, conversation, or durable run.

Run this to discover the portable command surface:

node <skill-dir>/scripts/codex-slides.mjs capabilities

Read references/COMMANDS.md when selecting commands,

constructing JSON inputs, or mapping a CLI command to an MCP tool.

Read references/CAPABILITY_MATRIX.md when

auditing a newly added product feature or changing the Browser/CLI/MCP contract.

Build a deck

• Discover workflow presets with scenarios / list_scenarios. A scenario owns

its default page count, aspect, research behavior, model instruction, and

required/optional source slots. Pass its scenarioId to onboard,

research, create, or outline; do not re-create the scenario prompt by

hand.

• Upload slot files with upload-material / upload_material, then pass both

materialIds and materialContexts (id, name, role). Required slots

must be satisfied before creation. Keep content sources, datasets, brand

assets, templates, and visual references in their declared roles.

• Use the Browser-first guided flow above by default. The Browser UI drives the

staged clarify -> outline -> inspire -> deck state and persists the project

before expensive work starts.

• Search the shared community style library with templates / list_templates

(query and communityGroup), then use inspiration / rank_inspiration

when the topic and outline should semantically rank those directions. A chosen

community style is both prompt context and the first visual reference image.

• Use start-project / start_project only when Codex needs a deterministic

fallback to create the same durable project shell before returning to the UI.

• Use create / create_deck only when the user explicitly requests an

unattended one-call result or the current Codex surface has no Browser.

• The lower-level onboard, research, outline, revise-outline,

inspiration, and render operations are for CLI automation, recovery, and

deterministic mutations. Keep the corresponding Browser project open when

using them interactively.

• For navigation-independent Deck Agent, outline, or render work, use

start_project_run / CLI run-start. Retain its runId; use

get_project_run, wait_project_run, or cancel_project_run (CLI

run-status, run-wait, run-cancel) after navigation or reconnect.

• Preserve the Markdown research brief and its source links. Do not call a

brief source-backed when it contains no source links.

• Upload logos, screenshots, PDFs, or other references with upload-material

before creation, editing, or restyling, then pass the returned material ids.

Operate Design Files

• Use design-files / list_design_files to inspect the generated and uploaded

project file inventory. Use read-design-file / read_design_file for text

and the returned Browser deep link for visual or binary files.

• In the Browser, every selected Design File exposes its absolute local path for

copying and a direct download action. CLI/MCP file-list responses include the

same absolutePath and a downloadUrl for automation.

• Use write-design-file / write_design_file only when the user asked to

replace an existing editable file. Use upload-design-file /

upload_design_file to add a local file to the project workspace.

• When an outline or deck edit should use project files as evidence, pass their

returned paths as designFilePaths to revise-outline / revise_outline or

edit / edit_deck. This is the Codex equivalent of selecting a Design File

with @ in the Browser composer.

Reuse project templates

• Use project-templates, action list, or list_project_templates before

creating with a reusable project template. Pass the returned id as

projectTemplateId; do not substitute a built-in template id.

• Use project-templates, action save, or save_project_as_template only when

the user wants to preserve an existing project's visual system. The snapshot

includes its format, base template/style, brand system, brand assets, and up

to six visual references, but not the source project's deck content.

• Deleting a saved template does not mutate projects already created from it,

because assets and brand rules are copied into each new project.

Maintain the brand design system

• Call get-brand-system / get_brand_design_system before changing an

existing project's always-on rules. It returns normalized brand identity,

style, colors, typography, effects, spacing, radii, and brand assets.

• Stage new logos or product images with upload-material, then merge a partial

update with set-brand-system / update_brand_design_system. Brand updates

preserve untouched sections. Redrawing existing slides is explicit; default

to saving without redraw unless the user requested application to the current

deck.

• A brand design system is project-wide context for outline generation, slide

generation, chat planning, and later edits. Do not replace it with a one-off

free-text style when the project already has one.

Edit an existing deck

• Inspect with list and get before changing an unknown project.
• Use edit for natural-language add/rewrite/redraw/optimize requests.
• Use slide for deterministic add, duplicate, move, delete, or transition changes.
• Use regenerate for one slide and restyle for the whole deck.
• Use upload-slide for a finished local PNG.
• Use mark-edit when the user supplies an annotated PNG and wants a clean

regenerated slide.

• Use speaker-notes / get_speaker_notes to inspect the talk track,

action:set / update_speaker_notes to write or clear exact notes, and

action:generate / generate_speaker_notes to ask the project's selected

agent for one slide or a coherent full-deck talk track. Notes stay off-canvas,

appear in presenter mode, and export as native PowerPoint speaker notes.

• In the Browser, use the project header's Version entry to inspect immutable

deck snapshots and their originating prompts. Each version owns its slide

images, transitions, and notes, so preview, Play, and PDF/PPTX export use that

exact snapshot. Restoring never overwrites history; it creates a new current

version linked to the selected source version. Every AI command or manual

action that changes a rendered deck must create a version; one multi-step AI

command may update one grouped version. Conversation-only turns, navigation,

and saves whose deck content is unchanged do not create empty versions.

Keep durable edits scoped to the project the user named. If no project was

named and multiple projects exist, inspect the recent list before choosing.

Route to focused workflow skills

• Use the codex-slides-structured-intake sibling for ambiguous or

scenario-led new-deck requirements.

• Use the codex-slides-verification sibling after creation, rendering,

editing, restyling, version restore, speaker-note changes, or export.

• Use the codex-slides-known-errors sibling when the runtime, MCP, durable

run, Browser handoff, project resume, render, Design Files, or export fails.

Open and verify in Codex Browser

Open the Browser before creating a new deck and keep it open throughout the

workflow. After any programmatic mutation, navigate or reload the project URL

and inspect the visible result. Do not stop after printing the URL when the

Browser capability is available.

Preserve exact handoff query parameters: slide, panel, version, mode,

checkpoint, conversation, and run. Presenter mode intentionally leaves

one visible user click because browsers require a gesture to open its second

window.

Use Browser view scenarios for the workflow catalog, design-files for the

file workspace, and brand-system for the visual-system editor. Use the normal

workspace for Play from current/beginning, dual-window presenter mode, speaker

notes editing or AI generation, slide navigation, direct on-canvas marking, and

layout inspection. If the current Codex surface has no in-app Browser session, return

the local URL and state that limitation instead of claiming it opened.

Export only after review

Use export / export_deck with pdf or pptx after the requested visual

result is ready. Return the download URL and keep the project preview URL

available for follow-up edits.

Runtime

Use Node.js 20 or newer. Override the default app URL with

CODEX_SLIDES_URL; override the source checkout with CODEX_SLIDES_HOME.