xonecas.io
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).