7415
Va
vim-ai-complete / files
vim-ai-complete / README.md
4.7 KB
1# vim-ai-complete 2 3A small Neovim plugin for applying an LLM instruction to selected text. 4 5## How to install 6 7This plugin uses the standard Neovim plugin layout, so it should work with any plugin manager. Make sure `pi` is installed and available on Neovim's `$PATH`, or configure another LLM command. 8 9### lazy.nvim / LazyVim 10 11Add a plugin spec like this: 12 13```lua 14-- ~/.config/nvim/lua/plugins/ai-complete.lua 15return { 16 "sacenox/vim-ai-complete", 17 cmd = { "Ai", "AiComplete" }, 18} 19``` 20 21For local development, use `dir` instead: 22 23```lua 24return { 25 dir = "~/src/vim-ai-complete", 26 cmd = { "Ai", "AiComplete" }, 27} 28``` 29 30### Native packages 31 32Without a plugin manager: 33 34```bash 35cd ~/.config/nvim/pack/local/start 36git clone https://github.com/sacenox/vim-ai-complete.git 37``` 38 39## Usage 40 41### Replace visual selection 42 431. Select text in Visual mode. 442. Run `:Ai <prompt>`. 453. The selected text is replaced when generation succeeds. 46 47Run `:Ai` without a prompt to open a multiline input window below the last selected line. Press `<Enter>` to add a line and `<S-Enter>` to submit, including when the prompt is empty. Press `<Esc>` or `<C-c>` to cancel. The status area shows `Generating...` while the blocking LLM command runs. 48 49Characterwise, linewise, and blockwise selections are supported. If generation fails, the buffer is left unchanged. A completed replacement is a normal Neovim edit and can be reverted with `u`. 50 51### Completion at the cursor 52 53Run `:AiComplete` to insert a completion at the cursor, before the current character, without selecting text or entering a prompt. The agent receives the current buffer (including unsaved changes) and cursor position, and decides what to insert and whether to read additional context. Generation is blocking, just like `:Ai`. 54 55The insertion is a single undoable edit: press `u` to discard it. Failed generation leaves the buffer unchanged. 56 57### Optional key mappings 58 59The plugin does not bind keys automatically. For example, add these mappings to your Neovim configuration to use `<leader>a` for completion in Normal mode and the prompt window in Visual mode: 60 61```lua 62vim.keymap.set("n", "<leader>a", "<cmd>AiComplete<CR>", { desc = "AI completion at cursor" }) 63vim.keymap.set("x", "<leader>a", ":Ai<CR>", { desc = "AI replace selection" }) 64``` 65 66The Visual-mode mapping uses `:` to preserve the selected range. Both mappings also work with the command-based lazy-loading examples above. 67 68## LLM command 69 70The plugin uses `pi` by default. Make sure it is available on Neovim's `$PATH`, or configure another command: 71 72```lua 73require("ai_complete").setup({ 74 command = { "my-llm", "--prompt", "{prompt}" }, 75}) 76``` 77 78The configured command receives the generated prompt and writes replacement text to standard output. `{prompt}` may appear anywhere in the argument list; if omitted, the prompt is appended. For advanced integrations, `command` may be a function that receives the prompt and returns an argument list. 79 80### Claude Code, Codex, or Cursor 81 82Choose one configuration below. Install and authenticate the corresponding CLI first, and make sure its executable is on Neovim's `$PATH`. These examples work for both `:Ai` and cursor completion. Use Neovim 0.10+ so stderr (such as CLI progress messages) stays separate from the text inserted into your buffer; the older fallback may mix it into stdout. 83 84#### Claude Code 85 86```lua 87require("ai_complete").setup({ 88 command = { 89 "claude", "-p", "--output-format", "text", 90 "--tools", "Read,Glob,Grep", 91 "--strict-mcp-config", 92 "{prompt}", 93 }, 94}) 95``` 96 97Uses print mode with text output, restricts built-in tools to reading/searching, and disables configured MCP servers. See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference). 98 99#### Codex CLI 100 101```lua 102require("ai_complete").setup({ 103 command = { 104 "codex", "exec", "--sandbox", "read-only", 105 "--color", "never", "{prompt}", 106 }, 107}) 108``` 109 110`codex exec` sends progress to stderr and only the final answer to stdout. The explicit read-only sandbox keeps workspace files from being edited by the agent. Run Neovim with its working directory inside a Git repository; to work outside one, add `"--skip-git-repo-check"` before `"{prompt}"`. See [non-interactive mode](https://developers.openai.com/codex/non-interactive-mode) and the [CLI reference](https://developers.openai.com/codex/cli/reference). 111 112#### Cursor CLI 113 114```lua 115require("ai_complete").setup({ 116 command = { 117 "agent", "--mode=ask", "-p", 118 "--output-format", "text", "{prompt}", 119 }, 120}) 121``` 122 123Cursor's CLI executable is `agent`. Ask mode explores code without editing files; print mode with text output returns only the final assistant message. See [CLI modes](https://cursor.com/docs/cli/using) and [output formats](https://cursor.com/docs/cli/reference/output-format).