my-codex.el

┌───────────────┬───────────────┐
│ code          │ codex         │
│ 1  </>        │ >_            │
│ 2  ─────      │ ─────────     │
│ 3  ───────    │ ─────         │
│ 4  }          │ ▌             │
└───────────────┴───────────────┘

my-codex.el runs the OpenAI Codex CLI inside Emacs using vterm.

It keeps code on the left and Codex on the right, with small helpers for regions, files, Git diffs, build output, project instructions, and commit messages. Codex buffers are project-specific, so different projects keep separate sessions.

Features

• Start Codex in read-only, workspace-write, or resume mode.
• Use a two-column layout and restore the previous window layout.
• Send selected code, the current file, Git diffs, or staged Git diffs.
• Ask free-form questions from the minibuffer.
• Draft a commit message from staged changes, then open an editable commit.
• Explain selected compiler or test errors.
• Open project instruction files such as AGENTS.md.
• Run a configurable project build command.
• Warn when project buffers have unsaved changes before sending prompts.
• Enable global-auto-revert-mode when my-codex-global-mode starts.
• Provide global keys and a Tools -> Codex menu.

Requirements

• Emacs 29.1 or newer.
• vterm.
• OpenAI Codex CLI available as codex.
• Git, for Git-related commands.

vterm is loaded lazily, only when Codex is used.

Installation

Clone the repository somewhere in your Emacs load path:

git clone https://github.com/morinim/my_codex.git ~/.emacs.d/lisp/my_codex

Then add:

(add-to-list 'load-path "~/.emacs.d/lisp/my_codex")
(require 'my-codex)
(my-codex-global-mode 1)

Basic Usage

Start Codex first:

F8 o   start in read-only mode
F8 w   start with workspace-write access
F8 r   resume a previous session

Then use the F8 prefix for everyday actions.

Key Bindings

Key	Command	Description
F7	my-codex-project-build	Run the project build command
F8	my-codex-map	Codex prefix key

Prefix bindings:

Key	Command	Description
F8 o	my-codex-read-only	Show/start read-only Codex
F8 w	my-codex-workspace	Show/start workspace-write Codex
F8 r	my-codex-resume	Resume a Codex session
F8 q	my-codex-restore-layout	Restore the previous window layout
F8 a	my-codex-ask	Ask a free-form question
F8 s	my-codex-send-region	Send the selected region
F8 Right	my-codex-send-region	Send the selected region
F8 Left	my-codex-insert-selection-into-code	Insert selected Codex text into code
F8 TAB	my-codex-toggle-focus	Toggle focus between code and Codex
F8 f	my-codex-send-current-file	Ask Codex to inspect the current file
F8 g	my-codex-send-git-diff	Review the current Git diff
F8 G	my-codex-send-git-staged-diff	Review the staged Git diff
F8 m	my-codex-commit-message-from-diff	Draft a commit message
F8 c	my-codex-git-commit-with-latest-message	Edit a commit using the latest drafted message
F8 e	my-codex-explain-region-as-error	Explain a selected error
F8 i	my-codex-open-project-instructions	Open project instructions
F8 ?	my-codex-help	Show help

Inside vterm:

Key	Command
F8	Use the Codex prefix
Shift Insert	Paste into vterm
C-c C-t	Enter vterm copy mode
Page Up / Page Down	Scroll the terminal buffer

Customisation

Use:

M-x customize-group RET my-codex RET

Common options:

(setq my-codex-read-only-command
      "codex --sandbox read-only --ask-for-approval on-request")
(setq my-codex-workspace-command
      "codex --sandbox workspace-write --ask-for-approval on-request")
(setq my-codex-resume-command "codex resume")

(setq my-codex-left-width 80)
(setq my-codex-min-right-width 80)

(setq my-codex-project-build-command "./setup_build")
(setq my-codex-project-instruction-files
      '("AGENTS.md" "CODEX.md" ".codex/instructions.md"))

(setq my-codex-warn-about-unsaved-project-buffers t)
(setq my-codex-enable-global-auto-revert t)

Suggested Codex Configuration

For conservative defaults, configure Codex itself to use read-only mode and explicit approvals.

In ~/.codex/config.toml:

sandbox_mode = "read-only"
approval_policy = "on-request"
approvals_reviewer = "user"

Notes

Use F8 s or F8 Right for small snippets. For larger reviews, prefer F8 f, F8 g, or F8 G, which ask Codex to inspect files or diffs directly.

To copy text from Codex, use C-c C-t in the vterm buffer, select text, then use F8 Left to insert it into the coding window.

Licence

Mozilla Public License v2.0, also available in LICENSE.