Welcome to the OpenAI Codex Bible

Act as a course creator for non-technical builders.

Turn this topic into a friendly lesson:
[topic]

Make it:
- beginner-safe
- practical
- copy-paste friendly
- focused on building something real
- no more than 5 steps before the learner gets a visible result

Include:
1. Why this matters
2. What to click
3. What to paste
4. What success looks like
5. What to ignore until later

# macOS or Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# Optional alternatives
npm install -g @openai/codex
brew install --cask codex

codex --version
codex login
codex

git --version
node --version
npm --version
codex --version
codex login
codex app .

I am new to coding. Please inspect this project before changing anything.

Tell me:
1. What files and folders matter
2. How to run the project locally
3. What commands are safe to run
4. What you recommend as the first small step

Do not edit files until I approve the plan.

codex doctor

my-project/
  AGENTS.md
  docs/
    MASTERPLAN.md
    DECISIONS.md
    TESTING.md
  src/
  package.json

Inspect this project before changing anything. Read the README, package files, docs folder, and any AGENTS.md files.

Tell me:
1. What this project appears to do
2. How to run it locally
3. How to test it
4. Any risks or missing setup
5. The safest next step for: [describe what I want]

Before coding, make a plan. Inspect the current repo and ask me any questions that would materially change the solution.

Do not edit files yet. I want:
- a short diagnosis
- the proposed files to change
- risks
- tests you will run
- the exact definition of done

Goal: Build [feature].

Context:
- Read [file or doc].
- Follow the current app patterns.

Constraints:
- Keep the change small.
- Do not add new dependencies without explaining why.
- Preserve existing user data and behavior.

Done when:
- The feature works in [screen/workflow].
- Relevant tests or checks pass.
- You summarize what changed and any remaining risk.

This is the bug: [describe what happens].
Expected behavior: [describe what should happen].
Steps to reproduce:
1. [step]
2. [step]
3. [step]

Please reproduce or reason from the code first. Then fix the root cause, add or update a test if practical, run the relevant check, and explain the fix in plain English.

I have a fuzzy project idea. Interview me like a product-minded engineer.

Ask one short batch of questions at a time until you can write:
- the goal
- ideal user
- main workflows
- MVP features
- non-goals
- risks
- first implementation plan

My idea: [describe it casually]

codex --image screenshot.png "Explain what is wrong with this UI and fix the app to match the intended design."

I want to push this existing project to GitHub so another LLM or coding agent can work on it later.

Before pushing, do a safe handoff preparation:
1. Inspect current branch, changed files, untracked files, git status, and remote status.
2. Check for files that should not be pushed: .env, API keys, credentials, large generated files, node_modules, build outputs, cache folders.
3. Make sure the repo has README.md, setup instructions, local run command, test/build commands, required environment variables without secret values, .gitignore, and AGENTS.md or HANDOFF.md.
4. Do not delete, rewrite, or push anything until you show me the files that will be committed and I approve them.
5. If safe, create a clean commit with a clear message.
6. If no GitHub remote exists, tell me the exact steps to create/connect one.
7. After pushing, give me the repo URL, branch name, commit hash, changed files, and what the next agent should know.

git status
git add README.md AGENTS.md docs .gitignore src package.json
git commit -m "Prepare first project handoff"
gh repo create PROJECT_NAME --private --source=. --remote=origin --push
git branch --show-current
git rev-parse --short HEAD

Help me deploy this project to Vercel from GitHub.

First verify:
- the GitHub repo is pushed
- README has local setup
- environment variables are documented
- build command and output directory are known

Then tell me the Vercel import settings:
- framework preset
- install command
- build command
- output directory
- environment variables for preview and production

Do not paste secret values into code.

I want to add payments with Stripe, but keep it beginner-safe.

Use Stripe Checkout Sessions unless there is a strong reason not to.
Explain test mode vs live mode.
List the required environment variables without secret values.
Create the minimal checkout flow and webhook plan.
Add a launch checklist for privacy policy, terms, cookie banner, test cards, and Vercel production environment variables.
Do not use live keys during development.

codex --cd /path/to/project "Summarize this repo"
codex --model gpt-5.5 "Plan the refactor"
codex --sandbox workspace-write --ask-for-approval on-request
codex --image screenshot.png "Fix this visual bug"
codex --search "Look up the current docs and update this integration"

codex
/init

# AGENTS.md

## Project overview
- This project is: [one sentence].
- Main users: [who uses it].

## Commands
- Install: `npm install`
- Run locally: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Working rules
- Inspect existing patterns before editing.
- Keep changes scoped to the request.
- Ask before adding new dependencies or changing architecture.
- Never commit secrets, API keys, or credentials.
- Run the relevant checks before saying work is complete.

## Definition of done
- User-facing behavior works.
- Tests/checks pass or failures are clearly explained.
- The final response summarizes changed files and remaining risks.

Orient me in this repo. Check the current branch, changed files, active instructions, and available test commands.

Then tell me the safest next step for today's goal:
[describe goal]

Create a handoff note for the next session.

Include:
- what changed
- files touched
- commands run and results
- decisions made
- blockers
- exact next steps

If there is a docs/HANDOFF.md or docs/PROJECT_STATE.md file, update it.

Review your own changes like a senior engineer.

Focus on:
- bugs or behavior regressions
- security or privacy issues
- missing tests
- edge cases
- confusing user experience

List findings first with file references. Then fix the high-confidence issues and rerun checks.

codex
/review

codex mcp --help
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp login SERVER_NAME
codex
/mcp

Use the connected docs/tooling instead of guessing.

First inspect which MCP tools or connectors are available.
Then use the smallest relevant source to answer or implement the task.
If the source is missing or stale, tell me before proceeding.

Use parallel subagents for read-only analysis.

Spawn:
1. one agent for security risks
2. one agent for UX/accessibility issues
3. one agent for test gaps

Wait for all three. Return a consolidated list of findings with file references. Do not let subagents edit files.

codex --sandbox workspace-write --ask-for-approval on-request

## Safety rules
- Never print, commit, or paste secrets.
- Ask before deleting files, dropping databases, changing auth, or running migrations.
- Use read-only analysis first for unfamiliar production systems.
- Before deployment, run tests/build and review the diff.
- Prefer targeted fixes over broad rewrites.

In the Codex app:
1. Open Plugins.
2. Browse Curated by OpenAI, Shared with you, or Created by you.
3. Install the plugin.
4. Connect the external app if prompted.
5. Start a new thread and ask Codex to use it.

In the CLI:
codex
/plugins

Use the installed [PLUGIN NAME] plugin if it is available.

First confirm what tools or skills the plugin exposes.
Then use the smallest relevant tool for this task:
[describe outcome]

If authentication or permission is missing, stop and tell me exactly what to connect.

---
name: project-handoff
description: Use when finishing a coding session and creating a concise handoff for the next Codex run.
---

1. Inspect changed files and commands run.
2. Summarize what changed in plain English.
3. List blockers, risks, and exact next steps.
4. Update docs/HANDOFF.md if it exists.
5. Do not claim tests passed unless you ran them.

$skill-creator

I want a new skill for [workflow].
It should trigger when [situations].
It should not trigger when [boundaries].
The output should be [deliverable].
Ask me questions until the skill is clear, then create the SKILL.md.

/goal

Objective: [specific outcome].
Definition of done:
- [measurable result]
- [tests/checks pass]
- [docs or handoff updated]

Constraints:
- Keep changes scoped.
- Ask before destructive actions.
- Report blockers clearly.

Create an automation for this project.

Task: [what to check or do]
Schedule: [daily, weekly, every 30 minutes, cron, etc.]
Scope: [current thread, standalone, or project automation]
Safety: use workspace-write only if edits are needed; otherwise read-only.
Reporting: only notify me when there are actionable findings.

codex exec "summarize the repository structure"
codex exec --json "triage the top risks in this repo" | jq
codex exec --ephemeral "review this folder and suggest next steps"
npm test 2>&1 | codex exec "summarize failing tests and suggest the smallest fix"
codex exec --sandbox workspace-write "update release notes from recent commits"

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/stop_check.py",
            "timeout": 30,
            "statusMessage": "Checking completion rules"
          }
        ]
      }
    ]
  }
}

This is an advanced Codex workflow.

Recommend the right surface before acting:
- normal thread
- goal mode
- subagents
- automation
- hook
- plugin or MCP
- codex exec

Explain why, then proceed only with the safest option that fits the task.

Something is off. Do not guess.

Please inspect:
- current working directory
- current git branch and changed files
- active instructions
- available scripts
- the exact error output

Then explain the likely cause and the smallest safe fix.