codex-cli.el

Run Codex CLI inside Emacs — project‑scoped terminals, predictable windows, and a few high‑leverage helpers for sending prompts, regions, and files. Small surface. Stable defaults.

Single Session in a Side Window

Toggle a Project Session

All Project Sessions (Columns + Paging)

Highlights

• Project‑scoped Codex terminals (multiple sessions per project)
• Side window toggle with fixed width and optional focus
• “Show All Sessions” view with automatic column layout and paging
• Send prompt, active region, or any file under the project
• Smart chunking for large sends + optional per‑session preamble
• Optional log buffer mirroring injected content

Requirements

• Emacs 28+
• Codex CLI on PATH (codex --version)
• Optional: vterm (falls back to built‑in term)

Install

MELPA or directly from GitHub via :vc:

(use-package codex-cli
  ;; For MELPA: :ensure t
  ;; For GitHub (Emacs 29+):
  ;; :vc (:fetcher github :repo "bennfocus/codex-cli.el")
  :bind (("C-c c t" . codex-cli-toggle)
         ("C-c c s" . codex-cli-start)
         ("C-c c q" . codex-cli-stop)
         ("C-c c Q" . codex-cli-stop-all)
         ("C-c c p" . codex-cli-send-prompt)
         ("C-c c r" . codex-cli-send-region)
         ("C-c c f" . codex-cli-send-file)
         ;; Show-all layout + paging
         ("C-c c a" . codex-cli-toggle-all)
         ("C-c c n" . codex-cli-toggle-all-next-page)
         ("C-c c b" . codex-cli-toggle-all-prev-page))
  :init
  (setq codex-cli-executable "codex"
        codex-cli-terminal-backend 'vterm
        codex-cli-side 'right
        codex-cli-width 90))

Quick Start

1. Verify Codex CLI:

which codex && codex --version

2. Open a file inside a project in Emacs.

3. Start/toggle the session window:

• M-x codex-cli-toggle (creates if none; toggles otherwise)
• Or C-c c t with the binding above

4. Try sending content:

• M-x codex-cli-send-prompt → paste text into the terminal
• Select a region → M-x codex-cli-send-region
• M-x codex-cli-send-file → choose any file under the project

5. Show all sessions for the project in columns:

• M-x codex-cli-toggle-all (C-c c a), then page with C-c c n / C-c c b

Commands

• codex-cli-start — start a new session (auto id if unnamed)
• codex-cli-toggle — project‑aware toggle; prompts to create when none exist
• codex-cli-restart — kill and start again in the same buffer
• codex-cli-stop — choose an existing session and terminate it
• codex-cli-rename-session — rename a session (and its log buffer)
• codex-cli-stop-all — stop sessions in bulk (current project or all projects)

Send helpers:

• codex-cli-send-prompt — minibuffer → terminal
• codex-cli-send-region — active region or whole buffer
• codex-cli-send-file — pick and send a file under the project

Multi‑session view:

• codex-cli-toggle-all — show all sessions as columns; call again to restore layout
• codex-cli-toggle-all-next-page / codex-cli-toggle-all-prev-page — cyclic paging

Tips:

• Use C-u M-x codex-cli-start to provide a custom session name (blank = auto id).
• codex-cli-toggle/codex-cli-stop auto‑select when only one session exists.

Window & Sessions