Help Codex Understand You: Context, Prompts, and Slash Commands

💡 What this guide covers: Codex misunderstanding requests, editing too much, or searching half the project for a small bug. Learn how to provide useful context, write clear tasks, and use slash commands so it spends less time guessing and makes fewer unrelated changes.

More Codex articles: Save Effort · Codex

Where people get stuck

• Misunderstood requests and runaway edits: the extension is installed, but Codex keeps misreading the task or changing files you didn’t authorize.
• Incomplete context: without relevant files, call relationships, or business constraints, Codex has to guess.
• Unclear tasks: missing a goal, scope, or acceptance criteria can send the work off track. Because Codex can edit the project directly, treat the task as a short requirements document.
• Too much at once: handing over a whole project without acceptance criteria and expecting one prompt to solve everything.
• Wasted effort: making Codex read half the codebase to fix a tiny bug.

1. Know the two kinds of input

Codex accepts two types of input:

• Ordinary prompts: requests such as “Show me how to start this project,” “Fix the login page bug,” or “Make this function easier to follow.”
• Slash commands: inputs starting with /, such as /init, /model, /plan, /diff, /review, and /compact. They control how Codex works; they aren’t feature requirements.

In short: a prompt describes the work; a slash command manages the tool.

2. Give it the right context

Codex often goes off track because it starts in an unrelated part of the codebase. These methods all give it a clear starting point.

1. Use the context already in your editor

The VS Code extension can add open files, selected code, and recent conversations directly to the input. Codex starts with what you are looking at, so you can write shorter prompts without explaining everything again.

Suppose a project uses a service worker and contains a return statement you don’t understand. Open Codex in the editor and ask what it does. The Auto Context button shares your recent IDE activity. If the statement handles browsers without service-worker support, ask Codex to explain the condition and early return, then check that against the code. A simple question like this doesn’t require searching the entire project.

2. Name a file with @ or /mention

• In the CLI, use @ to reference a file, then ask: “How does this file work? Where would I add a button?” Selecting a file as context in the IDE serves the same purpose.
• You can also use /mention:

/mention src/api/user.ts
Explain the request flow in this file.

This is useful for an error-producing file, component, or configuration file. It focuses the investigation instead of sending Codex across the whole codebase.

• The named file may not be the file that ultimately needs editing. It is a starting point; Codex can follow the relevant code paths. Instead of “Look at the login logic in this project,” try:

Start with src/auth.ts and trace the login flow and its related calls.

3. Add selected code with a shortcut

Bind a shortcut to a frequently used extension action—for example, Command + Shift + C. Select a few lines and press it to add them as context. Selecting ten lines in hero.tsx is quicker than copying and pasting repeatedly. Use this to:

• Explain a selected block.
• Add a feature to a selected component.
• Refactor logic you don’t fully understand.
• Adjust a page to match its existing styles.

4. Send a screenshot for visual problems

When a change is hard to describe, a screenshot is clearer. Instead of explaining where “the third button on the left” is, show it.

• CLI: capture the page, paste the screenshot into the conversation, and describe the change.
• IDE extension: click the plus beside the input, attach an image such as screenshot.png from your desktop, and add instructions.

For example, if three installation commands lack background colors, attach a screenshot and ask: “Use this image to make the background of these inline code labels orange.” Have Codex locate the component, change only those labels, and check the result in a browser. This also works for colors, spacing, and layout.

5. Appshots: show it the application in front of you

Appshots in the Codex App sends a screenshot of the current application to Codex. It helps when:

• A page has an error and you don’t want to copy lots of text.
• You don’t know which setting to choose.
• A frontend page has a visual problem.
• You want the next step explained using the current screen.

Check privacy first. Look for email addresses, tokens, and project names; redact what you can. Don’t send private chats, financial screens, or admin pages containing user data. Check again before sharing a screenshot publicly.

6. Paste the complete error when debugging

Don’t extract one line or just say “It threw an error.” Include the full message and stack trace. Codex can follow the files, functions, and calls named in the error into the codebase. That is much faster than a vague description.

7. Turn TODO comments into tasks

Codex can turn code comments into work. If a button component has a “Add hover effect” comment, clicking it starts a local conversation with the relevant context. You don’t need a detailed prompt from scratch or a separate chat full of copied files. The workflow has five steps:

1. Find a useful TODO in the code.
2. Give Codex the related editor context.
3. Let it explore the project and make the change.
4. Review the edits in the IDE.
5. Check the result in a browser.

Move the pointer over the button to verify the shadow and movement—for example, a larger shadow and a slight upward shift. Confirm that clicking still works.

The IDE also has a to-do feature. Add an item such as “Implement a button on this page like the previous example,” then click Implement with Codex. Codex starts a task on the right, reads files, finds the right place, and edits the code. You can list several to-dos and work through them in order. Each step has a clear goal, so you don’t have to put every requirement in one long message.

8. Check that it is heading in the right direction

• The interface lists files it has read, giving you a quick sense of whether it found the right area.
• The IDE shows clickable file labels so you can open what it is referencing.
• A short plan breaks the work into steps and lets you see what it intends to change.
• At any time, ask it to summarize the goal and current progress. It also gives a full summary at the end.
• Don’t read only the final answer. Check which files it read, which commands it ran, why it changed a function, and how it handled failed tests. A traceable process is a major part of Codex’s value.

3. Write a clear task prompt

1. Cover four things

Explain what you want, the current project situation, the constraints, and the result you expect. AGENTS.md holds long-term project instructions—see the configuration guide. The prompt adds the specific requirements for this task.

2. A general template

Background: What the project is and the problem it currently has.
Goal: What I want you to accomplish.
Scope: Which files you may change and which you must leave alone.
Constraints: Do not add dependencies, change public APIs, or alter the database schema.
Verification: Report which files changed and run the relevant tests or checks.

Think of Codex as a temporary engineer who gets things done but can make mistakes. More detail means less guessing. If something is missing, send a follow-up.

3. Writing a feature request

You are a temporary engineer on this project.
Goal:
Make the Save button on the user settings page show a loading state during a request and prevent duplicate clicks.
Context:
This project uses React and TypeScript.
The settings page is in src/pages/settings.
Reuse the existing Button component. Do not create a new UI component.
Scope:
You may edit the settings page and its related hooks.
Do not change the API layer, routes, or styling system.
Acceptance criteria:
1. The button shows a loading state while saving.
2. Users cannot submit again until the request finishes.
3. The button returns to its normal state if the request fails.
4. Run npm run lint.
5. Report which files changed.

There is no magic here. It simply states the goal, context, scope, and acceptance criteria.

4. For bugs, ask for a plan first

Investigate this bug, but do not edit code yet.
Symptom:
Sometimes the page gives no feedback after a user taps Submit on mobile.
First:
1. Find the relevant code path.
2. Identify likely causes.
3. Propose 2–3 fixes.
4. Recommend the smallest change.
Wait for my approval before implementing it.

This works well for high-risk situations. You wouldn’t want a new teammate changing things at random either. Ask them to read the code, explain their reasoning, and propose options first.

5. Define what “done” means

When assigning a task, explain how to verify it: run tests, check formatting, or run the project’s code checks. If these are already in AGENTS.md, you don’t need to repeat them. You can also provide a yardstick:

These are the requirements this feature must satisfy when finished. Check progress against them after completing each part.

Codex can use those criteria throughout the task rather than stopping as soon as it edits the code. For verification and test evidence, see safe code changes and review.

6. Start small; have it break down large tasks

Practice with a small feature, a minor bug, or a single-file check. That makes quality easier to judge. Larger tasks create more room for mistakes and require more review. You don’t have to work out every step yourself:

Read the relevant code first and confirm how this feature currently works. Then split the work into smaller tasks that can be completed independently.

Assign them one at a time, check each result, and add requirements as needed.

7. Avoid vague requests

“Optimize this project” or “Refactor the entire system” is too vague and likely to fail. Start with: read the project and suggest refactoring options without editing code.

8. Use multiple rounds when one prompt isn’t enough

Real work is iterative: read code → propose a plan → make a small change → verify → continue. Don’t expect one prompt to produce a perfect project.

9. Ask what to do next

After finishing a feature, ask:

Based on the current codebase, what could we do next?

Codex considers the project as a whole, not just the lines it changed. Turn the answer into a to-do list and choose what is genuinely useful. A good habit is to ask for the next step after each completed feature. You can also explore broader questions, such as how to improve the feature or its performance.

OpenAI’s developer website has a more detailed Codex prompting guide if you want to go further.

4. Your first three tasks

Move from analysis to edits to verification.

Task one: read-only analysis

Read this project's README, package.json, and main entry files.
Analyze only. Do not edit code.
Tell me:
1. What the project does
2. How to run it locally
3. Which command runs the tests
4. Three small tasks you recommend next

Task two: documentation only

Clarify the local startup instructions in the README.
Edit README.md only.
Do not edit code.
Summarize the changes afterward.

Task three: a small code change

Find the login form validation code.
Fix only the inconsistent error-message wording.
Do not change the API logic.
Run the existing lint checks or tests afterward.

Codex works continuously within a workspace. You can add context, ask for changes, undo them, or request an explanation.

5. Useful tasks to hand over

Beginner tasks recommended by OpenAI

• Understand a codebase: ask what the project does, how its main modules fit together, or for a short explanation of a feature.
• Write a README: a repository owned by another team at your company can be a useful practice project.
• Fix a bug: paste the complete stack trace and let it investigate and fix it.
• Expand test coverage: find overlooked edge cases and add tests; use the prompt below.
• Refactor across files: find patterns spread across several implementations and extract a shared component; use the prompt below.
• Update documentation: engineers often put this off. After a feature or interface changes, ask Codex to update the docs using the latest code.

Start with a specific question about test gaps. Codex can identify missing tests and add them based on the actual implementation:

Which edge cases should this feature handle? What tests should we add to complete its coverage?

For repetitive refactoring, describe the goal. Codex can inspect the relevant code, identify duplication, and extract a shared implementation—faster than checking every file by hand and less likely to miss one:

Find the common patterns in these implementations, extract them into a shared component, and make the different interfaces use it.

Everyday coding tasks

• Explain the current file.
• Refactor or comment on a selected block.
• Trace an error from its message.
• Add unit tests for a function.
• Refactor and review code.
• Turn a script into a CLI tool or add comments to older code. Real, small tasks are ideal for learning how to work together.

Use Git history to get up to speed

Codex can use Git as you would in a terminal: find who changed a file, inspect commits, and summarize recent project changes. This is useful when taking over a project. Start with a read-only request to summarize history and file relationships. Let it edit only after you are satisfied it understands them.

Draw a Mermaid sequence diagram

Create a clean Mermaid sequence diagram based on this codebase.

Codex reads the code, maps the flow, and produces a concise diagram you can copy or download. Follow up to adjust details or add explanations. This is especially useful for large, complicated codebases.

Build a documentation page, then add features in rounds

In the agents.md project, for example, ask Codex to create assets.html showing how files relate. Markdown is enough for reference material. Use a browser-based documentation page when you need navigation and interaction.

• Open the generated assets.html directly in Chrome without configuring a preview tool. It can serve as project documentation covering workflows and each file’s role.
• The Codex panel shows prompts and conversations. Select the relevant conversation to see its generated files and preview them in the side panel.
• Then start a new conversation to add a feature:

Can you add a download button and a button to copy the page as Markdown next to the “View examples” and “GitHub” buttons?

• In Agent mode, Codex reads the hero component, locates the buttons, integrates them with the page, and follows the existing style. The hero area then has buttons to download the repository, open GitHub, and copy the current page as Markdown.

Assign work in two steps: first describe the specific change, where the button goes, and what clicking it does. Then open the generated file and check the result. Ask for further changes where needed. Start with something visible and add features around it in successive rounds.

You don’t have to write code

• Product managers: ask it to understand requirements, break down acceptance criteria, and check for missing implementation details.

Read this PR and its requirements.
From a product manager's perspective, check:
1. Whether every acceptance criterion is covered
2. Whether obvious edge cases are missing
3. Whether empty, error, or loading states need work
4. Whether there are user-experience risks
Do not edit code. Give me a checklist only.

• Designers: connect designs, prototypes, and existing pages to build something that runs.
• Operations and content teams: write scripts, batch-process files, organize data, and inspect pages.

The requirement is a clear task. Not knowing how to code is fine; not being able to describe the goal is the problem.

6. How to use slash commands

Three basics

1. Put the command first. /model works; “Please help me /model” doesn’t. Codex recognizes the command when / is the first character.
2. If you forget, type /. The available commands appear. Type more letters to filter them: /mo brings up /model. Lists vary by OS, version, extension, permissions, and experimental features. The list in your local installation is the one to follow.
3. Don’t assume Claude Code conventions apply. Claude Code commonly uses CLAUDE.md, /btw, and /branch. Codex uses AGENTS.md, /side, and /fork instead.

Common commands at a glance

Using /plan

Don’t send Codex straight into a big change. Instead of “Refactor the permissions system,” say:

/plan Analyze the current permissions system and propose the lowest-risk refactoring plan. Do not edit code yet.

The larger the task, the more important /plan becomes.

An eight-step first session

# 1. Enter the project
cd my-project
codex

# 2. Initialize project instructions
/init

# 3. Check status
/status

# 4. Have it read the project before editing
Do not edit code yet. Read the project structure and explain the startup command, test command, main modules, and highest-risk directories.

# 5. Plan larger work first
/plan Help fix the login page's loading state not clearing after submission. Locate relevant files and propose the smallest change. Do not edit code yet.

# 6. Implement after approval
Implement the plan, keeping the changes as small as possible.

# 7. Inspect actual changes
/diff

# 8. Review before committing
/review

Have it read, think, and edit—in that order—then check the result yourself. Don’t go fully automatic from the start.

A quick way to remember

Start with /init to introduce the project. Check /status. Use /plan for large tasks and /mention for key files. After edits, run /diff; before committing, run /review. Use /compact for long conversations, /resume when you return tomorrow, /side for a quick aside, and /fork to try another path.

A final thought

Treat Codex as a smart coding colleague who still needs your management:

• Give it context so it guesses less.
• Give it boundaries so it changes less of what it shouldn’t.
• Check the diff so vague assurances aren’t enough.

A capable Codex user puts AI in the passenger seat to watch the road, check the map, and help with repairs. You keep the steering wheel.

Official documentation to keep handy

• Codex IDE guide
• Official Codex VS Code extension