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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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

1. Use the codex_slides MCP tools when they are exposed in the current session and a structured tool call is convenient.
2. 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.
3. 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:

bashCopy code
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.