Your First Session

You've installed Codex and signed in. The whole experience starts with one word. In any project directory, run:

codex

That opens the full-screen terminal UI (the TUI) — a composer at the bottom where you type, and a scrolling transcript above it where Codex shows its work. You're now talking to an agent that can see and act on the project you're standing in.

You can also hand it the task up front, so it starts working the moment the UI opens:

codex "fix the login bug"

Both forms do the same thing — the second just pre-fills your first message. Either way, Codex reads the project around you, so where you launch matters: start in the directory that holds the code you want it to work on. In a monorepo, open the subdirectory that contains the relevant .codex / AGENTS.md context.

The key mental model for this lesson: you are not running a command that spits out an answer and quits. You're opening a conversation with an agent that will inspect, propose, pause, and iterate with you until the task is done — and then stay open for the next instruction.

Hand Codex a task and it runs the same loop every time. Watching it happen once is the whole point of this lesson, because the loop is what makes Codex an agent rather than a chatbot.

1. Inspect the repo. Codex reads the relevant files, searches the code, and builds a picture of what's there. You'll see it open and skim files in the transcript.
2. Propose edits / commands. It decides what to do — an edit to a file, a shell command to run, a test to execute — and surfaces that proposal.
3. Pause for approval. Depending on your approval mode, Codex stops and asks before it writes a file or runs a command, showing you exactly what it intends. Nothing consequential happens behind your back.
4. Iterate conversationally. You approve (or decline, or redirect), Codex acts, observes the result, and loops back — re-reading, re-running tests — until the task is actually finished.

The pause in step 3 is the part newcomers most need to internalize. Codex is not a runaway script; by default it works inside a sandbox and asks before going beyond it. (The full matrix of where it can act and when it asks — sandbox vs. approvals — is its own lesson; here, just notice that it pauses and waits for you.)

Throughout, Codex keeps a transcript of every action it takes — every file read, every edit, every command. That transcript is both your live view of what's happening and, as you'll see next, half of your safety net.

Here is the single most important thing to understand before you let an agent edit your code: how to undo it.

Codex's answer has two parts that work together:

• The transcript surfaces every action Codex took — which files it read, what it edited, what commands it ran. Nothing is hidden, so you can always see exactly what changed and why.
• Git is your undo button. Codex deliberately does not ship a /undo slash command. Instead, you roll back through your normal git workflow — because the transcript tells you precisely what happened, standard git tools handle the reversal cleanly.

In practice, that means the habits you already have are your recovery story:

git status                 # see what Codex changed
git diff                   # review the changes in detail
git restore <file>         # discard changes to a specific file
git checkout -- .          # discard all uncommitted changes
git stash                  # shelve changes to inspect later

Inside the TUI, /diff shows you the same Git diff (including files Git isn't tracking yet) without leaving the session, so you can review before you ever touch the shell.

The practical lesson: commit before you start a risky task. A clean git checkpoint before Codex begins means git restore or git checkout can return you to a known-good state in one command, no matter how far the agent wandered.

You will not always like where Codex is heading — and you don't have to wait it out or kill the session. Three keystrokes give you full control while it runs. Getting these into muscle memory is what turns Codex from a black box into a steerable teammate.

A few nuances worth knowing on day one:

• Ctrl+C is the interrupt — not Esc. If you come from other agents where Esc stops the run, retrain that reflex: in Codex a single Esc doesn't cancel; Ctrl+C does. A double-tap of Esc on an empty composer is the edit-my-last-message gesture, which is a different (and very useful) thing.
• Esc Esc lets you fix the prompt, not patch over it. Rather than sending a second message that argues with the first, walk back and rewrite the instruction that sent Codex off course. Press Enter to fork the conversation from that point.
• Tab queues; Enter injects. Pressing Enter while Codex is running injects an instruction into the current turn; Tab holds it for the next turn. Use Tab when you want to let the current action finish first.

Codex works far better when you point it at the right context instead of making it hunt. Two lightweight ways to do that, both usable from your very first prompt.

@ for files. Type @ in the composer to open a fuzzy file search over the workspace root. Start typing part of a filename, then press Tab or Enter to drop the highlighted path into your message. So a prompt like:

Why does @src/auth/login.ts throw on empty passwords?

gives Codex an exact pointer instead of a vague description. (/mention is the menu-driven equivalent if you prefer picking from a list.)

Images for visual context. Codex is multimodal — show it a screenshot of an error, a failing UI, or a design spec:

• Paste an image directly into the interactive composer, or
• Attach from the CLI when you launch:

codex -i screenshot.png "Explain this error and fix it"

The --image / -i flag accepts comma-separated or repeated files (e.g. -i before.png,after.png), so you can hand Codex a before/after pair or several screenshots at once.

The instinct to build here: a good first prompt is a goal plus its context. Tell Codex what you want, and @-mention the files or paste the screenshot that show it the situation — that single habit eliminates a huge fraction of "Codex went the wrong way" moments.

A session doesn't have to end when you close your laptop. Codex stores each session locally, so you can pick a conversation back up with its full history intact.

codex resume          # opens a picker of recent sessions in this project
codex resume --last   # jumps straight to your most recent session here

The plain codex resume shows a picker of recent sessions — highlight one to see its summary and press Enter to reopen it. codex resume --last skips the picker and reopens the most recent session from your current directory. Inside a session, the /resume slash command does the same, and /new starts a fresh conversation without leaving the CLI.

While you're working, one slash command is worth knowing from day one:

• /status displays your session configuration and token usage — which model and reasoning effort are active, and how much of your usage window you've consumed. It's the quickest way to answer "what mode am I in?" and "how much have I used?" without leaving the session.

That's the full day-one toolkit: start with codex, watch the loop, steer with Ctrl+C / Esc Esc / Tab, attach context with @ and images, undo with git, and come back later with codex resume. Everything deeper — approval modes, sandboxing, config, MCP — builds on this foundation.