You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/src/content/docs/learning-hub/agents-and-subagents.md
+16-1Lines changed: 16 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ title: 'Agents and Subagents'
3
3
description: 'Learn how delegated subagents differ from primary agents, when to use them, and how to launch them in VS Code and Copilot CLI.'
4
4
authors:
5
5
- GitHub Copilot Learning Hub Team
6
-
lastUpdated: 2026-05-04
6
+
lastUpdated: 2026-05-07
7
7
estimatedReadingTime: '9 minutes'
8
8
tags:
9
9
- agents
@@ -134,6 +134,21 @@ The important behavior is different from a single chat turn:
134
134
135
135
That makes `/fleet` a practical way to launch subagents even if you are not authoring custom agent files yourself.
136
136
137
+
### Rubber-duck agent (experimental)
138
+
139
+
Available in `/experimental` (v1.0.42+), the **rubber-duck agent** applies a novel multi-model pattern: when you're working in a GPT-powered session, the rubber-duck agent internally routes certain requests through Claude to provide a second perspective. The idea is similar to rubber-duck debugging — talking through a problem with a different "listener" often surfaces assumptions or blind spots you didn't notice.
140
+
141
+
To try it, enable experimental features and then select the rubber-duck agent from the agent picker:
142
+
143
+
```
144
+
/experimental # toggle experimental features
145
+
/agent # open the agent picker and select rubber-duck
146
+
```
147
+
148
+
Because it runs as a sub-agent layer rather than replacing your primary model, you keep your current session model and context while the rubber-duck analysis runs in the background.
149
+
150
+
> **Note**: This is an experimental feature and may change. Provide feedback via `/feedback` if you find it useful.
description: 'Learn how to configure GitHub Copilot at user, workspace, and repository levels to optimize your AI-assisted development experience.'
4
4
authors:
5
5
- GitHub Copilot Learning Hub Team
6
-
lastUpdated: 2026-05-05
6
+
lastUpdated: 2026-05-07
7
7
estimatedReadingTime: '10 minutes'
8
8
tags:
9
9
- configuration
@@ -408,6 +408,8 @@ These files follow the same format as `config.json` and are loaded after the glo
408
408
409
409
The model picker opens in a **full-screen view** with inline reasoning effort adjustment. Use the **← / →** arrow keys to change the reasoning effort level (`low`, `medium`, `high`) directly from the picker without leaving the session. The current reasoning effort level is also displayed in the model header (e.g., `claude-sonnet-4.6 (high)`) so you always know which level is active.
410
410
411
+
**Auto mode and server-side model routing** (v1.0.43+): When you select **Auto** as your model, the CLI uses server-side model routing for real-time model selection. Instead of locking in a single model at session start, Auto mode evaluates each request and routes it to the most appropriate model dynamically. This means straightforward questions can be handled by a faster model while complex reasoning tasks are automatically escalated — without you needing to switch models manually.
412
+
411
413
### CLI Session Commands
412
414
413
415
GitHub Copilot CLI has two commands for managing session state, with distinct behaviours:
@@ -527,12 +529,14 @@ The `/compact` command summarizes the conversation history to free up context wi
527
529
528
530
> **ACP sessions (v1.0.39+)**: The `/compact`, `/context`, `/usage`, and `/env` commands are now available in ACP (Agent Coordination Protocol) sessions, allowing remote ACP clients to surface session details and manage context from within their own automated workflows.
529
531
530
-
The `/statusline` command (with `/footer` as an alias) lets you control which items appear in the terminal status bar. You can show or hide individual indicators like the working directory, current branch, effort level, context window usage, and quota. The **changes** toggle shows a running count of added/removed lines for the session — useful when tracking the scope of an ongoing edit:
532
+
The `/statusline` command (with `/footer` as an alias) lets you control which items appear in the terminal status bar. You can show or hide individual indicators like the working directory, current branch, effort level, context window usage, quota, and **active account username** (v1.0.43+). The **changes** toggle shows a running count of added/removed lines for the session — useful when tracking the scope of an ongoing edit:
531
533
532
534
```
533
535
/statusline # show the statusline configuration menu
534
536
```
535
537
538
+
Toggle the **username** indicator to display which GitHub account is currently active in the footer — helpful when you work with multiple accounts or switch between personal and organization contexts.
539
+
536
540
The `/keep-alive` command prevents the system from sleeping while Copilot CLI is active. This is useful during long-running agent sessions on laptops or machines with aggressive sleep settings:
537
541
538
542
```
@@ -563,6 +567,13 @@ Accepted values are `low`, `medium`, and `high`. You can also set a default via
563
567
564
568
### CLI Startup Flags
565
569
570
+
The `-C <directory>` flag changes the working directory before starting, similar to `git -C` (v1.0.42+). This is useful for scripts or aliases that need to start Copilot CLI in a specific project directory without a separate `cd`:
571
+
572
+
```bash
573
+
copilot -C ~/projects/my-repo # start in a different directory
574
+
copilot -C ~/projects/my-repo -p "..."# combine with prompt mode
575
+
```
576
+
566
577
The `--mode` flag (along with its aliases `--autopilot` and `--plan`) lets you launch the CLI directly in a specific agent mode without waiting for the interactive session to start:
description: 'Learn how Model Context Protocol servers extend GitHub Copilot with access to external tools, databases, and APIs.'
4
4
authors:
5
5
- GitHub Copilot Learning Hub Team
6
-
lastUpdated: 2026-05-01
6
+
lastUpdated: 2026-05-07
7
7
estimatedReadingTime: '8 minutes'
8
8
tags:
9
9
- mcp
@@ -261,13 +261,43 @@ If your team has internal tools or proprietary APIs, you can build custom MCP se
261
261
262
262
MCP server SDKs are available in [Python](https://github.com/modelcontextprotocol/python-sdk), [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk), and other languages. Browse the [Agents Directory](../../agents/) for examples of agents built around MCP server expertise.
263
263
264
+
## Troubleshooting MCP Connection Issues
265
+
266
+
When an MCP server fails to start or loses its connection, Copilot CLI surfaces a warning with actionable details to help you diagnose the problem quickly.
267
+
268
+
**Failure warnings include stderr output** (v1.0.42+): If your MCP server prints error messages to stderr (e.g., missing environment variables, connection refused, import errors), those messages are now included directly in the CLI warning. This means you usually see the root cause without needing to run the server manually.
269
+
270
+
For example, a PostgreSQL server that can't connect because `DATABASE_URL` is not set will show:
271
+
272
+
```
273
+
⚠ MCP server "postgres" failed to start
274
+
Error: connect ECONNREFUSED 127.0.0.1:5432
275
+
stderr: Error: DATABASE_URL environment variable is required
276
+
```
277
+
278
+
**Diagnosing connection problems with `/mcp show`**: Run `/mcp show` to see the current status of all configured MCP servers — which ones are running, which have failed, and their connection details. When an MCP server name contains whitespace, the failure warning also suggests a directly runnable `/mcp show <name>` command for quick inspection.
279
+
280
+
```
281
+
/mcp show # list all servers and their status
282
+
/mcp show postgres # inspect a specific server
283
+
```
284
+
285
+
**Common causes and fixes**:
286
+
287
+
| Symptom | Likely Cause | Fix |
288
+
|---------|--------------|-----|
289
+
|`ENOENT` on startup | Missing `npx` / `python` / command | Verify the executable is installed and in your PATH |
290
+
| Auth errors / 401 | Expired or missing API key | Update the `env` field in your config; check `/mcp auth`|
291
+
| Server starts then exits | Server crash | Check stderr output in the warning for the root cause |
292
+
| Server blocked | Organization policy | Contact your admin; switch to an approved server |
293
+
264
294
## Best Practices
265
295
266
296
-**Principle of least privilege**: Only give MCP servers the minimum access they need. Use read-only database connections for analysis agents.
267
297
-**Keep secrets out of config files**: Use `${input:variableName}` for API keys and connection strings, or load from environment variables.
268
298
-**Document your servers**: Add comments or a README explaining which MCP servers your project uses and why.
269
299
-**Version control carefully**: Commit `.mcp.json` or `.vscode/mcp.json` for shared server configurations, but use `.gitignore` for any files containing credentials.
270
-
-**Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows.
300
+
-**Test server connectivity**: Verify MCP servers start correctly before relying on them in agent workflows. Use `/mcp show` to check status and read stderr output in any failure warnings.
271
301
-**Use the MCP allowlist (experimental)**: In high-security environments, the `MCP_ALLOWLIST` feature flag lets you validate MCP servers against a configured registry, blocking unrecognized servers from loading. MCP servers that are blocked by the allowlist policy are **hidden from `/mcp show`** to avoid confusion — only permitted servers appear in that view. This is an experimental feature for enterprise environments requiring strict control over which MCP servers are permitted.
272
302
273
303
### Organization Policy for Third-Party MCP Servers
0 commit comments