diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 730bd60..d265ccd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,7 @@ on:
jobs:
docs:
runs-on: ubuntu-latest
- if: ${{ github.ref == 'refs/heads/main' }}
+ if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs' }}
steps:
- uses: actions/checkout@v3
- name: panvimdoc
@@ -16,6 +16,9 @@ jobs:
vimdoc: gp.nvim
demojify: true
treesitter: true
+ docmapping: true
+ docmappingprojectname: false
+ dedupsubheadings: false
- name: Push changes
uses: stefanzweifel/git-auto-commit-action@v4
with:
diff --git a/README.md b/README.md
index e37baa5..b9b2656 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,6 @@
-# Gp.nvim (GPT prompt) Neovim AI plugin
-
-
@@ -11,9 +8,13 @@
+# Gp.nvim (GPT prompt) Neovim AI plugin
+
-Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code operations in your favorite editor.
+
+
+**ChatGPT like sessions, Instructable text/code operations, Speech to text and Image generation in your favorite editor.**
@@ -24,7 +25,7 @@ Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code op
- [5-min-demo](https://www.youtube.com/watch?v=X-cT7s47PLo) (December 2023)
- [older-5-min-demo](https://www.youtube.com/watch?v=wPDcBnQgNCc) (screen capture, no sound)
-## Goals and Features
+# Goals and Features
The goal is to extend Neovim with the **power of GPT models in a simple unobtrusive extensible way.**
Trying to keep things as native as possible - reusing and integrating well with the natural features of (Neo)vim.
@@ -35,7 +36,7 @@ Trying to keep things as native as possible - reusing and integrating well with
- properly working undo (response can be undone with a single `u`)
- **Infinitely extensible** via hook functions specified as part of the config
- hooks have access to everything in the plugin and are automatically registered as commands
- - see [Configuration](#4-configuration) and [Extend functionality](#extend-functionality) sections for details
+ - see [4. Configuration](#4-configuration) and [Extend functionality](#extend-functionality) sections for details
- **Minimum dependencies** (`neovim`, `curl`, `grep` and optionally `sox`)
- zero dependencies on other lua plugins to minimize chance of breakage
- **ChatGPT like sessions**
@@ -54,11 +55,14 @@ Trying to keep things as native as possible - reusing and integrating well with
- **Speech to text support**
- a mouth is 2-4x faster than fingers when it comes to outputting words - use it where it makes sense
(dicating comments and notes, asking gpt questions, giving instructions for code operations, ..)
+- **Image generation**
+ - be even less tempted to open the browser with the ability to generate images directly from Neovim
-## Install
+# Install
-### 1. Install the plugin with your preferred package manager:
+## 1. Install the plugin
+Snippets for your preferred package manager:
```lua
-- lazy.nvim
{
@@ -89,23 +93,25 @@ use({
})
```
-### 2. OpenAI API key
+## 2. OpenAI API key
-Make sure you have OpenAI API key. [Get one here](https://platform.openai.com/account/api-keys) and use it in the [config](#4-configuration). Also consider setting up [usage limits](https://platform.openai.com/account/billing/limits) so you won't get suprised at the end of the month.
+Make sure you have OpenAI API key. [Get one here](https://platform.openai.com/account/api-keys) and use it in the [4. Configuration](#4-configuration). Also consider setting up [usage limits](https://platform.openai.com/account/billing/limits) so you won't get suprised at the end of the month.
The OpenAI API key can be passed to the plugin in multiple ways:
-| Method | Example | Security Level |
-|------------------|----------------------------------------------------------------|----------------|
-| hardcoded string | `openai_api_key: "sk-...",` | Low |
-| default env var | set `OPENAI_API_KEY` environment variable in shell config | Medium |
-| custom env var | `openai_api_key = os.getenv("CUSTOM_ENV_NAME"),` | Medium |
-| read from file | `openai_api_key = { "cat", "path_to_api_key" },` | Medium-High |
-| password manager | `openai_api_key = { "bw", "get", "password", "OAI_API_KEY" },` | High |
+
+| Method | Example | Security Level |
+|------------------------|----------------------------------------------------------------|----------------|
+| hardcoded string | `openai_api_key: "sk-...",` | Low |
+| default env var | set `OPENAI_API_KEY` environment variable in shell config | Medium |
+| custom env var | `openai_api_key = os.getenv("CUSTOM_ENV_NAME"),` | Medium |
+| read from file | `openai_api_key = { "cat", "path_to_api_key" },` | Medium-High |
+| password manager | `openai_api_key = { "bw", "get", "password", "OAI_API_KEY" },` | High |
+
If `openai_api_key` is a table, Gp runs it asynchronously to avoid blocking Neovim (password managers can take a second or two).
-### 3. Dependencies
+## 3. Dependencies
The core plugin only needs `curl` installed to make calls to OpenAI API and `grep` for ChatFinder. So Linux, BSD and Mac OS should be covered.
@@ -117,82 +123,155 @@ Voice commands (`:GpWhisper*`) depend on `SoX` (Sound eXchange) to handle audio
- Redhat/CentOS: `yum install sox`
- NixOS: `nix-env -i sox`
-### 4. Configuration
+## 4. Configuration
+
+Bellow is a linked snippet with the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs.
-Bellow are the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs.
https://github.com/Robitx/gp.nvim/blob/7d802f54fb503f27fc9722656efddb05a533f4cf/lua/gp/config.lua#L8-L350
-## Usage
-
-### Commands
-
-- Have ChatGPT experience directly in neovim:
-
- - `:GpChatNew` - open fresh chat in the current window
- (either empty or with the visual selection or specified range as a context)
- - `:GpChatPaste` - paste the selection or specified range to the latest chat
- (simplifies adding code from multiple files into a single chat buffer)
- - `:GpChatToggle` - open chat in toggleable popup window
- (the last active chat or a fresh one with selection or a range as a context)
- - `:GpChatFinder` - open a dialog to search through chats
- - `:GpChatRespond` - request new gpt response for the current chat
- - `:GpChatRespond N` - request new gpt response with only last N messages as a context
- (using everything from the end up to Nth instance of `🗨:..` => `N=1` is like asking a question in a new chat)
- - `:GpChatDelete` - delete the current chat
-
- when calling `:GpChatNew` or `:GpChatPaste` and `GpChatToggle` you can also specify where to display chat using subcommands:
- ![image](https://github.com/Robitx/gp.nvim/assets/8431097/350b38ce-52fb-4df7-b2a5-d6e51581f0c3)
-
-- Ask GPT and get response to the specified output:
-
- - `:GpRewrite` - answer replaces the current line, visual selection or range
- - `:GpAppend` - answers after the current line, visual selection or range
- - `:GpPrepend` - answers before the current line, selection or range
- - `:GpEnew` - answers into a new buffer in the current window
- - `:GpNew` - answers into new horizontal split window
- - `:GpVnew` - answers into new vertical split window
- - `:GpTabnew` - answers into new tab
- - `:GpPopup` - answers into pop up window
- - `:GpImplement` - default example hook command for finishing the code
- based on comments provided in visual selection or specified range
-
- all these command work either:
-
- - as pure user commands without any other context in normal/insert mode
- - with current selection (using whole lines) as a context in visual/Visual mode
- - with specified range (such as `%` for the entire current buffer => `:%GpRewrite`)
-
-- Provide custom context per repository with`:GpContext`:
-
- - opens `.gp.md` file for given repository in toggable window
- - if used with selection/range it appends it to the context file
- - supports display targeting subcommands just like `GpChatNew`
- - see [Custom instructions](#custom-instructions-per-repository) section
-
-- Switch between configured agents (model + persona):
-
- - `:GpNextAgent` - cycle between available agents
- - `:GpAgent` - display currently used agents for chat and command instructions
- - `:GpAgent XY` - choose new agent based on its name
-
- commands are context aware (they switch chat or command agent based on the current buffer)
-
-- Voice commands transcribed by Whisper API:
- - `:GpWhisper` - transcription replaces the current line, visual selection or range in the current buffer (use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel)
- for the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command (`GpWhisperRewrite` dictates instructions for `GpRewrite` etc.):
- - `:GpWhisperRewrite` - answer replaces the current line, visual selection or range
- - `:GpWhisperAppend` - answers after the current line, visual selection or range
- - `:GpWhisperPrepend` - answers before the current line, selection or range
- - `:GpWhisperEnew` - answers into new buffer in the current window
- - `:GpWhisperNew` - answers into new horizontal split
- - `:GpWhisperVnew` - answers into new vertical split
- - `:GpWhisperTabnew` - answers into new tab
- - `:GpWhisperPopup` - answers into pop up window
-- To stop the stream of currently running gpt response you can use `:GpStop`
-- Run your own custom hook commands:
- - `:GpInspectPlugin` - inspect GPT prompt plugin object
-
-### GpDone autocommand to run consequent actions
+# Usage
+
+## Chat commands
+
+#### `:GpChatNew`
+Open a fresh chat in the current window. It can be either empty or include the visual selection or specified range as context. This command also supports subcommands for layout specification:
+
+- `:GpChatNew vsplit` Open a fresh chat in a vertical split window.
+- `:GpChatNew split` Open a fresh chat in a horizontal split window.
+- `:GpChatNew tabnew` Open a fresh chat in a new tab.
+- `:GpChatNew popup` Open a fresh chat in a popup window.
+
+#### `:GpChatPaste`
+Paste the selection or specified range into the latest chat, simplifying the addition of code from multiple files into a single chat buffer. This command also supports subcommands for layout specification:
+
+- `:GpChatPaste vsplit` Paste into the latest chat in a vertical split window.
+- `:GpChatPaste split` Paste into the latest chat in a horizontal split window.
+- `:GpChatPaste tab` Paste into the latest chat in a new tab.
+- `:GpChatPaste popup` Paste into the latest chat in a popup window.
+
+#### `:GpChatToggle`
+Open chat in a toggleable popup window, showing the last active chat or a fresh one with selection or a range as a context. This command also supports subcommands for layout specification:
+
+- `:GpChatToggle vsplit` Toggle chat in a vertical split window.
+- `:GpChatToggle split` Toggle chat in a horizontal split window.
+- `:GpChatToggle tab` Toggle chat in a new tab.
+- `:GpChatToggle popup` Toggle chat in a popup window.
+
+#### `:GpChatFinder`
+Open a dialog to search through chats.
+
+#### `:GpChatRespond`
+Request a new GPT response for the current chat. Usin`:GpChatRespond N` request a new GPT response with only the last N messages as context, using everything from the end up to the Nth instance of `🗨:..` (N=1 is like asking a question in a new chat).
+
+#### `:GpChatDelete`
+Delete the current chat. By default requires confirmation before delete, which can be disabled in config using `chat_confirm_delete = false,`.
+
+## Text/Code commands
+
+#### `:GpRewrite`
+Opens a dialog for entering a prompt. After providing prompt instructions into the dialog, the generated response replaces the current line in normal/insert mode, selected lines in visual mode, or the specified range (e.g., `:%GpRewrite` applies the rewrite to the entire buffer).
+
+`:GpRewrite {prompt}` Executes directly with specified `{prompt}` instructions, bypassing the dialog. Suitable for mapping repetitive tasks to keyboard shortcuts or for automation using headless Neovim via terminal or shell scripts.
+
+#### `:GpAppend`
+Similar to `:GpRewrite`, but the answer is added after the current line, visual selection, or range.
+
+#### `:GpPrepend`
+Similar to `:GpRewrite`, but the answer is added before the current line, visual selection, or range.
+
+#### `:GpEnew`
+Similar to `:GpRewrite`, but the answer is added into a new buffer in the current window.
+
+#### `:GpNew`
+Similar to `:GpRewrite`, but the answer is added into a new horizontal split window.
+
+#### `:GpVnew`
+Similar to `:GpRewrite`, but the answer is added into a new vertical split window.
+
+#### `:GpTabnew`
+Similar to `:GpRewrite`, but the answer is added into a new tab.
+
+#### `:GpPopup`
+Similar to `:GpRewrite`, but the answer is added into a pop-up window.
+
+#### `:GpImplement`
+Example hook command to develop code from comments in a visual selection or specified range.
+
+#### `:GpContext`
+Provides custom context per repository:
+
+- opens `.gp.md` file for a given repository in a toggable window.
+- appends selection/range to the context file when used in visual/range mode.
+- also supports subcommands for layout specification:
+
+ - `:GpContext vsplit` Open `.gp.md` in a vertical split window.
+ - `:GpContext split` Open `.gp.md` in a horizontal split window.
+ - `:GpContext tabnew` Open `.gp.md` in a new tab.
+ - `:GpContext popup` Open `.gp.md` in a popup window.
+
+- refer to [Custom Instructions](#custom-instructions) for more details.
+## Speech commands
+
+#### `:GpWhisper`
+Transcription replaces the current line, visual selection or range in the current buffer. Use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel..
+
+For the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates instructions for `GpRewrite` etc.
+
+#### `:GpWhisperRewrite`
+Similar to `:GpRewrite`, but the prompt instruction dialog uses transcribed spoken instructions.
+
+#### `:GpWhisperAppend`
+Similar to `:GpAppend`, but the prompt instruction dialog uses transcribed spoken instructions for adding content after the current line, visual selection, or range.
+
+#### `:GpWhisperPrepend`
+Similar to `:GpPrepend`, but the prompt instruction dialog uses transcribed spoken instructions for adding content before the current line, selection, or range.
+
+#### `:GpWhisperEnew`
+Similar to `:GpEnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new buffer within the current window.
+
+#### `:GpWhisperNew`
+Similar to `:GpNew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new horizontal split window.
+
+#### `:GpWhisperVnew`
+Similar to `:GpVnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new vertical split window.
+
+#### `:GpWhisperTabnew`
+Similar to `:GpTabnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new tab.
+
+#### `:GpWhisperPopup`
+Similar to `:GpPopup`, but the prompt instruction dialog uses transcribed spoken instructions for displaying content in a pop-up window.
+
+## Agent commands
+
+#### `:GpNextAgent`
+Cycles between available agents based on the current buffer (chat agents if current buffer is a chat and command agents otherwise). The agent setting is persisted on disk across Neovim instances.
+
+#### `:GpAgent`
+Displays currently used agents for chat and command instructions.
+
+#### `:GpAgent XY`
+Choose a new agent based on its name, listing options based on the current buffer (chat agents if current buffer is a chat and command agents otherwise). The agent setting is persisted on disk across Neovim instances.
+
+## Image commands
+
+#### `:GpImage`
+Opens a dialog for entering a prompt describing wanted images. When the generation is done it opens dialog for storing the image to the disk.
+
+#### `:GpImageAgent`
+Displays currently used image agent (configuration).
+
+#### `:GpImageAgent XY`
+Choose a new "image agent" based on its name. In the context of images, agent is basically a configuration for model, image size, quality and so on. The agent setting is persisted on disk across Neovim instances.
+
+## Other commands
+
+#### `:GpStop`
+Stops all currently running responses and jobs.
+
+#### `:GpInspectPlugin`
+Inspects the GPT prompt plugin object in a new scratch buffer.
+
+## GpDone autocommand
Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate event `GpDone`, so you can define autocmd (like auto formating) to run when gp finishes:
@@ -207,7 +286,7 @@ Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate event
})
```
-### Custom instructions per repository
+## Custom instructions
By calling `:GpContext` you can make `.gp.md` markdown file in a root of a repository. Commands such as `:GpRewrite`, `:GpAppend` etc. will respect instructions provided in this file (works better with gpt4, gpt 3.5 doesn't always listen to system commands). For example:
@@ -220,7 +299,7 @@ Use Early return/Guard Clauses pattern to avoid excessive nesting.
Here is [another example](https://github.com/Robitx/gp.nvim/blob/main/.gp.md).
-### Scripting and multifile edits
+## Scripting
`GpDone` event + `.gp.md` custom instructions provide a possibility to run gp.nvim using headless (neo)vim from terminal or shell script. So you can let gp run edits accross many files if you put it in a loop.
@@ -266,11 +345,11 @@ Ahoy there!
5
```
-### Shortcuts
+# Shortcuts
There are no default global shortcuts to mess with your own config. Bellow are examples for you to adjust or just use directly.
-#### Native
+## Native
You can use the good old `vim.keymap.set` and paste the following after `require("gp").setup(conf)` call
(or anywhere you keep shortcuts if you want them at one place).
@@ -355,7 +434,7 @@ vim.keymap.set("v", "wv", ":'<,'>GpWhisperVnew", keymapOptions("Vi
vim.keymap.set("v", "wt", ":'<,'>GpWhisperTabnew", keymapOptions("Visual Whisper Tabnew"))
```
-#### Whichkey
+## Whichkey
Or go more fancy by using [which-key.nvim](https://github.com/folke/which-key.nvim) plugin:
@@ -519,7 +598,7 @@ require("which-key").register({
})
```
-## Extend functionality
+# Extend functionality
You can extend/override the plugin functionality with your own, by putting functions into `config.hooks`.
Hooks have access to everything (see `InspectPlugin` example in defaults) and are
diff --git a/doc/gp.nvim.txt b/doc/gp.nvim.txt
index 9408ed8..7d0d917 100644
--- a/doc/gp.nvim.txt
+++ b/doc/gp.nvim.txt
@@ -3,12 +3,29 @@
==============================================================================
Table of Contents *gp.nvim-table-of-contents*
- - Goals and Features |gp.nvim-goals-and-features|
- - Install |gp.nvim-install|
- - Usage |gp.nvim-usage|
- - Extend functionality |gp.nvim-extend-functionality|
-Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code
-operations in your favorite editor.
+1. Goals and Features |gp.nvim-goals-and-features|
+2. Install |gp.nvim-install|
+ - 1. Install the plugin |gp.nvim-1.-install-the-plugin|
+ - 2. OpenAI API key |gp.nvim-2.-openai-api-key|
+ - 3. Dependencies |gp.nvim-3.-dependencies|
+ - 4. Configuration |gp.nvim-4.-configuration|
+3. Usage |gp.nvim-usage|
+ - Chat commands |gp.nvim-chat-commands|
+ - Text/Code commands |gp.nvim-text/code-commands|
+ - Agent commands |gp.nvim-agent-commands|
+ - Image commands |gp.nvim-image-commands|
+ - Other commands |gp.nvim-other-commands|
+ - GpDone autocommand |gp.nvim-gpdone-autocommand|
+ - Custom instructions |gp.nvim-custom-instructions|
+ - Scripting |gp.nvim-scripting|
+4. Shortcuts |gp.nvim-shortcuts|
+ - Native |gp.nvim-native|
+ - Whichkey |gp.nvim-whichkey|
+5. Extend functionality |gp.nvim-extend-functionality|
+
+
+**ChatGPT like sessions, Instructable text/code operations, Speech to text and
+Image generation in your favorite editor.**
@@ -18,7 +35,8 @@ YOUTUBE DEMOS ~
- older-5-min-demo (screen capture, no sound)
-GOALS AND FEATURES *gp.nvim-goals-and-features*
+==============================================================================
+1. Goals and Features *gp.nvim-goals-and-features*
The goal is to extend Neovim with the **power of GPT models in a simple
unobtrusive extensible way.** Trying to keep things as native as possible -
@@ -30,7 +48,7 @@ reusing and integrating well with the natural features of (Neo)vim.
- properly working undo (response can be undone with a single `u`)
- **Infinitely extensible** via hook functions specified as part of the config
- hooks have access to everything in the plugin and are automatically registered as commands
- - see |gp.nvim-configuration| and |gp.nvim-extend-functionality| sections for details
+ - see |gp.nvim-4.-configuration| and |gp.nvim-extend-functionality| sections for details
- **Minimum dependencies** (`neovim`, `curl`, `grep` and optionally `sox`)
- zero dependencies on other lua plugins to minimize chance of breakage
- **ChatGPT like sessions**
@@ -49,12 +67,17 @@ reusing and integrating well with the natural features of (Neo)vim.
- **Speech to text support**
- a mouth is 2-4x faster than fingers when it comes to outputting words - use it where it makes sense
(dicating comments and notes, asking gpt questions, giving instructions for code operations, ..)
+- **Image generation**
+ - be even less tempted to open the browser with the ability to generate images directly from Neovim
+
+==============================================================================
+2. Install *gp.nvim-install*
-INSTALL *gp.nvim-install*
+1. INSTALL THE PLUGIN *gp.nvim-1.-install-the-plugin*
-1. INSTALL THE PLUGIN WITH YOUR PREFERRED PACKAGE MANAGER: ~
+Snippets for your preferred package manager:
>lua
-- lazy.nvim
@@ -87,40 +110,35 @@ INSTALL *gp.nvim-install*
<
-2. OPENAI API KEY ~
+2. OPENAI API KEY *gp.nvim-2.-openai-api-key*
Make sure you have OpenAI API key. Get one here
and use it in the
-|gp.nvim-config|. Also consider setting up usage limits
+|gp.nvim-4.-configuration|. Also consider setting up usage limits
so you won’t get
suprised at the end of the month.
The OpenAI API key can be passed to the plugin in multiple ways:
- ------------------------------------------------------------------------------------------
- Method Example Security
- Level
- ------------- -------------------------------------------------------------- -------------
- hardcoded openai_api_key: "sk-...", Low
- string
+ ---------------------------------------------------------------------------------------------
+ Method Example Security
+ Level
+ ---------------- -------------------------------------------------------------- -------------
+ hardcoded string openai_api_key: "sk-...", Low
- default env set OPENAI_API_KEY environment variable in shell config Medium
- var
+ default env var set OPENAI_API_KEY environment variable in shell config Medium
- custom env openai_api_key = os.getenv("CUSTOM_ENV_NAME"), Medium
- var
+ custom env var openai_api_key = os.getenv("CUSTOM_ENV_NAME"), Medium
- read from openai_api_key = { "cat", "path_to_api_key" }, Medium-High
- file
+ read from file openai_api_key = { "cat", "path_to_api_key" }, Medium-High
- password openai_api_key = { "bw", "get", "password", "OAI_API_KEY" }, High
- manager
- ------------------------------------------------------------------------------------------
+ password manager openai_api_key = { "bw", "get", "password", "OAI_API_KEY" }, High
+ ---------------------------------------------------------------------------------------------
If `openai_api_key` is a table, Gp runs it asynchronously to avoid blocking
Neovim (password managers can take a second or two).
-3. DEPENDENCIES ~
+3. DEPENDENCIES *gp.nvim-3.-dependencies*
The core plugin only needs `curl` installed to make calls to OpenAI API and
`grep` for ChatFinder. So Linux, BSD and Mac OS should be covered.
@@ -135,78 +153,275 @@ recording and processing:
- NixOS: `nix-env -i sox`
-4. CONFIGURATION ~
+4. CONFIGURATION *gp.nvim-4.-configuration*
+
+Bellow is a linked snippet with the default values, but I suggest starting with
+minimal config possible (just `openai_api_key` if you don’t have
+`OPENAI_API_KEY` env set up). Defaults change over time to improve things,
+options might get deprecated and so on - it’s better to change only things
+where the default doesn’t fit your needs.
+
-Bellow are the default values, but I suggest starting with minimal config
-possible (just `openai_api_key` if you don’t have `OPENAI_API_KEY` env set
-up). Defaults change over time to improve things, options might get deprecated
-and so on - it’s better to change only things where the default doesn’t fit
-your needs.
https://github.com/Robitx/gp.nvim/blob/7d802f54fb503f27fc9722656efddb05a533f4cf/lua/gp/config.lua#L8-L350
-USAGE *gp.nvim-usage*
-
-
-COMMANDS ~
-
-- Have ChatGPT experience directly in neovim:
- - `:GpChatNew` - open fresh chat in the current window
- (either empty or with the visual selection or specified range as a context)
- - `:GpChatPaste` - paste the selection or specified range to the latest chat
- (simplifies adding code from multiple files into a single chat buffer)
- - `:GpChatToggle` - open chat in toggleable popup window
- (the last active chat or a fresh one with selection or a range as a context)
- - `:GpChatFinder` - open a dialog to search through chats
- - `:GpChatRespond` - request new gpt response for the current chat
- - `:GpChatRespond N` - request new gpt response with only last N messages as a context
- (using everything from the end up to Nth instance of `🗨:..` => `N=1` is like asking a question in a new chat)
- - `:GpChatDelete` - delete the current chat
- when calling `:GpChatNew` or `:GpChatPaste` and `GpChatToggle` you can also
- specify where to display chat using subcommands:
-- Ask GPT and get response to the specified output:
- - `:GpRewrite` - answer replaces the current line, visual selection or range
- - `:GpAppend` - answers after the current line, visual selection or range
- - `:GpPrepend` - answers before the current line, selection or range
- - `:GpEnew` - answers into a new buffer in the current window
- - `:GpNew` - answers into new horizontal split window
- - `:GpVnew` - answers into new vertical split window
- - `:GpTabnew` - answers into new tab
- - `:GpPopup` - answers into pop up window
- - `:GpImplement` - default example hook command for finishing the code
- based on comments provided in visual selection or specified range
- all these command work either:
- - as pure user commands without any other context in normal/insert mode
- - with current selection (using whole lines) as a context in visual/Visual mode
- - with specified range (such as `%` for the entire current buffer => `:%GpRewrite`)
-- Provide custom context per repository with`:GpContext`
- - opens`.gp.md` file for given repository in toggable window
- - if used with selection/range it appends it to the context file
- - supports display targeting subcommands just like `GpChatNew`
- - see |gp.nvim-custom-instructions| section
-- Switch between configured agents (model + persona):
- - `:GpNextAgent` - cycle between available agents
- - `:GpAgent` - display currently used agents for chat and command instructions
- - `:GpAgent XY` - choose new agent based on its name
- commands are context aware (they switch chat or command agent based on the
- current buffer)
-- Voice commands transcribed by Whisper API:
- - `:GpWhisper` - transcription replaces the current line, visual selection or range in the current buffer (use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel)
- for the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command (`GpWhisperRewrite` dictates instructions for `GpRewrite` etc.):
- - `:GpWhisperRewrite` - answer replaces the current line, visual selection or range
- - `:GpWhisperAppend` - answers after the current line, visual selection or range
- - `:GpWhisperPrepend` - answers before the current line, selection or range
- - `:GpWhisperEnew` - answers into new buffer in the current window
- - `:GpWhisperNew` - answers into new horizontal split
- - `:GpWhisperVnew` - answers into new vertical split
- - `:GpWhisperTabnew` - answers into new tab
- - `:GpWhisperPopup` - answers into pop up window
-- To stop the stream of currently running gpt response you can use `:GpStop`
-- Run your own custom hook commands:
- - `:GpInspectPlugin` - inspect GPT prompt plugin object
-
-
-GPDONE AUTOCOMMAND TO RUN CONSEQUENT ACTIONS ~
+==============================================================================
+3. Usage *gp.nvim-usage*
+
+
+CHAT COMMANDS *gp.nvim-chat-commands*
+
+
+:GpChatNew *:GpChatNew*
+
+Open a fresh chat in the current window. It can be either empty or include the
+visual selection or specified range as context. This command also supports
+subcommands for layout specification:
+
+- `:GpChatNew vsplit` Open a fresh chat in a vertical split window.
+- `:GpChatNew split` Open a fresh chat in a horizontal split window.
+- `:GpChatNew tabnew` Open a fresh chat in a new tab.
+- `:GpChatNew popup` Open a fresh chat in a popup window.
+
+
+:GpChatPaste *:GpChatPaste*
+
+Paste the selection or specified range into the latest chat, simplifying the
+addition of code from multiple files into a single chat buffer. This command
+also supports subcommands for layout specification:
+
+- `:GpChatPaste vsplit` Paste into the latest chat in a vertical split window.
+- `:GpChatPaste split` Paste into the latest chat in a horizontal split window.
+- `:GpChatPaste tab` Paste into the latest chat in a new tab.
+- `:GpChatPaste popup` Paste into the latest chat in a popup window.
+
+
+:GpChatToggle *:GpChatToggle*
+
+Open chat in a toggleable popup window, showing the last active chat or a fresh
+one with selection or a range as a context. This command also supports
+subcommands for layout specification:
+
+- `:GpChatToggle vsplit` Toggle chat in a vertical split window.
+- `:GpChatToggle split` Toggle chat in a horizontal split window.
+- `:GpChatToggle tab` Toggle chat in a new tab.
+- `:GpChatToggle popup` Toggle chat in a popup window.
+
+
+:GpChatFinder *:GpChatFinder*
+
+Open a dialog to search through chats.
+
+
+:GpChatRespond *:GpChatRespond*
+
+Request a new GPT response for the current chat. Usin`:GpChatRespond N` request
+a new GPT response with only the last N messages as context, using everything
+from the end up to the Nth instance of `🗨:..` (N=1 is like asking a question
+in a new chat).
+
+
+:GpChatDelete *:GpChatDelete*
+
+Delete the current chat. By default requires confirmation before delete, which
+can be disabled in config using `chat_confirm_delete = false,`.
+
+
+TEXT/CODE COMMANDS *gp.nvim-text/code-commands*
+
+
+:GpRewrite *:GpRewrite*
+
+Opens a dialog for entering a prompt. After providing prompt instructions into
+the dialog, the generated response replaces the current line in normal/insert
+mode, selected lines in visual mode, or the specified range (e.g.,
+`:%GpRewrite` applies the rewrite to the entire buffer).
+
+`:GpRewrite {prompt}` Executes directly with specified `{prompt}` instructions,
+bypassing the dialog. Suitable for mapping repetitive tasks to keyboard
+shortcuts or for automation using headless Neovim via terminal or shell
+scripts.
+
+
+:GpAppend *:GpAppend*
+
+Similar to `:GpRewrite`, but the answer is added after the current line, visual
+selection, or range.
+
+
+:GpPrepend *:GpPrepend*
+
+Similar to `:GpRewrite`, but the answer is added before the current line,
+visual selection, or range.
+
+
+:GpEnew *:GpEnew*
+
+Similar to `:GpRewrite`, but the answer is added into a new buffer in the
+current window.
+
+
+:GpNew *:GpNew*
+
+Similar to `:GpRewrite`, but the answer is added into a new horizontal split
+window.
+
+
+:GpVnew *:GpVnew*
+
+Similar to `:GpRewrite`, but the answer is added into a new vertical split
+window.
+
+
+:GpTabnew *:GpTabnew*
+
+Similar to `:GpRewrite`, but the answer is added into a new tab.
+
+
+:GpPopup *:GpPopup*
+
+Similar to `:GpRewrite`, but the answer is added into a pop-up window.
+
+
+:GpImplement *:GpImplement*
+
+Example hook command to develop code from comments in a visual selection or
+specified range.
+
+
+:GpContext *:GpContext*
+
+Provides custom context per repository:
+
+- opens `.gp.md` file for a given repository in a toggable window.
+- appends selection/range to the context file when used in visual/range mode.
+- also supports subcommands for layout specification:
+ - `:GpContext vsplit` Open `.gp.md` in a vertical split window.
+ - `:GpContext split` Open `.gp.md` in a horizontal split window.
+ - `:GpContext tabnew` Open `.gp.md` in a new tab.
+ - `:GpContext popup` Open `.gp.md` in a popup window.
+- refer to |gp.nvim-custom-instructions| for more details. ## Speech commands
+
+
+:GpWhisper *:GpWhisper*
+
+Transcription replaces the current line, visual selection or range in the
+current buffer. Use your mouth to ask a question in a chat buffer instead of
+writing it by hand, dictate some comments for the code, notes or even your next
+novel..
+
+For the rest of the whisper commands, the transcription is used as an editable
+prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates
+instructions for `GpRewrite` etc.
+
+
+:GpWhisperRewrite *:GpWhisperRewrite*
+
+Similar to `:GpRewrite`, but the prompt instruction dialog uses transcribed
+spoken instructions.
+
+
+:GpWhisperAppend *:GpWhisperAppend*
+
+Similar to `:GpAppend`, but the prompt instruction dialog uses transcribed
+spoken instructions for adding content after the current line, visual
+selection, or range.
+
+
+:GpWhisperPrepend *:GpWhisperPrepend*
+
+Similar to `:GpPrepend`, but the prompt instruction dialog uses transcribed
+spoken instructions for adding content before the current line, selection, or
+range.
+
+
+:GpWhisperEnew *:GpWhisperEnew*
+
+Similar to `:GpEnew`, but the prompt instruction dialog uses transcribed spoken
+instructions for opening content in a new buffer within the current window.
+
+
+:GpWhisperNew *:GpWhisperNew*
+
+Similar to `:GpNew`, but the prompt instruction dialog uses transcribed spoken
+instructions for opening content in a new horizontal split window.
+
+
+:GpWhisperVnew *:GpWhisperVnew*
+
+Similar to `:GpVnew`, but the prompt instruction dialog uses transcribed spoken
+instructions for opening content in a new vertical split window.
+
+
+:GpWhisperTabnew *:GpWhisperTabnew*
+
+Similar to `:GpTabnew`, but the prompt instruction dialog uses transcribed
+spoken instructions for opening content in a new tab.
+
+
+:GpWhisperPopup *:GpWhisperPopup*
+
+Similar to `:GpPopup`, but the prompt instruction dialog uses transcribed
+spoken instructions for displaying content in a pop-up window.
+
+
+AGENT COMMANDS *gp.nvim-agent-commands*
+
+
+:GpNextAgent *:GpNextAgent*
+
+Cycles between available agents based on the current buffer (chat agents if
+current buffer is a chat and command agents otherwise). The agent setting is
+persisted on disk across Neovim instances.
+
+
+:GpAgent *:GpAgent*
+
+Displays currently used agents for chat and command instructions.
+
+
+:GpAgent XY *:GpAgent-XY*
+
+Choose a new agent based on its name, listing options based on the current
+buffer (chat agents if current buffer is a chat and command agents otherwise).
+The agent setting is persisted on disk across Neovim instances.
+
+
+IMAGE COMMANDS *gp.nvim-image-commands*
+
+
+:GpImage *:GpImage*
+
+Opens a dialog for entering a prompt describing wanted images. When the
+generation is done it opens dialog for storing the image to the disk.
+
+
+:GpImageAgent *:GpImageAgent*
+
+Displays currently used image agent (configuration).
+
+
+:GpImageAgent XY *:GpImageAgent-XY*
+
+Choose a new "image agent" based on its name. In the context of images, agent
+is basically a configuration for model, image size, quality and so on. The
+agent setting is persisted on disk across Neovim instances.
+
+
+OTHER COMMANDS *gp.nvim-other-commands*
+
+
+:GpStop *:GpStop*
+
+Stops all currently running responses and jobs.
+
+
+:GpInspectPlugin *:GpInspectPlugin*
+
+Inspects the GPT prompt plugin object in a new scratch buffer.
+
+
+GPDONE AUTOCOMMAND *gp.nvim-gpdone-autocommand*
Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate
event `GpDone`, so you can define autocmd (like auto formating) to run when gp
@@ -224,7 +439,7 @@ finishes:
<
-CUSTOM INSTRUCTIONS PER REPOSITORY ~
+CUSTOM INSTRUCTIONS *gp.nvim-custom-instructions*
By calling `:GpContext` you can make `.gp.md` markdown file in a root of a
repository. Commands such as `:GpRewrite`, `:GpAppend` etc. will respect
@@ -241,7 +456,7 @@ always listen to system commands). For example:
Here is another example .
-SCRIPTING AND MULTIFILE EDITS ~
+SCRIPTING *gp.nvim-scripting*
`GpDone` event + `.gp.md` custom instructions provide a possibility to run
gp.nvim using headless (neo)vim from terminal or shell script. So you can let
@@ -290,13 +505,14 @@ resulting `test` file:
<
-SHORTCUTS ~
+==============================================================================
+4. Shortcuts *gp.nvim-shortcuts*
There are no default global shortcuts to mess with your own config. Bellow are
examples for you to adjust or just use directly.
-NATIVE
+NATIVE *gp.nvim-native*
You can use the good old `vim.keymap.set` and paste the following after
`require("gp").setup(conf)` call (or anywhere you keep shortcuts if you want
@@ -383,7 +599,7 @@ them at one place).
<
-WHICHKEY
+WHICHKEY *gp.nvim-whichkey*
Or go more fancy by using which-key.nvim
plugin:
@@ -549,7 +765,8 @@ Or go more fancy by using which-key.nvim
<
-EXTEND FUNCTIONALITY *gp.nvim-extend-functionality*
+==============================================================================
+5. Extend functionality *gp.nvim-extend-functionality*
You can extend/override the plugin functionality with your own, by putting
functions into `config.hooks`. Hooks have access to everything (see
@@ -709,11 +926,6 @@ The raw plugin text editing method `Prompt` has seven aprameters:
- `whisper`
- optional string serving as a default for input prompt (for example generated from speech by Whisper)
-==============================================================================
-1. Links *gp.nvim-links*
-
-1. *image*: https://github.com/Robitx/gp.nvim/assets/8431097/350b38ce-52fb-4df7-b2a5-d6e51581f0c3
-
Generated by panvimdoc
vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/lua/gp/config.lua b/lua/gp/config.lua
index fe12e97..0caa00d 100644
--- a/lua/gp/config.lua
+++ b/lua/gp/config.lua
@@ -6,6 +6,11 @@
--------------------------------------------------------------------------------
local config = {
+ -- Please start with minimal config possible.
+ -- Just openai_api_key if you don't have OPENAI_API_KEY env set up.
+ -- Defaults change over time to improve things, options might get deprecated.
+ -- It's better to change only things where the default doesn't fit your needs.
+
-- required openai api key (string or table with command and arguments)
-- openai_api_key = { "cat", "path_to/openai_api_key" },
-- openai_api_key = { "bw", "get", "password", "OPENAI_API_KEY" },