ChatGPT Developer Guide

What is this about?

ChatGPT is not just a chat window. For developers, it is an ecosystem made of the ChatGPT surface, OpenAI Platform, Apps, Agents, Projects, GPTs, Skills, and Codex. This guide maps the pieces: what they are for, how to use them, when to extend them, and how they work together.

1. The mental model

OpenAI has several layers. The most common mistake is calling everything "ChatGPT". For clean architecture decisions, separate these concepts:

Layer	Purpose	Typical users	Extension model
ChatGPT	Productive chat work: research, writing, analysis, planning, agent use	End users, teams, developers	GPTs, Projects, Apps, Deep Research
OpenAI Platform	APIs, models, tools, tracing, keys, billing, production systems	Developers, product teams	Responses API, Agents SDK, Tools, Evals
Codex	Coding agent for repositories, IDE, terminal, desktop, and cloud	Developers	`AGENTS.md`, Skills, Plugins, MCP, Hooks, Subagents
Apps SDK	Build apps that run directly inside ChatGPT	App developers, SaaS teams	MCP server plus optional UI components
GPTs	Custom ChatGPT experiences without running full app infrastructure	Power users, teams	Instructions, Knowledge, Capabilities, Actions

Rule of thumb: ChatGPT is the work surface, the Platform is the API layer, Codex is the coding agent, Apps are product integrations, and GPTs are configured assistants.

2. Apps in ChatGPT

Apps bring external tools and data into ChatGPT. Earlier "connectors" are now generally surfaced as Apps in the current product line. Some apps only provide search or data access, some render interactive UI in the chat, and others can perform actions in a connected service.

App capability	What it is for	Example
Search	Find content in connected services and use it as context	Files, tickets, messages, CRM data
Deep research	Multi-source research with citations across connected apps	Market analysis across web, Drive, and Slack
Sync	Pre-index content so answers become faster and better	Workspace knowledge, document stores
Write actions	Change something in an external system	Post a comment, create a meeting, update a file
Interactive UI	Render rich UI directly in ChatGPT	Maps, product lists, playlists, forms

Using apps

Open Settings > Apps in ChatGPT or use the App Directory.
Connect the app if it needs OAuth or workspace approval.
Use the app through @AppName, the plus menu, or as a source in Projects and Deep Research.
Check approval cards carefully. Reading is usually less risky than writing, deleting, sharing, or purchasing.

Take permissions seriously

Apps can read external data or trigger actions. Keep app permissions conservative in production workspaces: automatic read access is often acceptable, while write actions usually deserve confirmation in teams.

Building your own apps

Custom ChatGPT apps are built with the Apps SDK. The basic architecture:

Building block	Role
MCP server	Exposes tools ChatGPT may call
Tool schemas	Describe inputs, outputs, and side effects
UI component	Optional interactive view inside the ChatGPT iframe
Auth	Connects users securely to your service
Submission	Makes the app available to a workspace or directory

Conceptual starter flow:

# 1. Create an app project
npm create openai-app@latest my-chatgpt-app

# 2. Run it locally
cd my-chatgpt-app
npm run dev

# 3. Connect it in ChatGPT Developer Mode
# 4. Test tools, verify UI, harden auth and permissions
# 5. Deploy and submit for workspace or directory use

When to use Apps instead of GPTs:

Choose Apps when...	Choose GPTs when...
you are integrating a real product or internal tool	you mainly want to configure behavior and knowledge
external APIs, auth, or write actions are required	you do not want to run infrastructure
UI in the chat matters	text workflows, analysis, or simple actions are enough
admins need rollout and permission controls	individual users or teams need to move quickly

Official sources: Apps in ChatGPT, Apps SDK.

3. Agents

"Agent" means two related but different things in the OpenAI ecosystem:

Layer	What it is	When to use it
ChatGPT agent mode	ChatGPT works longer on a task, uses browser, apps, files, Code Interpreter, and confirms risky steps	Complex online tasks without building your own system
Agents SDK	Developer framework for agentic apps with tools, handoffs, tracing, and guardrails	When you build an agentic product
Codex Agent	Coding agent for software development	When the task is attached to a repo, IDE, or terminal

ChatGPT agent mode

Agent mode is useful when ChatGPT should do more than answer: inspect websites, gather information, analyze files, prepare forms, edit tables, or combine multiple sources. You start it from the tool menu or with /agent.

Good prompt:

Use Agent Mode. Goal: create a comparison table for three CRM tools.
Sources: official pricing pages and our uploaded requirements file.
Deliverable: Markdown table with recommendation, assumptions, and links.
Stop before any action that sends data to external services.

Agent mode is less useful for quick questions, simple writing, or tasks where you need full API control, logs, evals, and product-owned logic.

Agents SDK

The Agents SDK is the path for building agents yourself. You define agents, tools, handoffs, guardrails, and observability. It fits support automation, research pipelines, internal ops agents, data analysis, and multi-step product workflows.

Minimal model:

from agents import Agent, Runner, function_tool

@function_tool
def lookup_customer(customer_id: str) -> str:
    return "Customer data from your system"

agent = Agent(
    name="Support Agent",
    instructions="Answer from company policy and use tools when needed.",
    tools=[lookup_customer],
)

result = Runner.run_sync(agent, "Summarize customer 123 and suggest next steps.")
print(result.final_output)

Decision table:

Task	Best choice
A human wants ChatGPT to complete a complex web task	ChatGPT agent mode
A product needs repeatable agentic logic	Agents SDK
A developer wants to read, edit, test, or review code	Codex
A team wants a ChatGPT experience without a backend	GPT

Official sources: ChatGPT agent, Agents SDK.

4. Projects

Projects are workspaces in ChatGPT. They keep chats, files, links, saved answers, and project instructions together. For developers, Projects are especially useful when context should persist across multiple threads.

Component	Benefit
Project Instructions	Project-level role, style, constraints, and rules
Files	Specs, PDFs, spreadsheets, architecture docs
Project Memory	Context from the project remains available in the project
Shared Projects	A team works in one shared context hub
Apps in Projects	External sources such as Drive or Slack can be used as context

Good project instructions:

You are our technical product partner for the billing project.
Answer concisely, but include clear trade-offs.
Use the uploaded architecture docs as the primary source.
If information is missing, mark assumptions explicitly.
Do not send personal data into external app actions.

When Projects make sense:

Long-running topics: product launch, migration, research, course, docs, recruiting.
Multiple parallel chats that need the same context.
Team work where files and decisions should remain traceable.
Recurring reports or analyses.

When they do not:

One-off questions.
Tasks where you intentionally do not want history or memory.
Confidentiality or compliance cases where the workspace does not allow files, apps, or sharing.

Official source: Projects in ChatGPT.

5. GPTs

GPTs are custom ChatGPT experiences. You configure name, description, instructions, knowledge, capabilities, apps, and actions. They are ideal when you need a reusable assistant experience without building a full app.

GPT building block	What it is for
Instructions	Behavior, role, tone, boundaries, decision rules
Knowledge	Uploaded references the GPT should use
Capabilities	Tools such as web, images, file analysis, or Code Interpreter, depending on plan
Apps	Connected app context or tools
Actions	Custom API calls through an OpenAPI schema
Version history	Test and track changes

You build GPTs on the web in the GPTs area. Mobile apps can use GPTs, but the builder is centered on the web experience.

GPT Actions

Actions connect a GPT to an API. You describe the API with an OpenAPI schema and define auth, parameters, and allowed operations.

Conceptual schema:

openapi: 3.1.0
info:
  title: Tickets API
  version: 1.0.0
paths:
  /tickets/search:
    get:
      operationId: searchTickets
      summary: Search support tickets
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Matching tickets

Use GPTs for:

Team assistants: "Support Policy Helper", "Brand Reviewer", "SQL Mentor".
Knowledge plus a clearly defined working style.
Prototypes before building an app or API integration.
Simple API actions when interactive UI is not needed.

Do not use GPTs for:

Complex product UX inside the chat.
Fine-grained admin rollout through an app directory.
Agentic production systems with tracing, evals, and a deployment pipeline.

Official sources: Creating and editing GPTs, GPT Actions.

6. Skills

Skills are reusable capabilities for agents. The term appears in two important contexts:

Context	Meaning	Typical form
OpenAI Platform Tools Skills	Tool capabilities for API agents	Skill or tool configuration in an agentic workflow
Codex Skills	Reusable working instructions for Codex	Directory with `SKILL.md`, optional scripts, references, assets

Codex Skills are especially concrete: a skill describes when it applies, which steps Codex should follow, and which resources or scripts it may use.

---
name: release-notes
description: Create release notes from git commits and issue context.
---

1. Read the merged commits since the last tag.
2. Group changes by user-facing impact.
3. Mention breaking changes explicitly.
4. Produce Markdown suitable for the changelog.

Skills vs GPTs vs Apps

You need...	Use
A reusable Codex workflow	Codex Skill
A friendly ChatGPT assistant	GPT
Access to external tools, data, or UI in ChatGPT	App
Production-grade agent logic in your product	Agents SDK
Project-wide rules for a repo	`AGENTS.md`

Skills are good for recurring procedures: release, review, migration, docs, security checks, frontend audits, and data imports. If a skill needs external systems, combine it with MCP.

Official sources: Skills in OpenAI API docs, Codex Skills.

7. Codex

Codex is OpenAI's coding agent. It reads repositories, plans changes, edits files, runs commands, reviews diffs, uses tools, and can work locally or in the cloud.

For a concrete Windows/WSL/VS Code setup, see the Codex Setup Guide.

Codex surfaces

Surface	Strength	When to use it
CLI	Terminal-first, fast, scriptable, close to the repo	Local repo work, reviews, automation
IDE Extension	Open files, selection, editor context, local changes	When you are working in the editor
Codex Desktop App	Projects, parallel threads, worktrees, browser, skills, plugins	Larger work, review, planning, app workflow
Codex Cloud/Web	Offloaded tasks in a remote environment	Long tasks, parallel implementations, PR fixes
Windows App	Native Windows, PowerShell, optional WSL2	Windows workflows with sandboxing

CLI basics

# Interactive session in the current repo
codex

# One-off question with repo context
codex "Explain this codebase"

# Non-interactive use for scripts
codex exec "Fix the failing tests and summarize what changed"

# Launch the desktop app from the terminal
codex app

# Resume an earlier session
codex resume --last

In the CLI, context is often more explicit: name paths, attach files, or describe the relevant area. In the IDE, Codex automatically gets more editor context.

IDE Context and Auto Context

In VS Code-compatible editors, Codex can use open files, selected code ranges, and explicitly added files as context. This is the core idea behind "include IDE context": you do not need to paste everything into the prompt; you can work with selections, @file references, and Auto Context.

Practical patterns:

Select a function and use Add to Codex Thread.
Mention files with @example.tsx or @resources.ts.
Use /auto-context when Codex should automatically include current editor signals.
Turn Auto Context off when a task should stay isolated.

Good IDE prompt:

Use the selected component and @src/lib/api.ts as context.
Add loading, empty, and error states.
Follow the existing UI patterns and run the relevant tests afterwards.

Codex layers that work together

Layer	Purpose	Example
Prompt	One-off task and constraints	"Plan only, do not edit"
IDE context	Current editor files and selection	Open React component
`AGENTS.md`	Durable repo rules	Test commands, architecture rules, review focus
`config.toml`	Personal or project configuration	Model, sandbox, MCP, feature flags
Skills	Reusable workflows	Release notes, security review
Plugins	Installable bundles of skills, apps, MCP, assets	Team plugin for Linear plus review skill
MCP	External tools and data	GitHub, Figma, Sentry, docs
Subagents	Specialists for parallel work	Tester, reviewer, implementer
Hooks/Rules	Mechanical boundaries and lifecycle checks	Check before shell command, block sensitive paths

`AGENTS.md`

AGENTS.md is the most important durable repo instruction file. Put information there that Codex should always know:

Setup and test commands.
Code style, architecture boundaries, naming.
Review expectations.
Directory-specific rules.
Things Codex has repeatedly assumed incorrectly.

Example:

# AGENTS.md

## Repository expectations

- Use `yarn build` before finishing MDX documentation changes.
- Keep source docs in English and put German translations under `i18n/de/`.
- Do not edit generated i18n files unless explicitly requested.
- For frontend changes, verify mobile and desktop layouts.

Windows, WSL, and the desktop app

On Windows, Codex can run natively with PowerShell and the Windows sandbox, or inside WSL2. Choose:

Setup	Recommendation
Repo and tools are Windows-native	Native Windows Agent
Repo lives in a Linux toolchain, Node/Python run in Linux	WSL2 Agent
You use VS Code Remote WSL	Start Codex in the WSL environment
You want to share files between Windows and WSL	Set `CODEX_HOME` deliberately, otherwise config/sessions stay separate

WSL2 is useful when your project already lives in Linux. For Windows-native apps, the native agent is often more direct. WSL1 is not a good base for modern Codex Linux sandboxing setups.

Permissions and sandboxing

Codex works with approval and sandbox modes. The safe default is: read, edit, and run local commands in the workspace; ask for network access, external paths, or risky actions. Full Access is useful, but should be limited to trusted repos and clear tasks.

Review and cloud

Use /review when Codex should prioritize risks in diffs. Use Cloud when a task is long-running, should be parallelized, or should leave your local IDE free. Good cloud tasks include a definition of done, branch context, test command, and explicit non-goals.

Official sources: Codex Manual, Codex CLI, Codex IDE, Codex Windows.

8. Search and Deep Research

ChatGPT has several research modes. They are not interchangeable.

Mode	Use case	Result
Standard Chat	General knowledge, quick explanation	Fast answer, not necessarily current
Web search	Current facts, prices, dates, news, source checks	Short answer with web sources
Deep Research	Multi-step research with synthesis and source control	Structured report with citations
Agent mode	Research plus actions	Result plus executed steps

Use Deep Research when:

multiple sources need to be compared,
you need citations or traceable sources,
files, web, and apps should be analyzed together,
the question needs analysis rather than lookup,
you need a longer decision document.

Use regular Web search when:

you only need to know what is current,
one official source is enough,
the answer should stay short,
no deep synthesis is required.

Good Deep Research prompt:

Create a Deep Research report on the best options for EU-compliant CRM.
Sources: official vendor websites, current privacy documents, and our uploaded requirements file.
Compare: data residency, API, role model, integrations, pricing structure qualitatively only.
Deliverable: executive summary, comparison table, risks, recommendation, source links.

Failure modes:

A question that is too broad leads to a shallow report.
The source mix becomes unclear if you do not state which sources are allowed.
Current prices and limits can change, so always check sources.
App data can only be used when the app is connected and authorized.

Official sources: Deep research in ChatGPT, Deep research API guide.

9. OpenAI Platform for developers

The OpenAI Platform is where production work happens: API keys, projects, models, usage, logs, evals, tools, and SDKs.

Area	What it is for
Dashboard	Projects, usage, billing, limits, keys
Projects	API workspaces, key isolation, team structure
Models	Model choice, capabilities, context, cost profile
Responses API	Standard API for multimodal, tool-using interactions
Agents SDK	Agentic workflows with tools, handoffs, and tracing
Tools	Web search, file search, computer use, code interpreter, MCP, Skills
Evals	Measure quality and detect regressions
Tracing/Observability	Understand and debug agent runs

Developer setup

# Set API key locally
export OPENAI_API_KEY="sk-..."

# Install SDK
npm install openai

# Minimal Responses call
node -e "import OpenAI from 'openai'; const client = new OpenAI(); const r = await client.responses.create({ model: 'gpt-5.5', input: 'Say a quick hello.' }); console.log(r.output_text);"

For real projects:

Create one Platform Project per product, environment, or team.
Use separate keys for dev, CI, and production.
Pin models deliberately and watch release notes.
Log inputs/outputs in a privacy-conscious way.
Build evals for core cases before automating agents.
Set rate limits, cost alerts, and fallbacks.
Use tracing for tool calls and agent handoffs.

Which API for what?

Goal	Recommendation
Chat, text, image input, tools, structure	Responses API
Classic legacy chat schema	Chat Completions only when existing code needs it
Agentic app with multiple tools	Agents SDK
Search over your own files	File Search/Retrieval
Current web data	Web Search Tool
Interactive browser/desktop actions	Computer Use, with strict guardrails
ChatGPT extension for users	Apps SDK or GPT Actions

Official source: OpenAI Platform docs.

10. Decision guide

I want to...
|
+-- Organize ChatGPT work around a topic
|   +-- Project
|
+-- Build a reusable chat assistant
|   +-- GPT
|
+-- Connect ChatGPT to my product or internal API
|   +-- Apps SDK or GPT Action
|
+-- Build an agent inside my own software
|   +-- Agents SDK
|
+-- Plan, edit, test, or review code in a repo
|   +-- Codex
|
+-- Make a Codex workflow reusable
|   +-- Skill, later Plugin
|
+-- Quickly check current information
|   +-- Web search
|
+-- Create a sourced report from multiple sources
    +-- Deep Research

11. Practical starting order

As a user: Create a Project for recurring work and write good Project Instructions.
As a power user: Build a GPT for recurring ChatGPT tasks.
As a developer: Use the OpenAI Platform with the Responses API and clearly separated Projects.
As an app builder: Start with the Apps SDK when ChatGPT should use your product directly.
As an agent builder: Use the Agents SDK, evals, and tracing before running agents autonomously in production.
As a software developer: Configure Codex with AGENTS.md, suitable permissions, skills, and MCP.
As a team: Package stable workflows as skills or plugins and document approval rules.

1. The mental model​

2. Apps in ChatGPT​

Using apps​

Building your own apps​

3. Agents​

ChatGPT agent mode​

Agents SDK​

4. Projects​

5. GPTs​

GPT Actions​

6. Skills​

Skills vs GPTs vs Apps​

7. Codex​

Codex surfaces​

CLI basics​

IDE Context and Auto Context​

Codex layers that work together​

AGENTS.md​

Windows, WSL, and the desktop app​

Permissions and sandboxing​

Review and cloud​

8. Search and Deep Research​

9. OpenAI Platform for developers​

Developer setup​

Which API for what?​

10. Decision guide​

11. Practical starting order​

Further reading​