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:

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.