Why
my-codex currently depends on vterm as its terminal backend. That works well on Unix-like systems, but it effectively blocks native Windows support because vterm is not a realistic option there.
Adding eat as an alternative backend would give the package a Windows-compatible terminal path while keeping vterm as the preferred backend where it already works well.
This should not replace vterm; it should introduce a backend choice.
Goals
- Keep
vterm as the default backend on supported platforms.
- Add
eat as an optional backend.
- Allow native Windows users to run Codex/Antigravity inside Emacs without requiring WSL.
- Keep the existing vterm behaviour unchanged.
- Avoid large rewrites by reusing the existing backend abstraction.
Proposed Design
Introduce a backend custom option:
(defcustom my-codex-terminal-backend 'vterm
"Terminal backend used by my-codex."
:type '(choice (const :tag "vterm" vterm)
(const :tag "eat" eat)))
Optionally, the default could be platform-aware:
(if (eq system-type 'windows-nt)
'eat
'vterm)
Add a new backend struct:
(cl-defstruct (my-codex-eat-backend
(:constructor my-codex--make-eat-backend))
buffer-name)
Then implement the existing backend protocol for eat:
my-codex-backend-start
my-codex-backend-send
my-codex-backend-live-p
The existing my-codex-vterm-backend should remain as-is where possible.
Implementation Tasks
- Add
my-codex-terminal-backend.
- Generalise backend creation in
my-codex--backend-for-buffer-name.
- Generalise buffer-name access in
my-codex--backend-buffer-name.
- Add
my-codex-eat-backend.
- Add eat autoloads / declarations after confirming the public API.
- Implement start/send/live methods for eat.
- Split terminal integration:
- keep
my-codex-vterm.el
- add
my-codex-eat.el
- Make global integration mode enable only the relevant terminal integration. 9. Update doctor checks to report the selected backend.
- Update
README with Windows guidance.
- Add tests mirroring the existing mocked vterm backend tests.
Open API Questions
Before implementation, verify the exact eat API for:
- starting an eat buffer with a specific shell command
- sending text to the running terminal
- sending return / newline
- detecting whether the terminal process is alive
- paste/yank behaviour
- copy-mode or scrollback equivalents, if any
Non-goals
- Removing vterm
- Making vterm work on native Windows
- Rewriting the terminal abstraction
- Supporting every Emacs terminal package immediately
Acceptance Criteria
- Existing vterm workflows still pass tests.
- Users can select eat via customisation.
- On Windows, eat can be used without loading or requiring vterm.
- my-codex-doctor reports the selected backend and useful diagnostics.
- README documents the recommended backend choices:
- Unix / WSL: vterm
- Native Windows: eat
- Tests cover backend selection, backend start/send/live behaviour, and doctor output for both backends.
Why
my-codexcurrently depends onvtermas its terminal backend. That works well on Unix-like systems, but it effectively blocks native Windows support becausevtermis not a realistic option there.Adding
eatas an alternative backend would give the package a Windows-compatible terminal path while keepingvtermas the preferred backend where it already works well.This should not replace
vterm; it should introduce a backend choice.Goals
vtermas the default backend on supported platforms.eatas an optional backend.Proposed Design
Introduce a backend custom option:
Optionally, the default could be platform-aware:
Add a new backend struct:
Then implement the existing backend protocol for eat:
my-codex-backend-startmy-codex-backend-sendmy-codex-backend-live-pThe existing
my-codex-vterm-backendshould remain as-is where possible.Implementation Tasks
my-codex-terminal-backend.my-codex--backend-for-buffer-name.my-codex--backend-buffer-name.my-codex-eat-backend.my-codex-vterm.elmy-codex-eat.elREADMEwith Windows guidance.Open API Questions
Before implementation, verify the exact eat API for:
Non-goals
Acceptance Criteria