Skip to content

Commit 3afd032

Browse files
deathbeampre-commit-ci[bot]
deathbeam
and
pre-commit-ci[bot]
authored
docs(readme): improve resource and tool usage docs (#1558)
* docs(readme): improve resource and tool usage docs - Add tip for using <Tab> 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 <Tab> 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 <slusnucky@gmail.com> * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Signed-off-by: Tomas Slusny <slusnucky@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent ee14248 commit 3afd032

1 file changed

Lines changed: 91 additions & 64 deletions

File tree

‎README.md‎

Lines changed: 91 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -97,32 +97,8 @@ EOF
9797
- **Models** (`$<model>`) - Specify which AI model to use for the chat
9898
- **Prompts** (`/PromptName`) - Use predefined prompt templates for common tasks
9999

100-
## Examples
101-
102-
```markdown
103-
# Add specific file to context
104-
105-
#file:src/main.lua
106-
107-
# Give LLM access to workspace tools
108-
109-
@copilot What files are in this project?
110-
111-
# Sticky prompt that persists
112-
113-
> #buffer:active
114-
> You are a helpful coding assistant
115-
```
116-
117-
When you use `@copilot`, the LLM can call functions from the `copilot` group such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`.
118-
119-
- By default, proposed tool calls wait for your approval.
120-
- You can configure `trusted_tools` to automatically run specific tools or groups.
121-
- Resources added with `#...` are resolved immediately and shared as context.
122-
- Tool call results are sent back to the model as plain output, while manual resources keep their `##<uri>` references in chat.
123-
124-
> [!WARNING]
125-
> `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.
100+
> [!TIP]
101+
> Press `<Tab>` after typing `#` or `@` to see available options and auto-complete. This is the easiest way to discover what's available!
126102
127103
# Usage
128104

@@ -144,54 +120,54 @@ When you use `@copilot`, the LLM can call functions from the `copilot` group suc
144120

145121
## Chat Key Mappings
146122

147-
| Insert | Normal | Action |
148-
| ------- | ------- | ----------------------------------------- |
149-
| `<Tab>` | - | Trigger/accept completion menu for tokens |
150-
| `<C-c>` | `q` | Close the chat window |
151-
| `<C-l>` | `<C-l>` | Reset and clear the chat window |
152-
| `<C-s>` | `<CR>` | Submit the current prompt |
153-
| `<C-y>` | `<C-y>` | Accept nearest diff |
154-
| - | `gj` | Jump to section of nearest diff |
155-
| - | `gqa` | Add all answers from chat to quickfix |
156-
| - | `gqd` | Add all diffs from chat to quickfix |
157-
| - | `gy` | Yank nearest diff to register |
158-
| - | `gd` | Show diff between source and nearest diff |
159-
| - | `gc` | Show info about current chat |
160-
| - | `gh` | Show help message |
161-
162-
> [!WARNING]
163-
> Some plugins (e.g. `copilot.vim`) may also map common keys like `<Tab>` in insert mode.
164-
> To avoid conflicts, disable Copilot's default `<Tab>` mapping with:
123+
| Insert | Normal | Action |
124+
| ------- | ------- | ---------------------------------------------------- |
125+
| `<Tab>` | - | **Autocomplete resources/files/options** (use this!) |
126+
| `<C-c>` | `q` | Close the chat window |
127+
| `<C-l>` | `<C-l>` | Reset and clear the chat window |
128+
| `<C-s>` | `<CR>` | Submit the current prompt |
129+
| `<C-y>` | `<C-y>` | Accept nearest diff |
130+
| - | `gj` | Jump to section of nearest diff |
131+
| - | `gqa` | Add all answers from chat to quickfix |
132+
| - | `gqd` | Add all diffs from chat to quickfix |
133+
| - | `gy` | Yank nearest diff to register |
134+
| - | `gd` | Show diff between source and nearest diff |
135+
| - | `gc` | Show info about current chat |
136+
| - | `gh` | Show help message |
137+
138+
**💡 Pro tip:** After typing `#`, `@`, `#buffer:`, or `#file:`, press `<Tab>` to see available options. This is the fastest way to work!
139+
140+
> [!NOTE]
141+
> **Tab key not working?** Some plugins (e.g. `copilot.vim`) also map `<Tab>` in insert mode.
142+
> To fix conflicts, disable the other plugin's `<Tab>` mapping:
165143
>
166144
> ```lua
145+
> -- For copilot.vim
167146
> vim.g.copilot_no_tab_map = true
168147
> vim.keymap.set('i', '<S-Tab>', 'copilot#Accept("\\<S-Tab>")', { expr = true, replace_keycodes = false })
169148
> ```
170149
>
171-
> You can also customize CopilotChat keymaps in your config.
150+
> Or customize CopilotChat keymaps in your config.
172151
173152
## Predefined Functions
174153
175154
All predefined functions belong to the `copilot` group.
176155
177-
| Function | Manual `#...` | Description | Example Usage |
178-
| ----------- | ------------- | ------------------------------------------------------ | -------------------- |
179-
| `bash` | No | Executes a bash command and returns output | `@copilot` |
180-
| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `#buffer:active` |
181-
| `clipboard` | Yes | Provides access to system clipboard content | `#clipboard` |
182-
| `edit` | No | Applies a unified diff to a file | `@copilot` |
183-
| `file` | Yes | Reads content from a specified file path | `#file:path/to/file` |
184-
| `gitdiff` | Yes | Retrieves git diff information | `#gitdiff:staged` |
185-
| `glob` | Yes | Lists filenames matching a pattern in workspace | `#glob:**/*.lua` |
186-
| `grep` | Yes | Searches for a pattern across files in workspace | `#grep:TODO` |
187-
| `selection` | Yes | Includes the current visual selection with diagnostics | `#selection` |
188-
| `url` | Yes | Fetches content from a specified URL | `#url:https://...` |
189-
190-
`#...` resolves a function immediately and adds its output as chat context.
191-
192-
`@copilot` shares the enabled functions with the model so it can choose when to call them.
193-
194-
Only `bash` and `edit` are tool-only. The rest can be used both as manual resources and as callable tools.
156+
| Function | Manual `#...` | Description | Available Options |
157+
| ----------- | ------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
158+
| `bash` | No | Executes a bash command and returns output | Tool-only (use `@copilot`) |
159+
| `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `active`, `visible`, `listed`, `quickfix`, buffer number, or filename |
160+
| `clipboard` | Yes | Provides access to system clipboard content | No options |
161+
| `edit` | No | Applies a unified diff to a file | Tool-only (use `@copilot`) |
162+
| `file` | Yes | Reads content from a specified file path | Any file path (use `<Tab>` for completion) |
163+
| `gitdiff` | Yes | Retrieves git diff information | `unstaged` (default), `staged`, or commit SHA |
164+
| `glob` | Yes | Lists filenames matching a pattern in workspace | Any glob pattern (default: `**/*`) |
165+
| `grep` | Yes | Searches for a pattern across files in workspace | Any search pattern |
166+
| `selection` | Yes | Includes the current visual selection with diagnostics | No options |
167+
| `url` | Yes | Fetches content from a specified URL | Any HTTPS URL |
168+
169+
- **`#<function>`** - Embeds output directly in your message (e.g., `#buffer:listed`, `#file:src/main.lua`)
170+
- **`@<function/group>`** - Makes function(s) available for LLM to call when needed (e.g., `@copilot`, `@file`)
195171
196172
## Predefined Prompts
197173
@@ -205,6 +181,55 @@ Only `bash` and `edit` are tool-only. The rest can be used both as manual resour
205181
| `Tests` | Generate tests for selected code |
206182
| `Commit` | Generate commit message with commitizen convention from staged changes |
207183
184+
## Resource Usage
185+
186+
```markdown
187+
# Current buffer
188+
189+
#buffer:active
190+
191+
# All open buffers (replaces old #buffers)
192+
193+
#buffer:listed
194+
195+
# All visible buffers
196+
197+
#buffer:visible
198+
199+
# Specific file
200+
201+
#file:src/main.lua
202+
203+
# Git changes
204+
205+
#gitdiff:staged
206+
207+
# URL content
208+
209+
#url:https://example.com/docs
210+
```
211+
212+
## Tool Usage
213+
214+
When you use `@copilot`, the LLM can call functions from the `copilot` group such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`.
215+
216+
```markdown
217+
# Give LLM access to workspace tools
218+
219+
@copilot What files are in this project?
220+
221+
# Sticky context with tools
222+
223+
> #buffer:listed
224+
> @copilot
225+
> Refactor the authentication code
226+
```
227+
228+
By default, tool calls require manual approval. Configure `trusted_tools` to automatically run specific tools (see [Functions](#functions)).
229+
230+
> [!WARNING]
231+
> `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.
232+
208233
# Configuration
209234

210235
For all available configuration options, see [`lua/CopilotChat/config.lua`](lua/CopilotChat/config.lua).
@@ -333,14 +358,16 @@ Use `trusted_tools` to control which tool calls are executed automatically:
333358
}
334359
```
335360

361+
**How tool trust works:**
362+
336363
A tool is trusted when any of these match:
337364

338365
- Its function definition sets `trusted = true`
339366
- Its function name appears in `trusted_tools`
340367
- Its function group appears in `trusted_tools`
341368
- `trusted_tools = true`
342369

343-
For most setups, trusting a few read-only functions such as `file`, `glob`, or `grep` is safer than trusting everything.
370+
**Recommended setup:** Trust read-only functions like `file`, `glob`, or `grep` for a smoother workflow without compromising safety.
344371

345372
> [!WARNING]
346373
> Trusted tools run without asking for confirmation. Be especially careful with tools like `bash` and `edit`, which can change your workspace.

0 commit comments

Comments
 (0)