Latest version:
- ✅ Toggle Codex floating or split window with
:CodexToggle - ✅ Seamless pane navigation (
<C-h>,<C-j>,<C-k>,<C-l>) from the Codex terminal - ✅ Optional keymap mapping via
setupcall - ✅ Background running when window hidden
- ✅ Statusline integration via
require('codex').status()
- Install the
codexCLI via npm, or mark autoinstall as true in the config function
npm install -g @openai/codex- Grab an API key from OpenAI and set it in your environment variables:
- Note: You can also set it in your
~/.bashrcor~/.zshrcfile to persist across sessions, but be careful with security. Especially if you share your config files.
- Note: You can also set it in your
export OPENAI_API_KEY=your_api_key- Use your plugin manager, e.g. lazy.nvim:
return {
'johnseth97/codex.nvim',
lazy = true,
cmd = { 'Codex', 'CodexToggle' }, -- Optional: Load only on command execution
keys = {
{
'<leader>cc', -- Change this to your preferred keybinding
function() require('codex').toggle() end,
desc = 'Toggle Codex popup',
},
},
opts = {
keymaps = {
toggle = nil, -- Keybind to toggle Codex window (Disabled by default, watch out for conflicts)
quit = '<C-q>', -- Keybind to close the Codex window (default: Ctrl + q)
}, -- Disable internal default keymap (<leader>cc -> :CodexToggle)
border = 'rounded', -- Options: 'single', 'double', or 'rounded'
layout = 'float', -- Options: 'float', 'left', 'right', 'up', 'down'
width = 0.8, -- Floating: relative width (0.0 - 1.0); Splits: absolute columns when >1
height = 0.8, -- Floating: relative height (0.0 - 1.0); Splits: absolute rows when >1
pane_navigation = true, -- Allow CTRL-based window navigation to pass through (terminal mode)
model = nil, -- Optional: pass a string to use a specific model (e.g., 'o3-mini')
autoinstall = true, -- Automatically install the Codex CLI if not found
},
}```
### Usage:
- Call `:Codex` (or `:CodexToggle`) to open or close the Codex popup.
-- Map your own keybindings via the `keymaps.toggle` setting.
- Add the following code to show backgrounded Codex window in lualine:
```lua
require('codex').status() -- drop in to your lualine sections-
All plugin configurations can be seen in the
optstable of the plugin setup, as shown in the installation section. -
layoutcontrols where the Codex terminal appears:'float'/'floating'(default) opens a centered floating window respectingborder,width, andheight.'left'/'right'open vertical splits;widthaccepts a percentage (0–1) or fixed column count (>1).'up'/'top'/'down'/'bottom'open horizontal splits;heightaccepts a percentage (0–1) or fixed row count (>1).
-
When
pane_navigationistrue(default) the Codex terminal buffer keeps Neovim's<C-h>,<C-j>,<C-k>,<C-l>navigation usable by forwarding them to window commands. Set it tofalseif you manage terminal navigation yourself. -
*For deeper customization, please refer to the Codex CLI documentation full configuration example. These features change quickly as Codex CLI is in active beta development.