Codex Neovim Plugin

A Neovim plugin integrating the open-sourced Codex CLI (codex)

Latest version:

Features:

• ✅ Toggle Codex window or side-panel with :CodexToggle
• ✅ Smart default keymap on <C-a> (normal: toggle + focus terminal, visual: send selection + focus terminal, terminal: close)
• ✅ Optional keymap mapping via setup call
• ✅ Background running when window hidden
• ✅ Statusline integration via require('codex').status()

Installation:

• Install the codex CLI 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 ~/.bashrc or ~/.zshrc file to persist across sessions, but be careful with security. Especially if you share your config files.

export OPENAI_API_KEY=your_api_key

• Use your plugin manager, e.g. lazy.nvim:

return {
  'kkrampis/codex.nvim',
  lazy = true,
  cmd = { 'Codex', 'CodexToggle', 'CodexSendSelection' }, -- Optional: Load only on command execution
  keys = {
    {
      '<leader>cc', -- Change this to your preferred keybinding
      function() require('codex').toggle() end,
      desc = 'Toggle Codex popup or side-panel',
      mode = { 'n', 't' }
    },
  },
  opts = {
    keymaps     = {
      smart = '<C-a>', -- Smart keymap (normal: toggle+focus, visual: send+focus, terminal: close); set `false` to disable
      toggle = nil, -- Optional keybind to toggle Codex window
      quit = '<C-q>', -- Keybind to close the Codex window (default: Ctrl + q)
    },
    border      = 'rounded',  -- Options: 'single', 'double', or 'rounded'
    width       = 0.5,        -- Width ratio used by side-panel or floating window (0.0 to 1.0)
    height      = 0.8,        -- Height of the floating window (0.0 to 1.0)
    cmd         = 'codex',    -- Command used to start Codex (string or list)
    args        = nil,        -- Optional extra Codex CLI args (string or list), e.g. { '--full-auto' }
    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
    panel       = true,       -- Default open mode is side-panel (set false for floating popup)
    use_buffer  = false,      -- Capture Codex stdout into a normal buffer instead of a terminal buffer
    cwd_from_buffer = true,   -- Default true: run Codex with cwd set to current file's directory
  },
}```

### Usage:
- Call `:Codex` (or `:CodexToggle`) to open or close the Codex popup or side-panel.
- By default, `<C-a>` is mapped to:
  - normal mode: toggle Codex and enter terminal insert mode when opening
  - visual mode: send selection and focus Codex terminal
  - terminal mode (inside Codex buffer): close Codex window
- Disable the smart mapping with `keymaps.smart = false`, or set it to another key.
- Add an additional toggle mapping via `keymaps.toggle` if desired.
- Side-panel is the default open mode. Set `panel = false` to use a floating popup instead.
- To capture Codex output in an editable buffer instead of a terminal, set `use_buffer = true` (or `false` to keep terminal) in your setup options.
- Codex runs from the current file's directory by default (`cwd_from_buffer = true`). Set it to `false` to keep process cwd.
- To pass extra CLI flags, set `args`. Example: `args = { '--full-auto' }`.
- Use `:CodexSendSelection` in visual mode to send the current selection to Codex without auto-submitting.
- Add the following code to show backgrounded Codex window in lualine:

```lua
require('codex').status() -- drop in to your lualine sections

Selection Actions:

local codex = require('codex')

-- Send arbitrary text to the running Codex terminal session.
codex.actions.send('Explain this function', { submit = false })

-- Send visual selection as:
-- File: <name>:<start>-<end>
-- <selection>
codex.actions.send_selection({ submit = false })

Migration Notes:

• cmd controls the executable/base command (string or list), e.g. { "codex", "-m", "gpt-5.3-codex" }.
• Use args for extra CLI flags while keeping cmd = 'codex', e.g. { '--full-auto' }.
• cwd_from_buffer defaults to true, so Codex uses the current file directory unless you set it to false.
• keymaps.smart defaults to <C-a> and includes normal/visual/terminal actions.
• Default UI now opens in side-panel mode (panel = true) with width = 0.5 and border = 'rounded'.
• To restore legacy defaults, set panel = false, width = 0.8, and border = 'single'.

Configuration:

• All plugin configurations can be seen in the opts table of the plugin setup, as shown in the installation section.

• *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.