my-codex.el

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

my-codex.el runs the Google Antigravity CLI (agy) or OpenAI Codex CLI (codex) inside Emacs using vterm.

Note

The package is named my-codex.el because it initially supported only the OpenAI Codex CLI. It has since been expanded to support Google Antigravity as a first-class agent.

It keeps your code on the left and the active agent CLI on the right, providing helpers for regions, files, Git diffs, compiler errors, build commands, and commit messages. Agent buffers are project-specific, keeping separate sessions per project.

Features

• Multi-Agent CLI Support: start, resume, and manage sessions with Google Antigravity or OpenAI Codex, with granular workspace write-access control.
• Side-by-Side Layout: code on the left, interactive agent terminal on the right.
• Context-Aware Prompts: send regions, files, Git diffs, compiler errors, or project structure overviews directly to the agent.
• Refactoring & Coverage: draft low-risk refactoring plans for file ranges and analyze implementation files against tests for missing coverage.
• Integration Tools: export session transcripts, summarize transcripts into Markdown notes, and draft commits or GitHub issues directly from Emacs.
• Interactive UI: insert agent output back into your code, and open clickable file references and URLs directly from the terminal.
• Diagnostics: verify Emacs, agent binaries, vterm, and Git configuration using the my-codex-doctor health check.

Requirements

• Emacs 29.1 or newer.
• vterm.
• transient.
• Google Antigravity CLI and/or OpenAI Codex CLI.
• Git (for Git commands) and GitHub CLI gh (for issue creation).

vterm is loaded lazily only when an agent session is started.

Installation

Clone the repository and add it to your Emacs load path:

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

Key Bindings & Usage

Press F8 to open the agent command menu.

Session Management

• F8 o / F8 w : start/show the default read-only or workspace-write session.
• F8 S o / F8 S w : select an agent, then start its default read-only or write session.
• F8 S n : start or show a named session (allows side-by-side Codex & Antigravity sessions).
• F8 S l / F8 S q / F8 S t : list open sessions, hide the selected session window, or view the sessions dashboard.
• F8 r / F8 q : resume a previous session, or hide the active agent window.

Prompts & Refactoring

• F8 a / F8 A : ask a free-form question or open the customizable prompt preset menu.
• F8 s (or F8 Right) / F8 R : send the selected region, or draft a low-risk refactoring plan for it.
• F8 Left / F8 TAB : insert agent text into code, or toggle focus between code and agent.
• F8 f / F8 C / F8 p : ask the agent to inspect the current file, analyze test coverage, or send a project overview.
• F8 x / F8 e : explain the symbol at point, or explain a selected error.

Git & GitHub Workflow

• F8 g / F8 G : review the current Git diff or the staged Git diff.
• F8 v / F8 V : view the current or staged Git diff locally.
• F8 d / F8 D : ediff the current or a changed file against HEAD.
• F8 c : draft or reuse an agent-generated commit message, edit it, then commit.
• F8 X / F8 M : export the session transcript, or summarize the session to Markdown notes.
• F8 t / F8 T : list open GitHub issues, or draft a GitHub issue from the session.

Diagnostics, Build & Instructions

• F8 ! : run my-codex-doctor diagnostics.
• F8 i : open project instruction files (e.g., AGENTS.md, CODEX.md).
• F7 : run the project build command.

Customisation

Configure options via M-x customize-group RET my-codex RET.

;; Set the default agent profile
(setq my-codex-agent 'antigravity)

;; Customize agent launch commands
(setq my-codex-antigravity-workspace-command "agy --sandbox")
(setq my-codex-antigravity-resume-command "agy resume")

;; Layout & build commands
(setq my-codex-right-width 80)
(setq my-codex-project-build-command "./setup_build")
(setq my-codex-project-instruction-files
      '("AGENTS.md" "CODEX.md" "ANTIGRAVITY.md"))

;; Prompt & warning thresholds
(setq my-codex-enable-prompt-preview t)
(setq my-codex-large-prompt-warning-chars 12000)
(setq my-codex-warn-about-unsaved-project-buffers t)

Updating CLI binaries

Antigravity CLI

The Antigravity CLI (agy) has a built-in self-updater. Run the following command to update:

agy update

Codex CLI

This repository includes optional helper scripts for updating direct GitHub binary installations of Codex CLI:

./update-codex.sh

On Windows, run from PowerShell:

.\update-codex.ps1

The scripts are intentionally conservative. They only update installations where the active codex command points to a direct binary downloaded from the OpenAI Codex GitHub releases, and they refuse common package-manager or wrapper installations such as npm, Homebrew, Snap, Flatpak, Scoop, Chocolatey, or winget. If you installed Codex with a package manager, update it with that package manager instead.

Depending on where codex is installed, the Linux script may ask for sudo. On Windows, close running Codex sessions first and use an elevated PowerShell session if the destination directory requires administrator rights.

Companion Skills

The skills/ directory contains optional agent skills that complement this package. They are provided as editable source, are not installed automatically, and are not required for the Emacs package to work.

Expert users can copy, symlink, modify, or ignore them according to their own agent setup.

Example invocations:

Skill	Description	Example invocation
consilium	Codebase advisor and plan manager. Finds improvements and writes implementation plans.	$consilium audit codebase
grill-me	Stress-test a plan or design by asking focused questions one at a time.	$grill-me stress-test this refactoring plan
handoff	Create a disposable Markdown context transfer for continuing focused work in another agent session.	$handoff continue the Firebird SQL refactoring

Attribution:

Skill	Attribution	Reference
grill-me	Matt Pocock	grill-me: Stress-Test a Plan Before You Build
handoff	Matt Pocock	handoff: Move Context Between Agent Sessions

Licence

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