Bringing Coding Harness' to Neovim

✨ Features

Requirements

Caution

You are reading the main branch README. Install details may differ from tagged releases. The current v2 beta release tag is 2.0.0-beta.2. For version-accurate instructions, read the README for your target tag from Codeberg releases.

Install

{
  url = "https://codeberg.org/yaadata/codex.nvim.git",
  version = "2.0.0-beta.2",
  lazy = false,
  cmd = {
    "Codex",
    "CodexFocus",
    "CodexTeardown",
    "CodexClearInput",
    "CodexSendSelection",
    "CodexSendFile",
    "CodexMentionFile",
    "CodexMentionDirectory",
  },
  opts = {},
  config = function(_, opts)
    require("codex").setup(opts)
  end,
}

Configuration

-- codex.Config
-- :help codex-nvim-config
require("codex").setup({

  -- codex.LaunchConfig
  -- :help codex-nvim-launch
  launch = {
    cmd = "codex", -- executable to launch
    args = {}, -- extra CLI args
    env = {}, -- extra environment variables
    auto_start = true, -- open a session after setup
    cwd = nil, -- nil = current Neovim working directory
  },

  -- codex.TerminalConfig
  -- :help codex-nvim-terminal
  terminal = {
    provider = "auto", -- prefer snacks when available, otherwise native
    auto_close = true, -- close after the Codex process exits

    -- codex.StartupConfig
    startup = {
      timeout_ms = 2000,
      retry_interval_ms = 50,
      grace_ms = 800,
    },

    -- codex.TerminalKeymapConfig
    -- :help codex-nvim-keymaps
    keymaps = {},

    -- Split sizes are reapplied on editor resize; fixed width/height is
    -- preserved when other splits open or close, subject to available space.
    -- codex.ProviderOptsConfig
    provider_opts = {
      -- codex.NativeProviderOpts
      native = {
        window = "vsplit",
        -- codex.VsplitConfig
        vsplit = {
          side = "right",
          size_pct = 40, -- shared with Snacks left/right splits
        },
        -- codex.HsplitConfig
        hsplit = {
          side = "bottom",
          size_pct = 30, -- shared with Snacks top/bottom splits
        },
        -- codex.FloatConfig
        float = {
          width_pct = 80,
          height_pct = 80,
          border = "rounded",
          title = " Codex ",
          title_pos = "center",
        },
      },
      snacks = {}, -- snacks.terminal(..., opts) pass-through
    },
  },

  -- codex.LogConfig
  -- :help codex-nvim-log
  log = {
    level = "warn",
    verbose = false,
  },

  -- codex.HooksConfig
  -- :help codex-nvim-hooks
  hooks = {
    on_setup = nil,
    on_terminal_open = nil,
    on_terminal_restore = nil,
    on_terminal_close = nil,
  },
})

Usage

local prompt = require("codex").prompt_builder
prompt.clear()
prompt.add("Review this file: ")
local ok, err = prompt.add_file()
if not ok then
  vim.notify(err, vim.log.levels.ERROR)
  return
end
prompt.send() -- paste the draft without pressing Enter

Developer Docs