• 🧩 Composable by default. Session control, send helpers, mention helpers, slash commands, and resume flows are available as both :Codex* commands and a public Lua API.
• 🔌 API-first instead of UI-first. Build your own workflows on top of require("codex") with primitives for opening, sending, mentioning, resuming, clearing input, and more.
• 🌱 Fits into the Neovim ecosystem. Lazy-load on commands, use the built-in terminal provider or snacks, and attach your own terminal-local keymaps without fighting rigid plugin assumptions.
• 🔄 Built to evolve with Codex. The plugin wraps real Codex flows like /mention, slash commands, ACP file references, and codex resume instead of inventing a separate abstraction that drifts from the CLI.
• 🎯 Comfortable for interactive use, but scriptable when you need more. Open, focus, toggle, send selections, send files, or keep editor focus while composing larger integrations.
• 📚 Documented for users and plugin authors. :help codex.nvim covers commands, config, behavior notes, examples, and the public API in one place.

• Neovim >= 0.11.0
• codex available on your PATH (or configure launch.cmd)

{
  url = "https://codeberg.org/yaadata/codex.nvim.git",
  version = "1.0.0",
  cmd = {
    "Codex",
    "CodexFocus",
    "CodexClose",
    "CodexClearInput",
    "CodexSendSelection",
    "CodexSendFile",
    "CodexMentionFile",
    "CodexMentionDirectory",
    "CodexResume",
  },
  opts = {},
  config = function(_, opts)
    require("codex").setup(opts)
  end,
}

Use this as a quick-reference setup example. For full behavior notes and the complete user-facing reference, see :help codex.nvim.

-- 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, -- auto-open for send-like flows
    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 = {},

    -- codex.ProviderOptsConfig
    provider_opts = {
      -- codex.NativeProviderOpts
      native = {
        window = "vsplit",
        -- codex.VsplitConfig
        vsplit = {
          side = "right",
          size_pct = 40,
        },
        -- codex.HsplitConfig
        hsplit = {
          side = "bottom",
          size_pct = 30,
        },
        -- 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,
  },
})

After installation, use the quick-reference config above and open :help codex.nvim inside Neovim for the full user-facing reference, including:

• setup and the full default options table via :help codex-nvim-config
• command reference and behavior notes
• public Lua API
• keymap examples via :help codex-nvim-keymaps
• slash-command examples

Common entry points:

• :Codex toggles the Codex terminal
• :CodexSendSelection sends the active visual selection
• :CodexSendFile sends the current buffer as an ACP file reference
• :CodexMentionFile [path] and :CodexMentionDirectory [path] send /mention
• :CodexResume[!] resumes in-process or launches codex resume

If :help codex.nvim is missing after a local/raw install, generate help tags for the plugin's doc/ directory, for example :helptags {path-to-codex.nvim}/doc. Plugin managers usually do this for you; :helptags ALL is the broad fallback.

The main runtime docs are in doc/codex.nvim.txt. Developer-oriented docs remain in:

• doc/architecture.md
• doc/contributing.md
• doc/troubleshooting.md