How to Use OpenAI Codex: Core Concepts Every Beginner Needs
A beginner's guide to OpenAI Codex covering projects, agents.md, the agent loop, and slash goals for non-coders getting started.
What is OpenAI Codex and how is it different from ChatGPT?
OpenAI Codex is an AI coding agent built to work inside a persistent project environment rather than a one-off chat window. Instead of starting from scratch every time you open a conversation, Codex works out of a folder of files on your computer (or in the cloud) that holds context about who you are, what you’re working on, and how you want it to behave. That context persistence, combined with the ability to run commands, read files, and take multi-step action on its own, is what separates Codex from a standard chatbot conversation in ChatGPT or Claude’s web interface.
TL;DR
- Projects in Codex are just folders of files on your computer that the agent reads from, so it gets smarter about your work the longer you use it instead of resetting with every new chat.
- agents.md is a plain markdown rules file that lives inside each project and tells Codex how to behave, what to prioritize, and where to find relevant information inside a large folder structure.
- The agent loop is the think-act-respond cycle that lets Codex reason, run commands, check its own results, and keep going until it finishes a task, and you can literally watch it happen step by step.
- A slash goal lets you hand Codex an objective instead of a rigid set of instructions, and the agent will keep retrying and adjusting until it satisfies that goal.
- The more objective and measurable a goal is (a specific number of sources, a specific set of deliverables), the more effective the agent is at knowing when it’s actually done.
- Codex can run locally or produce output served from a local host on your machine, which is different from something permanently hosted in the cloud and accessible to anyone else.
- Moving a setup from Claude Code to Codex is mostly a matter of renaming and reorganizing existing rules files (claude.md becomes agents.md), and Codex itself can automate much of that migration.
How do Codex projects actually work?
A Codex project is nothing more than a collection of folders and files sitting on your machine (or synced to the cloud) that Codex treats as its working memory for a specific area of your life or business. If you’ve used ChatGPT or Claude in the browser, you already know the pain point: every new chat means re-explaining your business, your preferences, and whatever you worked on last week. Projects solve that by giving Codex a fixed home base to read from.
In practice this might look like one project for your overall business operations, another for a specific app you’re building, and another for a one-off experiment. Each project can contain rules, credentials, prior conversation history, documents, and ongoing work. Because Codex can look back across everything stored in that project folder, including past chats, it can answer questions like “what have we been working on this month” by actually reviewing the accumulated files rather than guessing. The result functions less like a chatbot and more like a standing assistant that already knows the account, the goals, and the history before you type a single word.
What is agents.md and why does it matter?
agents.md is a markdown file that sits inside a Codex project and acts as the project’s rulebook. Despite the technical-sounding name, it’s just a plain text document anyone can open and read, no coding knowledge required. Each project gets its own agents.md, so the rules for one project (say, a personal operations hub) can be completely different from the rules for another (say, a video editing tool).
A well-built agents.md typically covers a few things: who the agent is working for and what its overall job is, core operating rules for how to behave, safety guardrails for anything it’s allowed to touch on your desktop, and a routing map. The routing map is especially useful once a project grows to hundreds or thousands of files, because it tells Codex where to look for specific categories of information (business documents, brand voice, active projects, reference material) instead of making it search blindly every time.
Functionally, agents.md gets read before anything else in a conversation. When you send a message, Codex reads the agents.md file first, then reads your message, then responds. That ordering is why the file works so well as a persistent set of ground rules: it’s reapplied automatically at the start of every interaction in that project, so you never have to restate your preferences.
What is the Codex agent loop?
The agent loop is the underlying think-act-respond cycle that powers Codex and similar tools (Claude Code and other “agent harnesses” work on the same basic principle). Instead of just answering in a single pass, the agent reasons about the task, decides which tools it needs, runs commands or looks things up, evaluates what it found, and repeats that cycle until it has enough to give a useful answer.
Remy is new. The platform isn't.
Remy is the latest expression of years of platform work. Not a hastily wrapped LLM.
What makes this practical for non-technical users is that the process is visible. Codex will show its reasoning steps, the commands it ran, and the files or data it checked along the way. Watching that trail is actually one of the best ways to learn how to prompt it more effectively, because you can see exactly what information it pulled and from where before it settled on a final response. For example, asking it to summarize comments from a recent YouTube upload will show it locating the right video, pulling comment data, and filtering down to a final set, all before presenting the answer.
What is a slash goal and how do you use one?
A slash goal is a way of giving Codex an objective to pursue rather than a fixed list of steps to follow. You set the goal, and the agent keeps working, adjusting, and retrying different approaches until it satisfies that goal, even if it hits obstacles along the way. This goal-oriented behavior is a defining trait of modern AI agents: they don’t give up after one failed attempt, they keep iterating.
Goals can be objective (a specific number of sources to pull, a defined set of deliverables to produce) or more open-ended (working until the result feels thorough or verified). Objective goals tend to work better because the agent has a clear, checkable condition for “done.” A looser, more emotional goal still gets pursued, but the agent has more discretion over when it considers the job finished.
One demonstrated use case involved a goal to build a batch of motion graphics for a video: an intro scene plus a set number of transition cards. The agent worked through the request, generated the assets, and visually checked its own output (taking screenshots to confirm things looked right) before marking the goal complete. The broader lesson is that as models get more capable, over-specifying every step can actually hold them back. Giving a clear goal and stepping back often produces better results than micromanaging each move, as long as the task isn’t high-risk.
Local versus cloud: what’s the difference inside Codex?
“Local” simply means a file, folder, or running process exists only on the machine you’re currently using, whether that’s a laptop or a desktop. Local files aren’t accessible from another device unless you explicitly sync or send them (through something like a cloud drive or email). Cloud storage, by contrast, is always accessible from anywhere with the right login.
This distinction matters beyond raw files too. When Codex generates something like a small website or a set of rendered videos, it may serve that output from a “local host,” a web address that only works on the machine running it. That address can look like a normal URL, but it won’t load for anyone else because nothing is actually hosted anywhere public. Understanding this difference helps avoid confusion when Codex hands you a link that works perfectly on your screen but would show nothing if shared with someone else.
Is switching from Claude Code to Codex difficult?
Not particularly. The main structural difference between the two tools is naming: Claude Code uses a claude.md file and a related folder structure, while Codex uses agents.md and an agents folder. Migrating a project built originally for Claude Code mostly involves copying the claude.md file and renaming it agents.md, then moving any custom skills or settings files into the equivalent Codex folders.
Rather than doing this by hand, you can ask Codex itself to review the existing Claude Code project, read its own documentation, and reorganize everything into a Codex-compatible structure automatically. The practical benefit is that the resulting rules and folders remain largely tool-agnostic: once your project is organized this way, it’s straightforward to use with whichever agent harness fits the task.
Frequently Asked Questions
Do I need to know how to code to use Codex?
No. The core concepts, projects, agents.md, the agent loop, and slash goals, are all designed around plain folders, markdown text files, and natural-language goals. None of them require writing code.
What exactly is agents.md written in?
It’s a markdown file, which is just plain text with simple formatting. It’s human-readable and editable in any basic text editor, not a programming language.
How does Codex know what to do without me explaining everything each time?
Because agents.md and the project’s folder structure persist between sessions, Codex reads that context automatically before responding to any new message, which removes the need to re-explain your preferences or background every time.
What makes a slash goal different from a regular prompt?
A regular prompt usually asks for one specific output. A slash goal hands the agent an objective and lets it keep working, retrying, and self-checking until that objective is met, rather than stopping after a single attempt.
Can I move my setup from another AI coding tool into Codex?
Yes. Tools like Claude Code use a similarly structured rules file (claude.md) and settings folder. Converting that into a Codex-ready project mainly involves renaming and reorganizing those files, a process Codex can largely automate when asked.
