🧭 This is the Codex + VS Code series index. The six guides cover installation, task prompts, configuration, verifying code changes, long tasks, and troubleshooting. Follow them in order or jump straight to a problem. Instructions were updated on October 29, 2026.
All Codex articles: this page indexes the VS Code series; every Codex article, including ones outside this series, is on Save Effort · Codex
Start here: the five most useful skills
- Give Codex the right code context so you explain less repeatedly.
- Store project rules in
AGENTS.md. - Have Codex analyze first, edit next, then check the diff and test results.
- Learn when to switch between VS Code, CLI, and cloud tasks.
- Handle long sessions, freezes, permissions, and usage limits.
These matter much more than installation alone. If you maintain projects with Codex, learn this workflow: understand the existing project → control the scope → run tests → inspect the diff. Installing an extension and saying “Improve my website” is not enough.
The six guides
- Getting started with Codex: install, sign in, and choose an interface: wrong extensions, failed sign-ins, confusion about the IDE, CLI, App, and Cloud, Windows setup problems, and what to practice on day one.
- Help Codex understand you: context, prompts, and slash commands: misunderstood requests, repeated explanations, runaway edits, referencing files, sharing screenshots and errors, and choosing useful commands.
- Configure Codex: AGENTS.md, config.toml, Skills, and MCP: recurring project explanations, what to put where, and old settings that no longer work.
- Safer Codex edits: permissions, branches, diffs, tests, and review: preventing broken or unrelated changes, demanding test evidence, choosing permissions, reading diffs, and code review.
- Long Codex tasks: plans, Goals, sessions, parallel work, Cloud, and limits: large or multi-day tasks, confused context, parallel and remote work, model choices, and usage management.
- Codex troubleshooting: stuck messages, freezes, missing history, and login errors: spinning or disappearing messages, frozen panels, missing sessions, sign-in errors,
command not found, and MCP failures.
Read guides 1–5 in order. Keep guide 6 nearby when something goes wrong.
Find the guide for your problem
| Problem | What users see | Read |
|---|---|---|
| 1. Stuck or unsent messages | Spinning, queued, or disappearing messages; several reports on October 1–3, 2026, in #49991 and #50118 | Troubleshooting |
| 2. Frozen extension while VS Code works | Unresponsive panel, blocked extension process, backlogs, and server-overload logs in #22393 | Troubleshooting |
| 3. Missing session history | Old chats missing from the list despite local databases and session files remaining, in #21244 | Troubleshooting |
| 4. Complex edits don’t work first time | Schema changes, migrations, and end-to-end testing need evidence, not a “done” message | Safe edits and long tasks |
| 5. Confused context and requirements | Many files, constraints, and past decisions lead to repeated explanations | Prompts, configuration, and long tasks |
When something goes wrong:
- Frozen extension or disappearing messages: check the version and GitHub issues first. Reloading, starting a session, or rolling back are temporary workarounds for particular versions, not universal fixes. See troubleshooting.
- Missing sessions: don’t immediately delete
.codexor clear caches. Missing history entries do not establish that local data is gone. See session recovery. - Unreliable complex work: split it into stages, run checks at each stage, and require specific pass/fail results. Keep human review for migrations and production changes. See safe edits and long tasks.
- Concern about usage: separate exploration, coding, and verification. Find the relevant files before implementing a task instead of repeatedly scanning a whole project for a vague request. This is a useful habit, not a promise of fixed savings. See usage management.
- For “change this website without breaking other features,” use the template in safe code changes.
Learn with less wasted time
- Complete the setup guide’s read-only task to understand the interface, file context, and editing process.
- Practice a small change with the prompting guide, then record project rules using the configuration guide’s
AGENTS.mdtemplate. - Add configuration and Skills as real tasks require them. Don’t install a pile of plugins first.
- Read a few recurring GitHub issues so you recognize tool failures and don’t blindly rebuild your environment.
Watch videos when you need an interface demonstration
These videos help explain the interface. Use your current version for installation parameters, models, and permissions.
| Video | Creator · length | Views, likes · published | Coverage | Useful timestamps |
|---|---|---|---|---|
| Getting Started with Codex, top recommendation | OpenAI · about 53 minutes | About 291,000 views, 4,900 likes · January 12, 2026 | VS Code extension, CLI, AGENTS.md, configuration, prompts, MCP, and advanced automation | 08:12 AGENTS.md; 14:14 environment; 16:26 prompts; 27:02 IDE tips; 34:59 MCP |
| OpenAI Codex in Your Code Editor | OpenAI · about 6 minutes | About 290,000 views, 4,700 likes · October 17, 2025 | A real repository: understanding code, hover changes, cloud tasks, design options, and reviewing edits | 00:45 read code; 01:20 changes; 02:40 Cloud; 05:30 review |
| OpenAI Codex Tutorial #7 — IDE Extension | Net Ninja · about 7 minutes 36 seconds | About 66,000 views, 399 likes · October 6, 2025 | The VS Code extension, part of an 11-lesson course | Watch it all, then lessons 8–11 as needed for context, MCP, Cloud, and parallel tasks |
Watch in the order 2 → 3 → 1. Get a six-minute overview, follow a practical example, then explore full configuration and advanced features. You can also skip the videos and follow the articles directly.
Documentation and troubleshooting references
Official documentation
| Resource | Coverage | Why read it |
|---|---|---|
| Codex IDE guide | Installation, editor context, inspecting changes, cloud tasks | Start here |
| Official VS Code extension | Installation, sign-in, features | Avoid the wrong extension |
| Configuration guide in Chinese | config.toml, permissions, models, MCP, precedence | Advanced setup |
| Iterating Development Workflows with Codex | AGENTS.md, planning, staged execution, verification | Practical project work |
| Rethinking Skills and Prompts for GPT-6 Astra | Leaner Skills, project rules, and prompts | Avoid overconfiguration |
| Using Goals in Codex | Completion criteria, evidence, limits, stopping conditions | Complex and long tasks |
The last two are especially worth reading.
Check third-party settings before installing them
Some tutorials change model providers, permissions, or custom APIs. Don’t copy old configuration files blindly. Check current official parameters first, especially permissions and third-party model endpoints.
Diagnose from evidence
Keep version numbers, error messages, and reproduction steps. Confirm the issue in your own environment before deciding to reload or roll back.
Real reports on GitHub
Match the issue description, environment, extension version, and developer responses in the official repository. Similar symptoms alone are not enough.
- #49991 and #50118: stuck, queued, or disappearing messages.
- #22393: unresponsive Windows extension and App.
- #21244: local sessions omitted from history.
The early-October 2026 queue failures were version bugs, not simply misuse. See troubleshooting.
When old and new advice disagree
Older videos help with interfaces and basic operations. Use current official documentation for configuration, models, and working practices. Check these settings in particular:
- AGENTS.md length: some 2025 tutorials recommended dozens or hundreds of rules. OpenAI’s September 2026 article recommends reviewing those long lists. Reminders such as “Always run tests” can be removed for GPT-6 Astra. See configuration.
- Web search:
web_search_requestis deprecated. Current configuration usesweb_search, defaulting to"cached". See configuration. - Approvals:
approval_policy = "untrusted"is retired, and managed computers may forbidapproval_policy = "never"throughrequirements.toml. See configuration and safe changes.
A note when following the guides
- Demonstrations may show older interfaces. If buttons or parameters differ, check your local version and its official documentation first.