# Write course lessons with the Codex CLI as plain Markdown files on a Mac

Write course lessons as plain Markdown files with the Codex CLI on a Mac: a lesson folder, an AGENTS.md style file, and ⌘⇧C before each Codex run.

**The short version:** Keep one Markdown file per lesson in a course folder, add an AGENTS.md file with your style rules, and run the Codex CLI there. Point Codex at a lesson with an @-mention and read its edits in place. In Flywrite, press ⌘⇧C before you start Codex, since Codex doesn't trigger the automatic checkpoint; restore any lesson from Versions.

We make Flywrite, the Markdown writing app these steps use. More on [writing a course in Flywrite](/for/courses).

## What you'll need

- A Mac
- Flywrite, installed on that Mac
- The Codex CLI, installed and signed in with a ChatGPT plan that includes the Codex CLI, or an OpenAI API key ([OpenAI's Codex CLI guide](https://learn.chatgpt.com/docs/codex/cli), [Codex plans](https://learn.chatgpt.com/docs/pricing))
- A course outline, even a rough one

## Do it step by step

By the end, you have a course folder of lessons as ordinary Markdown files, an `AGENTS.md` file with your style rules that Codex reads at the start of each session, and a restorable checkpoint before every Codex run.

1. **Make a course folder.** In Flywrite, choose `New Project` and name it after the course, or choose `Open Folder` if your lessons already exist as files. Keep one Markdown file per lesson, numbered so they sort in order. An example course, "Email basics for small shops":

   ```text
   email-basics/
     AGENTS.md
     outline.md
     01-welcome.md
     02-your-first-list.md
     03-your-first-campaign.md
   ```

2. **Write the rules in `AGENTS.md`.** Put the course's audience, reading level, lesson template and length in a file named [`AGENTS.md`](/glossary/agents-md) at the top of the folder. Codex reads it before doing any work. It reads it once per session, so after you edit it, start a new Codex session.

   ```AGENTS.md
   # Email basics for small shops
   Audience: small shop owners who are new to email marketing.
   Reading level: plain English, short sentences, no jargon.
   Lesson template: a one-line goal, 3 to 5 numbered steps, one exercise.
   Length: 600 to 900 words per lesson.
   Never invent statistics or customer stories.
   ```

3. **Save a checkpoint, then start Codex.** Flywrite saves a checkpoint of the whole project when Claude Code starts in its terminal, and when Cursor Agent starts after its one-time setup. Codex and other CLI agents don't trigger it, so press `⌘⇧C` before you start them, or click **Checkpoint** in the top bar. Then press `⌃3`, or click **+** in the terminal tab bar and pick Codex. The shortcuts here are defaults, and [every shortcut is customizable](/docs/keyboard-shortcuts).

   ```text
   ⌘⇧C   Checkpoint Now
   ⌃3    Start Codex
   ```

   You should see: the new checkpoint at the top of the Versions panel (`⌘⇧V`), which lists checkpoints newest first.

4. **Sign in the first time.** Codex asks you to sign in on its first run: choose **Sign in with ChatGPT**, or another available method such as an API key.

   You should see: Codex running in the terminal under your draft, in its `Auto` mode, because a Flywrite project with checkpoints is a Git folder. If Codex starts read-only instead, trust the folder when it asks, or type `/permissions` and choose `Auto`.

5. **Point Codex at the lesson and ask.** Codex doesn't see your open file or selection on its own. Type `@` to pick a file, or select text in Flywrite and press `⌘⇧L` to [send it to the terminal](/guides/send-selection-to-cli-agent). In `Auto`, Codex edits files and runs commands inside the course folder without asking, and asks before editing outside it or using the network.

   ```prompt
   Using @outline.md, draft @02-your-first-list.md. Follow AGENTS.md.
   ```

6. **Read the lesson as your students will.** The editor updates as Codex edits the file. Read it in Rendered view, and press `⌘E` to switch to Source view when you want the raw Markdown.

   You should see: the lesson's headings, numbered steps and exercise formatted in Rendered view as Codex writes them.

7. **Keep it, or roll it back.** To roll back what Codex changed, press `⌘⇧V`, expand the checkpoint, and choose **Restore** on one lesson, or **Restore project to this point** for the whole course; Flywrite saves a safety checkpoint first, so a restore can be undone too. For a line-by-line list of Codex's edits, Codex's own `/diff` command shows the Git diff since your checkpoint.

   ```text
   ⌘⇧V, then expand the checkpoint:
   Restore (on one lesson)
   Restore project to this point
   ```

8. **Get notified when Codex finishes (optional).** Open Settings → Agents → Codex and click **Set up with Codex…**. Codex adds a notify setting to its own config, and Flywrite can then send a notification when Codex finishes a task in its terminal.

   You should see: a terminal where Codex adds the setting and asks you to approve the edit. Flywrite never edits that file itself.

## When not to use this

- **You want the checkpoint taken for you.** Run Claude Code instead: Flywrite saves a checkpoint of the whole project the moment it starts ([Checkpoints & versions](/docs/checkpoints-and-versions)).
- **Your lessons must be written inside your course platform.** Keep drafting there, or paste finished lessons in. Codex works on files in a folder, not inside another app's editor.
- **You don't write on a Mac.** Flywrite is Mac only. The Codex CLI also installs on Linux and Windows, so follow [OpenAI's Codex CLI guide](https://learn.chatgpt.com/docs/codex/cli) and run it in your own terminal.
- **A co-author edits the same lessons at the same time.** Checkpoints stay on your computer. Sharing goes through [GitHub backup & sync](/docs/github-backup-and-sync), which you run by hand with Sync and which can raise conflicts to resolve.

## Questions

### What does Codex's workspace-write mode let it change in my course folder?

In `Auto`, which pairs workspace-write with on-request approvals, Codex can read files, make edits and run commands inside the course folder without asking. It asks before editing files outside the folder or running commands that need network access, and the folder's `.git` stays read-only. Type `/permissions` in Codex to change the mode.

### Do I have to paste my lesson into Codex?

No. Type `@` in Codex to pick a lesson file, or select text in Flywrite and press `⌘⇧L` to send a reference to that file and those lines to the terminal. Codex doesn't see your open file or selection on its own.

## Sources

1. [Flywrite pricing](/pricing), checked 2026-11-04
2. [Flywrite docs: Your first project](/docs/your-first-project), checked 2026-11-17
3. [Flywrite docs: Writing with Codex](/docs/writing-with-codex), checked 2026-11-17
4. [Flywrite docs: The terminal](/docs/the-terminal), checked 2026-11-17
5. [Flywrite docs: Checkpoints & versions](/docs/checkpoints-and-versions), checked 2026-11-17
6. [Flywrite docs: The editor](/docs/the-editor), checked 2026-11-17
7. [Flywrite docs: Keyboard shortcuts](/docs/keyboard-shortcuts), checked 2026-11-17
8. [Flywrite docs: GitHub backup & sync](/docs/github-backup-and-sync), checked 2026-11-17
9. [OpenAI Codex docs: Codex CLI](https://learn.chatgpt.com/docs/codex/cli), checked 2026-11-10
10. [OpenAI Codex docs: Authentication](https://learn.chatgpt.com/docs/auth), checked 2026-11-04
11. [OpenAI Codex docs: Pricing](https://learn.chatgpt.com/docs/pricing), checked 2026-11-04
12. [OpenAI Codex docs: Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md), checked 2026-11-10
13. [OpenAI Codex docs: Agent approvals & security](https://learn.chatgpt.com/docs/agent-approvals-security), checked 2026-11-04
14. [OpenAI Codex docs: Developer commands (CLI)](https://learn.chatgpt.com/docs/developer-commands?surface=cli), checked 2026-11-17

---

This is the Markdown copy of https://flywrite.app/guides/codex-cli-course-lessons.
