When you first open Codex, the most common hurdle is understanding what each area does: the difference between projects and tasks, whether to choose Local, Worktree, or Cloud, if a Plan is necessary, how to handle permissions, and why Plugins, Skills, and MCP all exist simultaneously.
This tutorial starts with these fundamental questions. We won't start a project immediately or drag you through a complex case study. Instead, we'll first identify the interface, buttons, workspaces, and common capabilities, then judge which extension functions are worth integrating.
After reading this, you should be able to independently open a correct directory, establish tasks, control permissions, view changes, and know when to use Plan, Skill, Plugin, MCP, Automation, and /goal.
1. Understanding What Codex Actually Is
Codex is an Agent that can perform actual operations. While ordinary chat tools mainly provide text answers, Codex can read files, modify code and documents, run commands, view Git changes, open web pages, operate applications, and call connected external tools.
Therefore, the best thing to give Codex is a job with materials, boundaries, and a result. Its basic loop can be written in four steps:
Prompt → Plan → Execute → Verify
Prompt is your task, Plan is how it intends to do it, Execute is the actual reading/writing and command running, and Verify is checking the results. The most important part is the last step. When Codex says "finished," it only means it has ended the current execution; it doesn't automatically prove the file is correct, the page works, or tests have passed.
Codex has five main entry points.
Beginners don't need to learn all five at once. If you've opened the desktop app, master that first; if you're used to the terminal, add the CLI later. Cloud, IDE, and Chrome extensions serve specific scenarios, not a "more is more professional" rule.
2. Navigating the Codex App Interface from Left to Right
The Codex App main body is divided into three parts: project and task management on the left, dialogue and execution in the middle, and file change inspection on the right. Different functional panels expand around these three, but the main logic remains the same.
Left Side: Projects and Tasks
Project corresponds to a working directory. Adding a website repository, article directory, or tool project essentially tells Codex: "This batch of files belongs to the same long-term work." The project determines where it reads materials by default and where the sandbox usually allows writing.
Task (Thread, Chat) is an independent dialogue under a project. A task should ideally be responsible for one clear result, such as "check this article's structure," "fix login page error," or "organize yesterday's commit records." Projects can exist long-term; tasks should have an end point.
Common actions on the left include:
- Adding or switching projects;
- Creating new tasks under the current project;
- Opening previous tasks to continue;
- Viewing running, pending approval, or ended tasks;
- Popping a task into a separate window to view alongside a browser or editor.
If an old task has mixed in too much irrelevant context and the new requirement is completely different, starting a new task is usually cleaner. If you're just continuing to modify the same result, stay in the original task.
Middle: Dialogue Area and Input Box
The middle area displays Codex's replies, plans, commands, tool calls, approval requests, and final summaries. The bottom input box is not just a chat box; it's also the task console.
Common functions around the input box include:
- Send: Submit the current requirement;
- Stop: Interrupt the executing task;
- Model: Choose the model for 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 transcribe;
- Work Mode: Choose between Local, Worktree, and Cloud for task execution.
You don't have to wait for it to finish before speaking. If you notice it's going the wrong way, supplement immediately: "Only check, don't modify," "Don't install dependencies," "Stop at the planning stage first." The earlier you correct, the less time is wasted.
Right Side: Diff and File Changes
The right Diff panel is used to see exactly what Codex changed. Additions are usually green, and deletions are red. You can view by file or focus on changes from a specific round or the entire branch.
The Diff panel's value isn't just for "a quick look." It also handles review work:
- View all uncommitted changes;
- Add inline comments next to specific code lines;
- Stage or undo by file or change block;
- Commit, push, or create Pull Requests within the app.
If a specific line has an issue, leaving a comment right there is much more accurate than describing "that function above" in the input box. After writing the comment, just say "handle the inline comment I just made, don't expand modifications elsewhere."
3. Choosing a Workspace: Determining What Codex Sees
The workspace is the directory Codex is currently working in. Choosing the wrong directory is the most common reason for "can't find file," "modified the wrong place," or "read too much irrelevant material."
Use a simple standard for selection: Can the files needed for this task be concentrated in a minimal directory? If yes, only open that directory. Don't give Codex your entire desktop or home directory just to save one switch.
Common scenarios:
- Modifying a single independent project: Open the project root;
- Multiple unrelated apps in one repo: Add them as separate Codex projects;
- Frontend and backend in adjacent directories: Start with the main directory and add extra directory permissions as needed;
- Analysis only, no modification: Open the correct directory but set permissions to read-only;
- Tasks to be executed in a remote environment: Choose Cloud instead of expanding local permissions.
In the CLI, you can use --cd to specify the working directory and --add-dir for extra writable directories:
``bash
codex --cd ~/projects/frontend --add-dir ../backend
``
This is clearer than giving write permissions to the whole computer. The smaller the boundary, the smaller the impact of any misoperation.
4. Local, Worktree, or Cloud: Where Should the Task Run?
One of the most important choices when creating a new task is where it works.
Local: Directly Modify the Current Directory
Local works in your selected project directory. Changes appear immediately in local files, suitable for most daily tasks: editing docs, fixing bugs, running tests, organizing directories.
The advantage is directness; the disadvantage is that if you and Codex modify the same file simultaneously, you might interfere with each other. Single tasks are easiest starting from Local.
Worktree: An Isolated Copy for the Task
Worktree uses Git's worktree feature to create an independent working directory for the task. The Agent modifies things there, and your active local directory doesn't change.
It's suitable for two cases: letting multiple tasks modify the same repo simultaneously, or wanting Codex to try a change without touching the current branch immediately. Once finished, you can create branches, commit, and open PRs in the Worktree, or move results back to Local via Handoff.
Cloud: Handing the Task to the Cloud
Cloud clones the repo and executes in a remote isolated environment. It's suitable for clearly bounded, asynchronous tasks like code reviews, fixing specific issues, bulk refactoring, and running tests.
The value of Cloud is that you don't need to stay at your machine. Check the Diff after completion and decide whether to merge. For work requiring frequent discussion or local file dependencies, Local or Worktree is usually better.
5. Setting a Plan: When and When Not to Use It
A Plan is the roadmap before execution. In complex tasks, it helps you spot issues like excessive scope or unnecessary dependencies early. In simple tasks, it might just be a formality.
In the CLI, you can type:
``text
/plan
``
Or specify requirements:
``text
/plan Check the current directory and related files first, only give a modification plan, do not write files.
``
In the App, use natural language:
``text
Don't modify yet. Please confirm your understanding of the goal, the files to check, and the steps to execute. Wait for my confirmation before starting.
``
Plans are for tasks spanning multiple files, non-reversible changes, or when you're comparing implementation methods. For changing a title or running a certain command, there's no need for a five-step plan.
6. Choosing Permissions and Handling Approval Pop-ups
Codex can read/write files and run commands, so permissions cannot be vague. Common sandboxes can be understood in three levels.
For beginners, Workspace-write is enough for most work. Use Read-only for analysis. Full access should not be opened just to click "confirm" fewer times.
When you see an approval request, check four things: what command it will run, in which directory, if it needs network access, and why this step is necessary. Installing dependencies, uploading files, deleting data, or accessing credentials should always be confirmed.
7. Basic but Often Overlooked Tools
Integrated Terminal
Each App task has its own terminal (Cmd+J on macOS). The terminal directory follows the task. Codex can read the current terminal output. If you see an error, just say "check the error in the terminal" instead of copying the whole block.
In-App Browser
The built-in browser is for checking local pages. You can leave comments directly on page elements, like "make this font smaller." This is more accurate than text descriptions.
Computer Use
Computer Use lets Codex operate desktop apps (clicking, dragging, typing). It's for legacy tools without APIs or cross-app workflows. Always keep the final confirmation for humans for payments or deletions.
Image Input and Generation
Images can be dragged into the input box as context. Image generation is for UI assets or document illustrations.
Memory
Memory retains repeated preferences and corrections (e.g., specific test tools or commit formats). Long-term rules should still go in AGENTS.md for visibility.
8. Most Common CLI Commands and Keys
CLI isn't mandatory but exposes Codex's power directly. Type codex in a project directory to enter the full-screen TUI.
Common subcommands:
``bash
codex # Start interactive interface
codex exec "task" # Non-interactive execution
codex resume --last # Continue recent session
``
Useful TUI operations:
- Type
@to search/reference workspace files; - Type
!followed by a command to run Shell commands; - Press
Enterwhile the Agent is running to add instructions; - Press
Tabto queue a subsequent requirement.
9. AGENTS.md: Writing Long-term Rules for Codex
AGENTS.md is the rule file Codex reads upon entering a project. It's for build commands, code standards, and "don't do" lists. Use /init to generate a draft, then prune it. Rules should come from real problems, not a 50-page "constitution."
10. Differences Between Skills, Plugins, and MCP
- Skill: Teaches Codex how to do a type of thing;
- Plugin: Packages a set of Skills, MCPs, and connectors;
- MCP: Connects Codex to external tools and data.
Skills: Reusable Methods
A Skill is a directory with a SKILL.md core. It can be called explicitly with $skill-name or implicitly based on its description. Common skills include long-form writing, code review, or team-specific deployment methods.
Plugins: App Store Capabilities
Install plugins via the App or /plugins in CLI. Examples include Jira/Confluence (Atlassian Rovo), GitLab, GitHub, Slack, and Google Drive connectors.
MCP: External Tool Interfaces
MCP lets Codex use external services (OpenAI Docs, Figma, Playwright, Sentry) as tools. Use codex mcp add to configure.
11. Setting Up Automations
Automations are for fixed-frequency checks or long tasks.
Steps: Select project -> Write prompt -> Choose frequency -> Select environment (Local/Worktree) -> Check permissions. Always run the prompt manually once before automating.
12. /goal vs Plan vs Automation
/goal is for long tasks with clear completion standards that span multiple sessions. A good goal has a verifiable end condition, like "migrate all tests and ensure they pass."
13. The 0 to 1 Learning Path
- Phase 1: Practice choosing workspaces, creating tasks, controlling permissions, and reading Diffs.
- Phase 2: Add Plan, Terminal, and
/review. - Phase 3: Learn Worktree and multi-tasking.
- Phase 4: Install extensions (Skills, MCP, Plugins) based on real needs.
Mastery isn't about how many plugins you have, but whether you can give the Agent correct boundaries and judge results using Diffs and tests.
Final Cheat Sheet
I am Miles, an AI algorithm expert transitioned to FDE. Follow me @miles_mazy to grow and earn together.
