In-Depth Guide: Mastering Codex from Beginner to Expert

The first time you open Codex, the real stumbling block is understanding what all these areas control: the difference between Projects and Threads, whether to choose Local, Worktree, or Cloud, whether you need to enable a Plan, where to set permissions, and why Plugins, Skills, and MCP all exist at once.

This tutorial starts with these fundamental questions. We won’t jump straight into creating a project or walk you through a complex example step-by-step. First, let’s get familiar with the interface, buttons, workspaces, and common capabilities. Then, we’ll assess which extended features are worth integrating.

After reading this, you should be able to independently open the correct directory, create a thread, control permissions, review changes, and know when to use a Plan, Skill, Plugin, MCP, Automation, or /goal.

I. First, Understand What Codex Actually Is

Codex is a functional Agent. While a typical chatbot primarily provides text responses, Codex can also read files, modify code and documents, run commands, view Git changes, open web pages, operate applications, and call external tools that are connected.

Therefore, the best tasks to give Codex are ones with materials, boundaries, and a deliverable outcome. Its fundamental loop can be broken down into four steps:

Prompt → Plan → Execute → Verify

A Prompt is your task description. The Plan is how it intends to proceed. Execute involves the actual file I/O and command running. Verify is checking the result. This last step is crucial. When Codex says “done,” it only means it has finished the current execution; it does not automatically prove that the files are correct, the page is functional, or that tests have passed.

Codex has five main entry points.

Beginners don’t need to learn all five simultaneously. If you’ve opened the Desktop App, start by mastering the App. If you’re used to the terminal, supplement with the CLI later. The Cloud, IDE, and Chrome Extension serve specific scenarios—it’s not a case of “the more, the more professional.”

II. Navigating the Codex App Interface, Left to Right

The main body of the Codex App can be divided into three sections: the left for managing Projects and Threads, the middle for handling the conversation and execution, and the right for inspecting file changes. Different function panels will expand around these three areas, but the core logic remains the same.

Left Side: Projects and Threads

Projects correspond to a working directory. When you add a website repository, a document directory, or a tool project, you’re essentially telling Codex: “These files belong to one long-term effort.” The Project determines where it reads materials from by default and often dictates where the sandbox is allowed to write.

Threads (also called Chats) are independent conversations within a Project. A single Thread should ideally handle one clear outcome, such as “check this article’s structure,” “fix the login page error,” or “organize yesterday’s commit history.” Projects can be long-lived, but Threads should have an endpoint.

Common actions on the left include:

• Adding or switching Projects;
• Creating a new Thread within the current Project;
• Opening a previous Thread to continue working;
• Viewing Threads that are running, awaiting approval, or finished;
• Popping out a Thread into a separate window for easy side-by-side viewing with a browser or editor.

If an old Thread has accumulated too much irrelevant context and the new requirement is completely different, starting a new Thread is usually cleaner. If you’re just making modifications to the same result, stay within the original Thread—don’t start a new conversation just for the sake of “neatness.”

Middle: The Conversation Area and Input Box

The middle area displays Codex’s replies, plans, commands, tool calls, approval requests, and final summaries. The input box at the bottom is not just a chat box; it’s also the task console.

Common functions around the input box include:

• Send: Submit the current request.
• Stop: Interrupt the currently executing task.
• Model: Select the model to process the current task.
• Permissions: Decide between Read-only, Workspace-write, or higher permissions.
• Attachments: Add files or images as context.
• Voice Input: Hold Ctrl+M to speak, release to convert to text.
• Work Mode: Choose where the task runs: Local, Worktree, or Cloud.

You don’t need to wait for a task to fully complete before speaking again. If you notice it’s going off track, you can directly add instructions like: “Only check, do not modify,” “Don’t install dependencies,” or “Pause at the planning stage.” Correcting course early saves time.

Right Side: Diff and File Changes

The Diff panel on the right is for reviewing exactly what Codex has changed. Additions are typically shown in green, deletions in red. You can view changes by file, or focus on changes from a specific turn or the entire branch.

The value of the Diff panel isn’t just “a quick look.” It also serves as a review tool:

• View all uncommitted changes.
• Add inline comments next to specific lines of code.
• Stage or revert changes by file or hunk.
• Perform commits, pushes, or create a Pull Request from within the App.

If there’s an issue with a specific line, leaving a comment directly on that line is much more precise than describing “that function above” in the input box. After writing the comment, you can send a follow-up: “Process the inline comments I just made, don’t expand modifications to other parts.”

III. Choosing a Workspace: What Codex Can See

The workspace is the directory where Codex is currently working. Choosing the wrong directory is the most common reason for “file not found,” “modified the wrong place,” or “read too much irrelevant material.”

You can use a simple criterion when choosing: Can all the files needed for this task be concentrated in one minimal directory? If yes, open only that directory. Don’t hand over your entire desktop, personal home directory, or a bunch of unrelated projects to Codex just to save one switch.

Here are some common scenarios and how to choose:

• Modifying a single standalone project: Open the project’s root directory.
• A repository with multiple unrelated applications: Add each as a separate Codex Project.
• Frontend and backend in adjacent directories: Start with the primary directory, and add the other as an extra directory permission if needed.
• You only want to analyze, not modify: Still open the correct directory, but set permissions to Read-only.
• The task must run in a remote environment: Choose Cloud, rather than expanding local permissions.

In the CLI, you can specify the working directory with --cd and add extra writable directories with --add-dir:

codex --cd ~/projects/frontend --add-dir ../backend

This is clearer than giving your entire computer write permissions. The smaller the boundary, the smaller the impact when mistakes happen.

IV. When Creating a Thread: Local vs. Worktree vs. Cloud

One of the most important choices when creating a new Thread is where it will work.

Local: Modifying Your Current Directory Directly

Local works within your selected Project directory. Changes appear immediately in your local files, making it suitable for most daily tasks: editing documents, fixing a bug, running tests, organizing directories, or reviewing project structure.

Its advantage is directness; its disadvantage is equally direct: you and Codex might interfere with each other if modifying the same file simultaneously. Starting a single task with Local is the simplest approach.

Worktree: An Isolated Copy for the Task

Worktree leverages Git’s worktree functionality to create an isolated working directory for the task. The Agent makes changes inside it, and your active local directory remains unaffected.

It’s suitable for two situations: having multiple tasks modify the same repository simultaneously, or letting Codex try a change without touching your current branch. After the task is complete, you can create a branch, commit, and open a PR within the Worktree, or use Handoff to move the result back to Local.

Worktree isn’t necessary for every task. If you’re just modifying a small file and only one Agent is working, Local is quicker. Use Worktree when you need isolation and parallel work.

Cloud: Sending the Task to the Cloud

Cloud clones the repository and executes in an isolated remote environment. It’s ideal for well-bounded tasks that can wait asynchronously, such as code review, fixing a specific issue, bulk refactoring, and running tests.

The value of Cloud is that you don’t need to monitor your local machine. After the task finishes, review the Diff and decide whether to merge. For work requiring frequent discussion, dependence on local files, or local applications, Local or Worktree is usually smoother.

V. How to Set a Plan—and When Not To

A Plan is the roadmap before execution. For complex tasks, it helps you spot issues like oversized scope, illogical ordering, or installing unnecessary dependencies ahead of time. For simple tasks, a Plan might just be an extra formality.

In the CLI, you can type:

/plan

You can also make the requirement clear in the same line:

/plan First check the current directory and related files, only provide a modification plan, do not write files

In the App, you can also use natural language:

First, do not modify anything. Please confirm you understand the goal, the files you need to check, and the steps you plan to take. Wait for my confirmation before proceeding.

A Plan is suitable for these situations: the task spans multiple files, modifications are not easily reversible, you need to investigate the root cause first, or you are still comparing implementation approaches. Changing a title, locating an error message, or executing a single determined command does not require forcing a five-step plan first.

A useful Plan should at least answer four questions: What is the real problem to solve, which materials will be examined, which parts will be modified, and how will completion be verified? Templates like “analyze requirements, start implementation, test results, summarize” are low on information; you can ask it to rewrite.

Here’s a more important principle: when receiving a task, first judge the real problem and the shortest reliable path. If it can be done directly, don’t add extra process. If existing results can be reused, don’t start from scratch. If a local modification suffices, don’t rebuild everything. If one command will solve it, don’t write a script. If one script works, don’t create a project. The role of a Plan is to help choose a method, not to add ceremony to a simple problem.

VI. Choosing Permissions and Understanding Approval Popups

Codex can read/write files and run commands; permissions cannot be ambiguous. Common sandboxes can be thought of as three tiers.

For most users, Workspace-write is sufficient for most work. Use Read-only when only analysis is needed. Full access should not be enabled just to avoid a few clicks, and it’s unsuitable for unattended scheduled tasks.

When you see an approval request, check four things first: what command it plans to run, in which directory it will run, whether it requires network access, and why this step is necessary for the current goal. Installing dependencies, uploading files, deleting data, modifying account settings, publishing externally, and accessing credentials are all worth pausing to confirm.

You can use /permissions to view and adjust the current security mode. In the CLI, you can also specify it at startup:

codex --sandbox read-only
codex --full-auto

--full-auto is for low-friction execution within the workspace; it does not mean the entire machine is open. --yolo bypasses approvals and the sandbox, making it unsuitable as a daily default.

VII. A Few Basic Yet Easily Overlooked Tools

Integrated Terminal

Every App task has its own terminal, accessible with Cmd+J on macOS. The terminal directory follows the task: a Local task opens the local project, a Worktree task opens the corresponding isolated directory.

The terminal can run tests, start development servers, check git status, and also inspect Codex’s modifications. A more convenient point is that Codex can read the terminal’s current output. When you see an error, you can directly say “Check the error in the terminal” without copying the entire block.

In-App Browser

The built-in browser is suitable for opening local pages and checking the interface. You can leave positional comments directly on page elements, like “Make the font size smaller here” or “Align this button with the input box above.” This feedback is more precise than plain text descriptions.

The built-in browser does not reuse your logged-in Chrome sessions. For operations on Gmail, Salesforce, LinkedIn, or internal systems, use the Chrome Extension.

Computer Use

Computer Use allows Codex to operate desktop applications, including clicking, typing, dragging, reading the screen, and using keyboard shortcuts. It’s suitable for legacy tools without APIs, bulk data entry, file organization, and cross-application workflows.

The fact that it can operate doesn’t mean everything should be automated. Tasks involving payments, publishing, deletion, account permissions, and external communications should still leave the final confirmation to a human.

Image Input and Generation

Images can be dragged directly into the input box as context, or appended when starting a CLI session:

codex -i screenshot.png "Check why this page is misaligned"

Image generation is suitable for creating interface assets, concept diagrams, and documentation illustrations. It’s an optional capability, not a required step for every task.

Memory

Memory is used to retain your repeatedly expressed preferences and corrections. For example, which testing framework a project consistently uses, what format commit messages should follow, or where certain files should be placed. It’s ideal for long-term, repetitive collaboration.

Important rules should still be written into AGENTS.md. Memory is more like gradually accumulated implicit preferences, while AGENTS.md is explicit, visible, and auditable project rules.

VIII. Most Common CLI Commands and Keystrokes

The CLI is not mandatory, but it exposes Codex’s capabilities most directly. After installation, enter codex in your project directory to launch the full-screen TUI.

The three most commonly used subcommands are:

codex                 # Launch the interactive interface
codex exec "task"     # Execute a task non-interactively
codex resume --last   # Resume the most recent session

Once in the TUI, type / to view special commands.

The input box also has several practical operations:

• Type @ to search and reference workspace files.
• Type ! followed by a command to run a Shell command directly.
• While the Agent is running, press Enter to append instructions for the current turn.
• While the Agent is running, press Tab to queue a subsequent request.
• In an empty input box, press Esc twice consecutively to go back to the previous message and continue editing.
• Ctrl+L only clears the screen, not the context.
• /clear is what starts a new conversation context.

You don’t need to memorize all commands. First, remember /plan, /review, /diff, /permissions, and /status; look up the rest as needed.

IX. AGENTS.md: Writing Long-Term Rules for Codex

AGENTS.md is a rules file that Codex reads when entering a Project. It’s suitable for recording information that doesn’t disappear after a single task ends, such as build commands, directory structure, code standards, acceptance criteria, and forbidden actions.

You can start with /init to generate a draft, then remove unnecessary content. A practical, simplified version for real work might look like this:

# Project Rules

- When receiving a task, first judge the real problem and the shortest reliable path.
- Prioritize reusing existing files; modify locally instead of rewriting an entire system.
- Check related files before modifying; don't guess the directory structure.
- Write only within the current workspace; do not install unrelated dependencies.
- After completion, run existing checks and explain which parts were verified and which were not.

Rules should come from real problems, not be written as a dozens-of-pages “corporate constitution” at once. Add a specific rule only when Codex repeatedly makes the same mistake on the same issue. Short and precise is easier to follow than long and comprehensive.

X. Skills, Plugins, MCP: What’s the Difference?

These three concepts are often conflated. The simplest distinction is:

• Skill teaches Codex how to do a type of task.
• Plugin bundles a group of Skills, MCP servers, and connectors for distribution.
• MCP lets Codex connect to external tools and data.

Skills: Reusable Methods of Doing Things

A Skill is essentially a directory. The core file is named SKILL.md. It contains a name, trigger description, and specific steps, and can also include scripts, templates, and reference materials.

A Skill can be invoked in two ways. Explicit invocation is writing $skill-name in the prompt. Implicit invocation is when Codex automatically determines a Skill based on its description. For Skills involving destructive actions, it’s best to disable implicit triggers and only allow manual invocation.

Common Skills can be categorized by use:

• Documents and Content: Long-form writing, removing template phrasing, PDF or table processing.
• Development Workflows: Code review, releases, issue handling, creating PRs.
• Visual and Media: Generating images, processing videos, creating presentations.
• Team Rules: Fixed testing, deployment, and acceptance methods for a specific repository.
• Research and Analysis: Retrieving information, organizing data, outputting reports in a fixed format.

You can use $skill-creator to build a Skill. Personal, universal Skills go in the user-level directory; team-shared Skills go in the repository’s .agents/skills/ directory. More Skills aren’t necessarily better; only embed a process as a Skill if a certain type of work genuinely recurs frequently.

Plugins: Installing a Complete Set of Capabilities from an App Store

The Plugins page is the plugin entry point. Open Plugins in the App or enter /plugins in the CLI to browse and install. A single plugin may contain multiple Skills, MCP Servers, and App Connectors, and can be used across workspaces after installation.

Representative plugins listed in the “Orange Book” include:

• Atlassian Rovo: Connects Jira, Confluence, Bitbucket.
• GitLab Issues: Handles issues within GitLab.
• CircleCI, Render: Views builds and deployments.
• CodeRabbit: Assists with code review.
• Microsoft Suite: Connects Word, Excel, Outlook, Teams.
• Connectors for GitHub, Slack, Google Drive, etc.: Bring external work content into tasks.

Before installing, ask yourself: Does this task repeatedly require data or actions from this system? A website you’ll use only once may not be worth a plugin; if a native function can accomplish the task, there’s no need to add another layer for the sake of the “ecosystem.”

MCP: Connecting Codex to External Tools

MCP can be thought of as a unified interface. Once an external service implements MCP, Codex can use the queries and operations it provides as tools.

Common MCP servers include:

• OpenAI Docs MCP: Queries OpenAI documentation.
• Context7: Reads documentation for common development libraries.
• Figma MCP: Reads design files.
• Playwright MCP, Chrome DevTools MCP: Controls and inspects web pages.
• Sentry MCP: Reads production errors.
• GitHub MCP: Handles PRs and Issues.

In the CLI, you can add with codex mcp add, list with codex mcp list, and check connection status after entering a session with /mcp. MCP can enable real external operations; configure it with attention to authentication, tool whitelists, and permission scopes.

XI. Setting Up Automations (Scheduled Tasks)

Automation is the scheduled task system within the Codex App. It’s suitable for fixed-frequency checks, execution at a future time, and long tasks that continue across days.

After entering Automations from the sidebar, the setup process can be condensed into five steps:

1. Select the Project for the task.
2. Clearly write the Prompt to execute when the time comes.
3. Select the time or recurrence frequency.
4. Choose the execution environment: Local or Worktree.
5. Check permissions, save, and wait for it to run.

Scheduling methods can be categorized as:

• One-time Future Task: E.g., generate release notes tomorrow morning.
• Fixed-Period Task: Check once daily, weekly, or at a specified frequency.
• Skill-Driven Task: Explicitly call $skill-name in the Prompt to repeat the same method.
• Continuous Goal Task: Automation handles the wake-up; /goal handles remembering the cross-session objective.

Run results will go to the Triage inbox. Results that need your attention stay there; runs with no significant findings can be archived automatically. For Git repositories, using Worktree for Automation is more stable, as it won’t directly disturb the directory you’re currently editing.

Before scheduling, manually run the same Prompt in a normal thread first. Confirm that the scope, tools, output, and Diff meet expectations before handing it over to unattended execution. High-frequency Automation will also accumulate Worktrees, requiring periodic archiving of run results you no longer need.

XII. /goal is Not the Same as Plan or Automation

These three functions handle different problems.

/goal is suited for long tasks that progress across multiple sessions and have clear completion criteria. It persists its state across /clear, conversation compression, and session switches. Short, few-minute tasks don’t need /goal, and exploratory tasks that require your frequent judgment are also not suitable to be forced into an “it won’t stop until it’s done” mode.

A reasonable goal must have a verifiable end condition. For example, “Migrate all tests and make all existing tests pass” is more suitable for `/goal than “Continuously optimize this project.” If a goal is too vague, the Agent will just keep finding new things to do.

When Skills, Plugins, MCP, Automations, and /goal all appear, you can understand them this way: A Skill is an instruction manual, a Plugin is a capability pack, MCP is an external interface, Automation is an alarm clock, and /goal is a long-term task state. You don’t need to use all five at once; add the layer that’s missing for your actual work.

XIII. A Practical Learning Order from 0 to 1

If you’re just starting with Codex, you can familiarize yourself in the following order, rather than installing all extensions at once.

First Phase: Practice just four things. Choose the correct workspace, create a new Thread, control Read-only vs. Workspace-write, and learn to read the Diff. Being able to independently judge “what it changed and whether it crossed boundaries” means your foundation is solid.

Second Phase: Add Plan, the terminal, and /review. For complex tasks, review the plan first. After completion, run checks yourself, then let an independent review Agent look at the changes once.

Third Phase: Learn Worktree and multi-task parallelism. Only parallelize when you have two truly independent tasks. Don’t force a task that could be done in one go into three separate parts just to see multiple Agents running simultaneously.

Fourth Phase: Install extensions based on real needs. Solidify repetitive work into a Skill, connect to an MCP only if you need an external system, install a Plugin only if you need a full set of existing capabilities, and enable Automation and /goal only for scheduled or cross-day execution.

Whether you can proficiently use Codex doesn’t depend on how many plugins you’ve installed or how long your Prompts are each time. The real watershed is: Can you give it the correct materials and boundaries? Can you course-correct in time while it’s executing? Can you judge the result using the Diff, terminal, tests, and the page, rather than just looking at the phrase “completed”?

Quick Reference Cheat Sheet

I’m Miles, an AI algorithm expert who transitioned from a big tech company to a FDE role. I’ve worked on algorithm R&D, optimization deployment, and corporate training. Follow me @miles_mazy—let’s grow and profit together.