From ba7e602d2475ab3e6791c7837617418a88edeed8 Mon Sep 17 00:00:00 2001 From: Tomas Slusny Date: Thu, 16 Apr 2026 19:37:54 +0200 Subject: [PATCH 1/2] docs(readme): improve resource and tool usage docs - Add tip for using to autocomplete resources and options - Clarify and expand resource examples for buffer, file, gitdiff, and url - Add section on tool usage with markdown examples - Update key mappings table and add pro tip for usage - Clarify tool trust configuration and recommend safe defaults - Improve descriptions and available options for predefined functions - General rewording and formatting for clarity and usability Closes #1530 Closes #1488 Signed-off-by: Tomas Slusny --- README.md | 148 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 83 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index b37e2cfe..0bb6b899 100644 --- a/README.md +++ b/README.md @@ -97,32 +97,8 @@ EOF - **Models** (`$`) - Specify which AI model to use for the chat - **Prompts** (`/PromptName`) - Use predefined prompt templates for common tasks -## Examples - -```markdown -# Add specific file to context - -#file:src/main.lua - -# Give LLM access to workspace tools - -@copilot What files are in this project? - -# Sticky prompt that persists - -> #buffer:active -> You are a helpful coding assistant -``` - -When you use `@copilot`, the LLM can call functions from the `copilot` group such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`. - -- By default, proposed tool calls wait for your approval. -- You can configure `trusted_tools` to automatically run specific tools or groups. -- Resources added with `#...` are resolved immediately and shared as context. -- Tool call results are sent back to the model as plain output, while manual resources keep their `##` references in chat. - -> [!WARNING] -> `trusted_tools = true` allows the model to run every enabled tool without asking. Only use it if you fully trust the tool set and workspace. +> [!TIP] +> Press `` after typing `#` or `@` to see available options and auto-complete. This is the easiest way to discover what's available! # Usage @@ -144,54 +120,54 @@ When you use `@copilot`, the LLM can call functions from the `copilot` group suc ## Chat Key Mappings -| Insert | Normal | Action | -| ------- | ------- | ----------------------------------------- | -| `` | - | Trigger/accept completion menu for tokens | -| `` | `q` | Close the chat window | -| `` | `` | Reset and clear the chat window | -| `` | `` | Submit the current prompt | -| `` | `` | Accept nearest diff | -| - | `gj` | Jump to section of nearest diff | -| - | `gqa` | Add all answers from chat to quickfix | -| - | `gqd` | Add all diffs from chat to quickfix | -| - | `gy` | Yank nearest diff to register | -| - | `gd` | Show diff between source and nearest diff | -| - | `gc` | Show info about current chat | -| - | `gh` | Show help message | - -> [!WARNING] -> Some plugins (e.g. `copilot.vim`) may also map common keys like `` in insert mode. -> To avoid conflicts, disable Copilot's default `` mapping with: +| Insert | Normal | Action | +| ------- | ------- | --------------------------------------------------- | +| `` | - | **Autocomplete resources/files/options** (use this!) | +| `` | `q` | Close the chat window | +| `` | `` | Reset and clear the chat window | +| `` | `` | Submit the current prompt | +| `` | `` | Accept nearest diff | +| - | `gj` | Jump to section of nearest diff | +| - | `gqa` | Add all answers from chat to quickfix | +| - | `gqd` | Add all diffs from chat to quickfix | +| - | `gy` | Yank nearest diff to register | +| - | `gd` | Show diff between source and nearest diff | +| - | `gc` | Show info about current chat | +| - | `gh` | Show help message | + +**💡 Pro tip:** After typing `#`, `@`, `#buffer:`, or `#file:`, press `` to see available options. This is the fastest way to work! + +> [!NOTE] +> **Tab key not working?** Some plugins (e.g. `copilot.vim`) also map `` in insert mode. +> To fix conflicts, disable the other plugin's `` mapping: > > ```lua +> -- For copilot.vim > vim.g.copilot_no_tab_map = true > vim.keymap.set('i', '', 'copilot#Accept("\\")', { expr = true, replace_keycodes = false }) > ``` > -> You can also customize CopilotChat keymaps in your config. +> Or customize CopilotChat keymaps in your config. ## Predefined Functions All predefined functions belong to the `copilot` group. -| Function | Manual `#...` | Description | Example Usage | -| ----------- | ------------- | ------------------------------------------------------ | -------------------- | -| `bash` | No | Executes a bash command and returns output | `@copilot` | -| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `#buffer:active` | -| `clipboard` | Yes | Provides access to system clipboard content | `#clipboard` | -| `edit` | No | Applies a unified diff to a file | `@copilot` | -| `file` | Yes | Reads content from a specified file path | `#file:path/to/file` | -| `gitdiff` | Yes | Retrieves git diff information | `#gitdiff:staged` | -| `glob` | Yes | Lists filenames matching a pattern in workspace | `#glob:**/*.lua` | -| `grep` | Yes | Searches for a pattern across files in workspace | `#grep:TODO` | -| `selection` | Yes | Includes the current visual selection with diagnostics | `#selection` | -| `url` | Yes | Fetches content from a specified URL | `#url:https://...` | - -`#...` resolves a function immediately and adds its output as chat context. - -`@copilot` shares the enabled functions with the model so it can choose when to call them. - -Only `bash` and `edit` are tool-only. The rest can be used both as manual resources and as callable tools. +| Function | Manual `#...` | Description | Available Options | +| ----------- | ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | +| `bash` | No | Executes a bash command and returns output | Tool-only (use `@copilot`) | +| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `active`, `visible`, `listed`, `quickfix`, buffer number, or filename | +| `clipboard` | Yes | Provides access to system clipboard content | No options | +| `edit` | No | Applies a unified diff to a file | Tool-only (use `@copilot`) | +| `file` | Yes | Reads content from a specified file path | Any file path (use `` for completion) | +| `gitdiff` | Yes | Retrieves git diff information | `unstaged` (default), `staged`, or commit SHA | +| `glob` | Yes | Lists filenames matching a pattern in workspace | Any glob pattern (default: `**/*`) | +| `grep` | Yes | Searches for a pattern across files in workspace | Any search pattern | +| `selection` | Yes | Includes the current visual selection with diagnostics | No options | +| `url` | Yes | Fetches content from a specified URL | Any HTTPS URL | + +- **`#`** - Embeds output directly in your message (e.g., `#buffer:listed`, `#file:src/main.lua`) +- **`@`** - Makes function(s) available for LLM to call when needed (e.g., `@copilot`, `@file`) ## Predefined Prompts @@ -205,6 +181,47 @@ Only `bash` and `edit` are tool-only. The rest can be used both as manual resour | `Tests` | Generate tests for selected code | | `Commit` | Generate commit message with commitizen convention from staged changes | +## Resource Usage + +```markdown +# Current buffer +#buffer:active + +# All open buffers (replaces old #buffers) +#buffer:listed + +# All visible buffers +#buffer:visible + +# Specific file +#file:src/main.lua + +# Git changes +#gitdiff:staged + +# URL content +#url:https://example.com/docs +``` + +## Tool Usage + +When you use `@copilot`, the LLM can call functions from the `copilot` group such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`. + +```markdown +# Give LLM access to workspace tools +@copilot What files are in this project? + +# Sticky context with tools +> #buffer:listed +> @copilot +Refactor the authentication code +``` + +By default, tool calls require manual approval. Configure `trusted_tools` to automatically run specific tools (see [Functions](#functions)). + +> [!WARNING] +> `trusted_tools = true` allows the model to run every enabled tool without asking. Only use it if you fully trust the tool set and workspace. + # Configuration For all available configuration options, see [`lua/CopilotChat/config.lua`](lua/CopilotChat/config.lua). @@ -333,14 +350,15 @@ Use `trusted_tools` to control which tool calls are executed automatically: } ``` -A tool is trusted when any of these match: +**How tool trust works:** +A tool is trusted when any of these match: - Its function definition sets `trusted = true` - Its function name appears in `trusted_tools` - Its function group appears in `trusted_tools` - `trusted_tools = true` -For most setups, trusting a few read-only functions such as `file`, `glob`, or `grep` is safer than trusting everything. +**Recommended setup:** Trust read-only functions like `file`, `glob`, or `grep` for a smoother workflow without compromising safety. > [!WARNING] > Trusted tools run without asking for confirmation. Be especially careful with tools like `bash` and `edit`, which can change your workspace. From 6254ec72c55b073d98fddbb275dcf4f5b289ccde Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 17:41:50 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 61 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 0bb6b899..346a87f6 100644 --- a/README.md +++ b/README.md @@ -120,20 +120,20 @@ EOF ## Chat Key Mappings -| Insert | Normal | Action | -| ------- | ------- | --------------------------------------------------- | +| Insert | Normal | Action | +| ------- | ------- | ---------------------------------------------------- | | `` | - | **Autocomplete resources/files/options** (use this!) | -| `` | `q` | Close the chat window | -| `` | `` | Reset and clear the chat window | -| `` | `` | Submit the current prompt | -| `` | `` | Accept nearest diff | -| - | `gj` | Jump to section of nearest diff | -| - | `gqa` | Add all answers from chat to quickfix | -| - | `gqd` | Add all diffs from chat to quickfix | -| - | `gy` | Yank nearest diff to register | -| - | `gd` | Show diff between source and nearest diff | -| - | `gc` | Show info about current chat | -| - | `gh` | Show help message | +| `` | `q` | Close the chat window | +| `` | `` | Reset and clear the chat window | +| `` | `` | Submit the current prompt | +| `` | `` | Accept nearest diff | +| - | `gj` | Jump to section of nearest diff | +| - | `gqa` | Add all answers from chat to quickfix | +| - | `gqd` | Add all diffs from chat to quickfix | +| - | `gy` | Yank nearest diff to register | +| - | `gd` | Show diff between source and nearest diff | +| - | `gc` | Show info about current chat | +| - | `gh` | Show help message | **💡 Pro tip:** After typing `#`, `@`, `#buffer:`, or `#file:`, press `` to see available options. This is the fastest way to work! @@ -153,18 +153,18 @@ EOF All predefined functions belong to the `copilot` group. -| Function | Manual `#...` | Description | Available Options | -| ----------- | ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | -| `bash` | No | Executes a bash command and returns output | Tool-only (use `@copilot`) | -| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `active`, `visible`, `listed`, `quickfix`, buffer number, or filename | -| `clipboard` | Yes | Provides access to system clipboard content | No options | -| `edit` | No | Applies a unified diff to a file | Tool-only (use `@copilot`) | -| `file` | Yes | Reads content from a specified file path | Any file path (use `` for completion) | -| `gitdiff` | Yes | Retrieves git diff information | `unstaged` (default), `staged`, or commit SHA | -| `glob` | Yes | Lists filenames matching a pattern in workspace | Any glob pattern (default: `**/*`) | -| `grep` | Yes | Searches for a pattern across files in workspace | Any search pattern | -| `selection` | Yes | Includes the current visual selection with diagnostics | No options | -| `url` | Yes | Fetches content from a specified URL | Any HTTPS URL | +| Function | Manual `#...` | Description | Available Options | +| ----------- | ------------- | ------------------------------------------------------ | --------------------------------------------------------------------- | +| `bash` | No | Executes a bash command and returns output | Tool-only (use `@copilot`) | +| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `active`, `visible`, `listed`, `quickfix`, buffer number, or filename | +| `clipboard` | Yes | Provides access to system clipboard content | No options | +| `edit` | No | Applies a unified diff to a file | Tool-only (use `@copilot`) | +| `file` | Yes | Reads content from a specified file path | Any file path (use `` for completion) | +| `gitdiff` | Yes | Retrieves git diff information | `unstaged` (default), `staged`, or commit SHA | +| `glob` | Yes | Lists filenames matching a pattern in workspace | Any glob pattern (default: `**/*`) | +| `grep` | Yes | Searches for a pattern across files in workspace | Any search pattern | +| `selection` | Yes | Includes the current visual selection with diagnostics | No options | +| `url` | Yes | Fetches content from a specified URL | Any HTTPS URL | - **`#`** - Embeds output directly in your message (e.g., `#buffer:listed`, `#file:src/main.lua`) - **`@`** - Makes function(s) available for LLM to call when needed (e.g., `@copilot`, `@file`) @@ -185,21 +185,27 @@ All predefined functions belong to the `copilot` group. ```markdown # Current buffer + #buffer:active # All open buffers (replaces old #buffers) + #buffer:listed # All visible buffers + #buffer:visible # Specific file + #file:src/main.lua # Git changes + #gitdiff:staged # URL content + #url:https://example.com/docs ``` @@ -209,12 +215,14 @@ When you use `@copilot`, the LLM can call functions from the `copilot` group suc ```markdown # Give LLM access to workspace tools + @copilot What files are in this project? # Sticky context with tools + > #buffer:listed > @copilot -Refactor the authentication code +> Refactor the authentication code ``` By default, tool calls require manual approval. Configure `trusted_tools` to automatically run specific tools (see [Functions](#functions)). @@ -353,6 +361,7 @@ Use `trusted_tools` to control which tool calls are executed automatically: **How tool trust works:** A tool is trusted when any of these match: + - Its function definition sets `trusted = true` - Its function name appears in `trusted_tools` - Its function group appears in `trusted_tools`