Slash Commands, @-Mentions & Images

When you run codex in a project, the box at the bottom of the TUI looks like an ordinary chat input. It isn't. It's a small command surface with four distinct modes, and learning the prefixes is the difference between talking at Codex and driving it.

Everything you type is interpreted by its first character:

That's the whole mental model. The rest of this lesson is just learning what lives behind @, /, and !, plus how to attach images. Master these and you stop describing your repo to Codex in prose and start handing it the exact files, screenshots, and commands it needs — which is faster and far more accurate.

Two more keys round out the composer and are worth knowing on day one: Ctrl+G opens your external editor ($VISUAL, falling back to $EDITOR) for composing a long prompt comfortably, and Esc Esc on an empty composer edits your previous message so you can refine an instruction instead of piling on a correction.

The single highest-leverage habit in the composer is pointing Codex at specific files instead of hoping it finds them. Two tools do this.

@ — fuzzy file search. Type @ and a fuzzy file search opens over the workspace root. Start typing part of a filename and the list narrows; press Tab or Enter to drop the highlighted path straight into your message. So instead of "look at the auth middleware, I think it's somewhere in src", you write:

Why does @src/middleware/auth.ts reject valid tokens? Compare it against @tests/auth.test.ts

Now Codex has the exact paths, with zero guessing about which file you meant.

/mention — the menu alternative. /mention does the same job from the slash menu: "Attach a file to the conversation." It's the discoverable, menu-driven path to the same outcome — handy when you'd rather browse than type a fuzzy query.

Why this matters: a file path you inserted is unambiguous, whereas a prose description ("the config file") forces Codex to search and possibly pick the wrong one. Mentioning files up front also keeps the agent from burning a turn exploring — it can read exactly what you handed it and get to work.

Codex is multimodal in the composer — a screenshot of a stack trace, a Figma frame, or a broken-layout snapshot is often worth a paragraph of description. There are two ways to attach one.

Paste directly. With an image on your clipboard (a screenshot, a design spec), paste it straight into the interactive composer. It's attached to your next message.

Attach from the command line with -i / --image. When you launch Codex you can hand it image files:

codex -i screenshot.png "Explain this error"

The --image (-i) flag accepts comma-separated or repeated files, so you can attach several at once:

codex --image before.png,after.png "Why did this layout shift between these two screenshots?"

Great uses: hand it a failing-test screenshot and the relevant file (@-mention it), paste a design mockup and ask it to build the component, or show a rendering bug it can't see from the code alone. The pattern that pays off most is image + file mention together — the picture tells Codex what's wrong and the mention tells it where to fix it.

Sometimes you don't want the agent to do anything — you just want to check something and keep its output in the conversation. The ! prefix runs a single local shell command from the composer:

!ls
!git status
!npm test

Codex runs the command and treats the output like user-provided context, while still respecting your approval settings — a !-prefixed line is not a license to bypass the sandbox or approval prompts. The result lands in the transcript, so it becomes information Codex can reason about on your next turn.

Think of ! as a quick "let me show you the current state" without breaking your flow: run !git status so the agent sees your working tree, !ls src/ to confirm a path before mentioning it, or pipe a quick check in before asking Codex to act on it. It keeps your hands in one place — you're not Alt-Tabbing to another terminal and then pasting results back.

Type / and a popup of slash commands appears; keep typing to filter. The roster is large and evolving, so don't try to memorize all of it — learn the groups you reach for daily and let the popup remind you of the rest.

Here are the workhorses, organized by what you're trying to do:

A few field notes on the ones you'll use most:

• /model changes both the model and its reasoning effort within the current thread — the in-session counterpart to the -m flag.
• /permissions is your live posture switch (more on the rename below).
• /status is your usage dashboard: it shows session configuration and token usage, so you can see how close you are to compaction.
• /compact summarizes the visible conversation to free tokens when a long session is filling the window — distinct from /clear (which clears the screen and starts a fresh chat) and /new (a fresh conversation inside the same CLI session).
• /copy (or Ctrl+O) copies the latest completed Codex output — handy for pasting a result into a PR or a message.

That's a usable core. The full list also includes session, MCP, skills, plugins, and cosmetic commands you'll meet in later lessons.

Codex moves fast, and two details surprise people coming from older guides or other agents. Get them right and you'll avoid the most common composer mistakes.

1. /approvals is now /permissions. The command that sets what Codex can do without asking first was renamed. The official slash-command popup shows /permissions — "Set what Codex can do without asking first" — and /approvals no longer appears as its own entry. If a tutorial tells you to run /approvals, mentally translate it to /permissions.

2. There is no /undo. Codex deliberately has no built-in undo command. Instead, it always surfaces a transcript of every edit and command it makes, and the official guidance is to roll back using your normal git workflow. That means the safety net you actually rely on is good git hygiene:

• Commit (or at least git stash) before handing Codex a big task, so you have a clean point to return to.
• Use /diff to inspect exactly what changed (including untracked files) before you accept it.
• If a change is wrong, git restore / git checkout / git reset it — the transcript tells you precisely what happened so you know what to undo.

This is a meaningful difference from agents that keep their own checkpoint/undo stack. With Codex, git is your undo button. That's not a limitation so much as a design choice: your version control is the source of truth, and Codex stays out of its way.

Everything above is the stable core — the commands and prefixes you'll use every day. But the full slash roster is one of the fastest-moving parts of Codex. Commands get added, renamed (/approvals → /permissions is the obvious example), and reorganized between releases, and new feature commands (skills, plugins, hooks, memories, agents) show up as the product grows.

So treat any printed list — including this one — as a snapshot, not gospel. The authoritative, always-current source is the official slash-commands page:

• Live slash-command roster: https://developers.openai.com/codex/cli/slash-commands

Two habits keep you current without re-reading docs:

1. Press / and read the popup. Your installed version's actual command set is right there, with one-line descriptions. It's the truest source for your Codex.
2. Check the live page when something's missing or renamed. If a command you expected isn't in the popup, the docs (and the changelog) will tell you what replaced it.

The concepts in this lesson — mention files, attach images, shell with !, reach for slash commands by purpose — don't rot. The exact spelling of any one command might. Anchor to the concept; verify the spelling live.