AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

chatgpt-apps

Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--chatgpt-apps at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/window-openai-patterns.md

Window.openai Patterns

Load this reference when a task needs ChatGPT-only widget features, when translating older examples that use an app wrapper, or when a React widget should read host globals safely.

Core Rule

  • Build baseline widget behavior on the MCP Apps bridge: ui/* notifications, tools/call, ui/message, and ui/update-model-context.
  • Use window.openai only when the task specifically benefits from ChatGPT-only runtime conveniences.
  • Treat window.openai as additive. The app should still have a coherent baseline path on the MCP Apps standard when possible.

Canonical window.openai Surface

State And Data

  • window.openai.toolInput: tool arguments supplied by the host
  • window.openai.toolOutput: current structuredContent
  • window.openai.toolResponseMetadata: current _meta payload (widget-only)
  • window.openai.widgetState: persisted widget-local snapshot
  • window.openai.setWidgetState(state): persist widget-local snapshot after meaningful UI changes

Runtime APIs

  • window.openai.callTool(name, args): call another MCP tool from the widget
  • window.openai.sendFollowUpMessage({ prompt, scrollToBottom? }): ask ChatGPT to post a widget-authored follow-up message
  • window.openai.openExternal({ href, redirectUrl? }): open an external URL through ChatGPT's vetted flow
  • window.openai.requestDisplayMode({ mode }): request inline, pip, or fullscreen
  • window.openai.requestModal({ params, template? }): open a host-owned modal
  • window.openai.requestClose(): ask ChatGPT to close the widget
  • window.openai.uploadFile(file, options?): upload a file from the widget
  • window.openai.selectFiles(): open ChatGPT's file library picker and return app-authorized files
  • window.openai.getFileDownloadUrl({ fileId }): resolve a temporary download URL
  • window.openai.notifyIntrinsicHeight(...): report dynamic height changes
  • window.openai.setOpenInAppUrl({ href }): override the fullscreen punch-out target

Context Signals

  • window.openai.theme
  • window.openai.displayMode
  • window.openai.maxHeight
  • window.openai.safeArea
  • window.openai.view
  • window.openai.userAgent
  • window.openai.locale

Mapping From Repo Wrapper Examples

  • app.callServerTool({ name, arguments }): Use window.openai.callTool(name, args) when you intentionally want the ChatGPT compatibility layer. Use tools/call over the bridge when you want the portable MCP Apps path.
  • app.sendMessage(...): Use ui/message for portable bridge messaging. If the task is intentionally ChatGPT-specific, window.openai.sendFollowUpMessage({ prompt }) is the closest supported path.
  • app.updateModelContext(...): Use ui/update-model-context over the bridge. This is part of the standard bridge, not a window.openai feature.
  • app.openLink({ url }): Use window.openai.openExternal({ href: url }) when you intentionally want ChatGPT's external navigation flow.
  • app.requestDisplayMode({ mode }): Use window.openai.requestDisplayMode({ mode }).
  • app.getHostContext(): Read the documented globals directly (theme, displayMode, locale, maxHeight, safeArea, userAgent).
  • app.getHostCapabilities() / app.getHostVersion(): These are wrapper-level convenience APIs. Prefer feature detection (if (window.openai?.requestModal)) and the documented globals instead of teaching these as the primary public surface.

File Patterns

  • Use window.openai.uploadFile(file) when the user is adding a new local file inside the widget.
  • Use window.openai.uploadFile(file, { library: true }) when the upload should also be saved into the user's ChatGPT file library.
  • Use window.openai.selectFiles() when the user should be able to reuse files that are already in their ChatGPT file library instead of uploading again.
  • Use window.openai.getFileDownloadUrl({ fileId }) when the widget needs a temporary URL for previewing a file or forwarding it through a file-param payload.
  • Feature-detect these helpers in the widget (if (window.openai?.selectFiles)) and provide a fallback upload flow when a ChatGPT-only helper is unavailable.

React Helper Extraction

  • The repo's src/use-openai-global.ts is a good baseline for subscribing to host global changes without scattering direct window.openai reads through components.
  • The repo's src/use-widget-state.ts is a good baseline for mirroring React state into window.openai.setWidgetState(...).
  • The repo's src/use-widget-props.ts is a good baseline for reading typed toolOutput with a local fallback.
  • Keep these helpers optional. Do not force a React abstraction when a simple vanilla widget is enough.