how.nvim

Ask the Neovim you are actually running.

how.nvim is a small, keyboard-first configuration assistant backed by the official Codex CLI. It inspects effective mappings, loaded plugins, your config files, operating system, and detected distribution before answering.

:How how do I move between buffers?

No API key is required when Codex is signed in with an eligible ChatGPT plan. The plugin does not read or store credentials; it talks to codex app-server over local stdio.

Principles

• Native Neovim buffers, splits, motions, search, yanks, and marks.
• No UI dependencies and no embedded browser.
• Short answers based on active runtime state rather than remembered defaults.
• Read-only by default, enforced by the Codex sandbox.
• A config change requires a detected proposal, a, and an explicit confirmation.
• Writes are scoped to stdpath("config"). Commands require another approval.

Requirements

• Neovim 0.10+
• Codex CLI
• codex login completed with ChatGPT or an OpenAI API key

Run :checkhealth how after installation.

Install

During local development with lazy.nvim:

{
  dir = vim.fn.expand("~/Developer/how.nvim"),
  name = "how.nvim",
  cmd = { "How", "HowAsk", "HowToggle", "HowApply" },
  keys = {
    { "<leader>ah", "<cmd>How<cr>", desc = "Ask How" },
  },
  opts = {},
}

After the repository is published, replace dir with its GitHub owner/repo.

Use

:How                         " open the prompt
:How why does K open hover?  " ask directly
:HowToggle                   " toggle the panel
:HowApply                    " confirm the last concrete proposal
:HowStop                     " stop streaming
:HowReset                    " new conversation

Inside the panel:

Key	Action
i	Ask a question
a	Apply the last proposal
R	Start a new conversation
<C-c>	Stop the response
g?	Toggle help
q	Close the panel

The panel is a normal read-only Markdown buffer. j, k, /, n, N, yy, marks, and window commands work normally.

Configuration

require("how").setup({
  window = {
    position = "right", -- "left" also works
    width = 0.38,
    min_width = 46,
  },
  keymaps = {
    ask = "i",
    apply = "a",
    close = "q",
    stop = "<C-c>",
    reset = "R",
    help = "g?",
  },
  codex = {
    command = "codex",
    model = nil, -- use the Codex default
  },
})

require("how").status() returns a compact string suitable for a statusline.

Change safety

Ordinary questions run with readOnly sandbox policy and approvals disabled. An assistant response becomes applicable only when it includes a valid internal proposal marker. Pressing a shows the proposal summary, files, and risk. Only the exact Apply exact proposal selection starts a workspaceWrite turn, whose writable root is the Neovim config directory.

How automatically denies requests to write outside that directory. Shell commands are displayed verbatim and require a separate Allow once decision. There is deliberately no "allow for session" shortcut.

Supported setups

Runtime inspection works with custom configurations. Detection currently labels LazyVim, NvChad, AstroNvim, LunarVim, Kickstart, and custom setups. Distribution detection is a hint; effective mappings and loaded plugins remain the source of truth.

Development

make test
make format
make check

License

MIT