codex: Emacs integration for OpenAI Codex CLI

codex.el provides an Emacs interface to the OpenAI Codex CLI, running Codex through the native app-server renderer or a terminal backend. You can interact with Codex without leaving your editor — start sessions, send commands, review output, and manage multiple instances across projects.

The package uses eat by default, can render natively through app-server, and can use vterm if you install it separately. It is modeled after claude-code.el, sharing a similar architecture and workflow.

Key capabilities include:

• Session management — start Codex in the current project, resume or fork previous sessions, run multiple named instances, kill instances individually or in bulk.
• Sending commands and context — send freeform prompts, prompts annotated with file/line context, the active region or entire buffer, file paths, images, and error-at-point requests.
• TUI interaction — send return, escape, digits, Tab (follow-up), agent navigation, and other key sequences to the Codex TUI from any buffer; prompt autosuggestions are shown with a distinct face in eat buffers.
• Stable Emacs terminal behavior — starts Codex with --no-alt-screen by default to avoid alternate-screen desynchronization in Emacs terminal buffers, preserves long scrollback in Codex terminal buffers, maps Eat blinking cursor states to non-blinking equivalents, and provides M-x codex-redraw for explicitly opted-in alt-screen sessions.
• Window and buffer management — toggle the Codex window, switch between instances, read-only mode for navigating output.
• Hooks and notifications — auto-configures the Codex CLI hooks system so Emacs receives lifecycle events for Emacs-owned sessions; desktop notifications when Codex awaits input.
• Transient menus — a main command menu and a slash commands menu for quick keyboard access.
• Live configuration — change model, reasoning effort, sandbox mode, approval policy, and profile on the fly via transient infixes.

Installation

Requires Emacs 28.1 or later.

package-vc (built-in since Emacs 29)

(use-package codex
  :vc (:url "https://github.com/benthamite/codex"))

Elpaca

(use-package codex
  :ensure (:host github :repo "benthamite/codex"))

straight.el

(use-package codex
  :straight (:host github :repo "benthamite/codex"))

Dependencies

• transient (>= 0.9.3)
• inheritenv (>= 0.2)
• eat (>= 0.9.4)
• Optional: vterm, when codex-terminal-backend is set to vterm
• The Codex CLI must be installed and available in your PATH.

Quick start

After installing the package and the Codex CLI, you can start a session with M-x codex. New sessions use the eat terminal backend by default for compatibility with the Codex CLI TUI. Set codex-terminal-backend to app-server or to vterm if you prefer those terminal backends.

;; Optional: bind the command map to a prefix of your choice.
(global-set-key (kbd "C-c x") codex-command-map)

;; Start Codex in the current project
;; C-c x c  — or M-x codex

;; Send a command from any buffer
;; C-c x s  — or M-x codex-send-command

;; Toggle the Codex window
;; C-c x t  — or M-x codex-toggle

;; Open the transient menu for all commands
;; C-c x m  — or M-x codex-transient

Documentation

For a comprehensive description of all user options, commands, and functions, see the manual.