xonecas.io
7415
Va

vim-ai-complete / commit cf0655d

chore: Adds AGENTS.md

xonecas2026-05-24 cf0655d575b62f200dd72c902810a8fa7e764437 parent 5728400

2 files changed

AGENTS.md+53−0
@@ -0,0 +1,53 @@
1+# AGENTS.md
2+
3+Repository notes for coding agents working on `vim-pi-complete`.
4+
5+## Project overview
6+
7+This is a minimal Neovim plugin that exposes `:Pi <prompt>` for AI-assisted edits. The user visually selects text, runs `:Pi`, and the plugin replaces the selection with stdout from the `pi` coding agent.
8+
9+The plugin intentionally invokes `pi` in a constrained way:
10+
11+- read-only tools only: `read,find,ls,grep`
12+- `--thinking minimal` for speed
13+- no edit/write tools; Neovim performs the actual replacement
14+- prompt asks for replacement text only
15+
16+## Repository layout
17+
18+- `plugin/pi_complete.lua`
19+ - Neovim runtime entrypoint.
20+ - Guards against double loading with `vim.g.loaded_pi_complete`.
21+ - Defines the public `:Pi` command.
22+ - Adds a lowercase `:pi` command-line abbreviation.
23+
24+- `lua/pi_complete/init.lua`
25+ - Main implementation module.
26+ - Builds the prompt sent to `pi`.
27+ - Captures the visual selection using register `z`.
28+ - Calls the external `pi` executable with `vim.fn.system`.
29+ - Replaces the selected text with the command output.
30+ - Restores register `z` afterward.
31+
32+- `README.md`
33+ - User-facing description, usage, and installation notes.
34+
35+- `LICENSE`
36+ - MIT license.
37+
38+## Important behavior to preserve
39+
40+- `:Pi` is selection-oriented. The current implementation relies on `gv` to restore the previous visual selection.
41+- Register `z` is temporary scratch space. Always save and restore its contents and type.
42+- Failed `pi` calls should leave the buffer unchanged.
43+- The generated text should be pasted using the original selection type: characterwise, linewise, or blockwise.
44+- Keep the implementation dependency-free and compatible with standard Neovim Lua APIs.
45+
46+## Development notes
47+
48+- There is currently no package metadata, test suite, formatter config, or CI.
49+- Keep changes small and plugin-style: simple Lua files under `plugin/` and `lua/`.
50+- Prefer clear behavior over clever abstractions; this project is intentionally tiny.
51+- If changing the `pi` invocation, update `README.md` so documented behavior stays accurate.
52+- If adding real line-range support, do not assume `opts.range` alone is enough; the current replacement path still uses `gv`.
53+- If adding async execution, preserve the current safety properties: no register clobbering, failed calls do not edit the buffer, and user feedback is visible.
README.md+38−3
@@ -16,13 +16,48 @@ Just select, prompt, and send. Then hope for the best. Each prompt is its own in
1616
1717 ## How to install
1818
19-I know there are many package managers, so please use any that you know. If I need to make changes to support one, file an issue or PR.
19+This plugin uses the standard Neovim plugin layout, so it should work with any plugin manager. Make sure the external `pi` executable is installed and available on Neovim's `$PATH`.
2020
21-Here's how to do it without a package manager:
21+### lazy.nvim / LazyVim
22+
23+Add a plugin spec like this:
24+
25+```lua
26+-- ~/.config/nvim/lua/plugins/pi-complete.lua
27+return {
28+ "sacenox/vim-pi-complete",
29+ cmd = { "Pi" },
30+}
31+```
32+
33+For local development, use `dir` instead:
34+
35+```lua
36+return {
37+ dir = "~/src/vim-pi-complete",
38+ cmd = { "Pi" },
39+}
40+```
41+
42+Note: when lazy-loading with `cmd = { "Pi" }`, the lowercase `:pi` abbreviation is only available after the plugin has loaded. Use `:Pi` to trigger loading, or define the abbreviation in `init`:
43+
44+```lua
45+return {
46+ "sacenox/vim-pi-complete",
47+ cmd = { "Pi" },
48+ init = function()
49+ vim.cmd([[cabbrev pi Pi]])
50+ end,
51+}
52+```
53+
54+### Native packages
55+
56+Without a plugin manager:
2257
2358 ```bash
2459 cd ~/.config/nvim/pack/local/start
25-git clone <this repo>
60+git clone https://github.com/sacenox/vim-pi-complete.git
2661 ```
2762
2863 Then restart Neovim.