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.