https://github.com/johnseth97/codex.nvim
OpenAI Codex plugin for Neovim
https://github.com/johnseth97/codex.nvim
neovim neovim-plugin openai openai-codex
Last synced: 15 days ago
JSON representation
OpenAI Codex plugin for Neovim
- Host: GitHub
- URL: https://github.com/johnseth97/codex.nvim
- Owner: johnseth97
- Created: 2025-04-18T07:47:29.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-20T01:56:01.000Z (7 months ago)
- Last Synced: 2026-05-15T09:07:48.308Z (29 days ago)
- Topics: neovim, neovim-plugin, openai, openai-codex
- Language: Lua
- Homepage:
- Size: 76.2 KB
- Stars: 238
- Watchers: 1
- Forks: 26
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-side-quests - johnseth97/codex.nvim
README
# Codex Neovim Plugin
## A Neovim plugin integrating the open-sourced Codex CLI (`codex`)
> Latest version: 
### Features:
- ✅ Toggle Codex window or side-panel with `:CodexToggle`
- ✅ 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
```bash
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.
```bash
export OPENAI_API_KEY=your_api_key
```
- Use your plugin manager, e.g. lazy.nvim:
```lua
return {
'kkrampis/codex.nvim',
lazy = true,
cmd = { 'Codex', 'CodexToggle' }, -- Optional: Load only on command execution
keys = {
{
'cc', -- Change this to your preferred keybinding
function() require('codex').toggle() end,
desc = 'Toggle Codex popup or side-panel',
mode = { 'n', 't' }
},
},
opts = {
keymaps = {
toggle = nil, -- Keybind to toggle Codex window (Disabled by default, watch out for conflicts)
quit = '', -- Keybind to close the Codex window (default: Ctrl + q)
}, -- Disable internal default keymap (cc -> :CodexToggle)
border = 'rounded', -- Options: 'single', 'double', or 'rounded'
width = 0.8, -- Width of the floating window (0.0 to 1.0)
height = 0.8, -- Height of the floating window (0.0 to 1.0)
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 = false, -- Open Codex in a side-panel (vertical split) instead of floating window
use_buffer = false, -- Capture Codex stdout into a normal buffer instead of a terminal buffer
},
}```
### Usage:
- Call `:Codex` (or `:CodexToggle`) to open or close the Codex popup or side-panel.
- Map your own keybindings via the `keymaps.toggle` setting.
- To choose floating popup vs side-panel, set `panel = false` (popup) or `panel = true` (panel) in your setup options.
- 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.
- Add the following code to show backgrounded Codex window in lualine:
```lua
require('codex').status() -- drop in to your lualine sections
```
### 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](https://github.com/openai/codex?tab=readme-ov-file#full-configuration-example) full configuration example. These features change quickly as Codex CLI is in active beta development.*