xonecas.io
7415
Va

vim-ai-complete / files

vim-ai-complete / AGENTS.md

2.5 KB
1# AGENTS.md
2
3Repository notes for coding agents working on `vim-ai-complete`.
4
5## Project overview
6
7This is a minimal Neovim plugin that exposes `:Ai <prompt>` for AI-assisted edits. The user visually selects text, runs `:Ai`, and the plugin replaces the selection with standard output from the configured assistant command.
8
9The plugin uses `pi` by default and invokes it with these constraints:
10
11- read-only tools: `read,find,ls,grep`
12- `--thinking high`
13- no edit or write tools; Neovim performs the replacement
14- a prompt that requests replacement text only
15
16Users can configure another assistant with `require("ai_complete").setup()`. The command can be an argument list or a function that returns one. It must accept the generated prompt and write the replacement text to standard output.
17
18## Repository layout
19
20- `plugin/ai_complete.lua`
21  - Neovim runtime entrypoint.
22  - Guards against double loading with `vim.g.loaded_ai_complete`.
23  - Defines the public `:Ai` command.
24
25- `lua/ai_complete/init.lua`
26  - Main implementation module.
27  - Builds the prompt sent to `pi`.
28  - Captures the visual selection using register `z`.
29  - Calls the external `pi` executable with `vim.fn.system`.
30  - Replaces the selected text with the command output.
31  - Restores register `z` afterward.
32
33- `README.md`
34  - User-facing description, usage, and installation notes.
35
36- `LICENSE`
37  - MIT license.
38
39## Important behavior to preserve
40
41- `:Ai` is selection-oriented. The current implementation relies on `gv` to restore the previous visual selection.
42- Register `z` is temporary scratch space. Always save and restore its contents and type.
43- Failed `pi` calls should leave the buffer unchanged.
44- The generated text should be pasted using the original selection type: characterwise, linewise, or blockwise.
45- Keep the implementation dependency-free and compatible with standard Neovim Lua APIs.
46
47## Development notes
48
49- There is currently no package metadata, test suite, formatter config, or CI.
50- Keep changes small and plugin-style: simple Lua files under `plugin/` and `lua/`.
51- Prefer clear behavior over clever abstractions; this project is intentionally tiny.
52- If changing the `pi` invocation, update `README.md` so documented behavior stays accurate.
53- If adding real line-range support, do not assume `opts.range` alone is enough; the current replacement path still uses `gv`.
54- If adding async execution, preserve the current safety properties: no register clobbering, failed calls do not edit the buffer, and user feedback is visible.