diff --git a/docs/cli/model-steering.md b/docs/cli/model-steering.md new file mode 100644 index 0000000000..6081209f22 --- /dev/null +++ b/docs/cli/model-steering.md @@ -0,0 +1,79 @@ +# Model steering (experimental) + +Model steering lets you provide real-time guidance and feedback to Gemini CLI +while it is actively executing a task. This allows you to correct course, add +missing context, or skip unnecessary steps without having to stop and restart +the agent. + +> **Note:** This is a preview feature currently under active development. It is +> only available on the preview channel. + +Model steering is particularly useful during complex [Plan Mode](./plan-mode.md) +workflows or long-running subagent executions where you want to ensure the agent +stays on the right track. + +## Enabling model steering + +Model steering is an experimental feature and is disabled by default. You can +enable it using the `/settings` command or by updating your `settings.json` +file. + +1. Type `/settings` in the Gemini CLI. +2. Search for **Model Steering**. +3. Set the value to **true**. + +Alternatively, add the following to your `settings.json`: + +```json +{ + "experimental": { + "modelSteering": true + } +} +``` + +## Using model steering + +When model steering is enabled, Gemini CLI treats any text you type while the +agent is working as a steering hint. + +1. Start a task (for example, "Refactor the database service"). +2. While the agent is working (the spinner is visible), type your feedback in + the input box. +3. Press **Enter**. + +Gemini CLI acknowledges your hint with a brief message and injects it directly +into the model's context for the very next turn. The model then re-evaluates its +current plan and adjusts its actions accordingly. + +### Common use cases + +You can use steering hints to guide the model in several ways: + +- **Correcting a path:** "Actually, the utilities are in `src/common/utils`." +- **Skipping a step:** "Skip the unit tests for now and just focus on the + implementation." +- **Adding context:** "The `User` type is defined in `packages/core/types.ts`." +- **Redirecting the effort:** "Stop searching the codebase and start drafting + the plan now." +- **Handling ambiguity:** "Use the existing `Logger` class instead of creating a + new one." + +## How it works + +When you submit a steering hint, Gemini CLI performs the following actions: + +1. **Immediate acknowledgement:** It uses a small, fast model to generate a + one-sentence acknowledgment so you know your hint was received. +2. **Context injection:** It prepends an internal instruction to your hint that + tells the main agent to: + - Re-evaluate the active plan. + - Classify the update (for example, as a new task or extra context). + - Apply minimal-diff changes to affected tasks. +3. **Real-time update:** The hint is delivered to the agent at the beginning of + its next turn, ensuring the most immediate course correction possible. + +## Next steps + +- Tackle complex tasks with [Plan Mode](./plan-mode.md). +- Build custom [Agent Skills](./skills.md). diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md index a8511d9c42..f2cd567d5a 100644 --- a/docs/cli/plan-mode.md +++ b/docs/cli/plan-mode.md @@ -107,7 +107,9 @@ structure, and consultation level are proportional to the task's complexity: 4. **Review & Approval:** Use the [`exit_plan_mode`] tool to present the plan and formally request approval. - **Approve:** Exit Plan Mode and start implementation. - - **Iterate:** Provide feedback to refine the plan. + - **Iterate:** Provide feedback to refine the plan. You can also use + [**model steering**](./model-steering.md) to provide real-time feedback + while Gemini CLI is researching or drafting the plan. - **Refine manually:** Press **Ctrl + X** to open the plan file in your [preferred external editor]. This allows you to manually refine the plan steps before approval. If you make any changes and save the file, the CLI diff --git a/docs/sidebar.json b/docs/sidebar.json index c2c6295bfa..4955710404 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -99,6 +99,11 @@ { "label": "MCP servers", "slug": "docs/tools/mcp-server" }, { "label": "Model routing", "slug": "docs/cli/model-routing" }, { "label": "Model selection", "slug": "docs/cli/model" }, + { + "label": "Model steering", + "badge": "🔬", + "slug": "docs/cli/model-steering" + }, { "label": "Plan mode", "badge": "🔬", "slug": "docs/cli/plan-mode" }, { "label": "Subagents",