From 3da1563c30bc6f201e501d90a584294cf2b854c6 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 11 Mar 2026 17:05:59 -0700 Subject: [PATCH] Docs: Add documentation for model steering (experimental). (#21154) --- docs/cli/model-steering.md | 79 +++++++++++++++++++++ docs/cli/tutorials/plan-mode-steering.md | 89 ++++++++++++++++++++++++ docs/sidebar.json | 10 +++ 3 files changed, 178 insertions(+) create mode 100644 docs/cli/model-steering.md create mode 100644 docs/cli/tutorials/plan-mode-steering.md diff --git a/docs/cli/model-steering.md b/docs/cli/model-steering.md new file mode 100644 index 0000000000..12b581c530 --- /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 lets you correct course, add missing +context, or skip unnecessary steps without having to stop and restart the agent. + +> **Note:** This is a preview feature under active development. Preview features +> may only be available in the **Preview** channel or may need to be enabled +> under `/settings`. + +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 acknowledgment:** 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/tutorials/plan-mode-steering.md b/docs/cli/tutorials/plan-mode-steering.md new file mode 100644 index 0000000000..86bc63edac --- /dev/null +++ b/docs/cli/tutorials/plan-mode-steering.md @@ -0,0 +1,89 @@ +# Use Plan Mode with model steering for complex tasks + +Architecting a complex solution requires precision. By combining Plan Mode's +structured environment with model steering's real-time feedback, you can guide +Gemini CLI through the research and design phases to ensure the final +implementation plan is exactly what you need. + +> **Note:** This is a preview feature under active development. Preview features +> may only be available in the **Preview** channel or may need to be enabled +> under `/settings`. + +## Prerequisites + +- Gemini CLI installed and authenticated. +- [Plan Mode](../plan-mode.md) enabled in your settings. +- [Model steering](../model-steering.md) enabled in your settings. + +## Why combine Plan Mode and model steering? + +[Plan Mode](../plan-mode.md) typically follows a linear path: research, propose, +and draft. Adding model steering lets you: + +1. **Direct the research:** Correct the agent if it's looking in the wrong + directory or missing a key dependency. +2. **Iterate mid-draft:** Suggest a different architectural pattern while the + agent is still writing the plan. +3. **Speed up the loop:** Avoid waiting for a full research turn to finish + before providing critical context. + +## Step 1: Start a complex task + +Enter Plan Mode and start a task that requires research. + +**Prompt:** `/plan I want to implement a new notification service using Redis.` + +Gemini CLI enters Plan Mode and starts researching your existing codebase to +identify where the new service should live. + +## Step 2: Steer the research phase + +As you see the agent calling tools like `list_directory` or `grep_search`, you +might realize it's missing the relevant context. + +**Action:** While the spinner is active, type your hint: +`"Don't forget to check packages/common/queues for the existing Redis config."` + +**Result:** Gemini CLI acknowledges your hint and immediately incorporates it +into its research. You'll see it start exploring the directory you suggested in +its very next turn. + +## Step 3: Refine the design mid-turn + +After research, the agent starts drafting the implementation plan. If you notice +it's proposing a design that doesn't align with your goals, steer it. + +**Action:** Type: +`"Actually, let's use a Publisher/Subscriber pattern instead of a simple queue for this service."` + +**Result:** The agent stops drafting the current version of the plan, +re-evaluates the design based on your feedback, and starts a new draft that uses +the Pub/Sub pattern. + +## Step 4: Approve and implement + +Once the agent has used your hints to craft the perfect plan, review the final +`.md` file. + +**Action:** Type: `"Looks perfect. Let's start the implementation."` + +Gemini CLI exits Plan Mode and transitions to the implementation phase. Because +the plan was refined in real-time with your feedback, the agent can now execute +each step with higher confidence and fewer errors. + +## Tips for effective steering + +- **Be specific:** Instead of "do it differently," try "use the existing + `Logger` class in `src/utils`." +- **Steer early:** Providing feedback during the research phase is more + efficient than waiting for the final plan to be drafted. +- **Use for context:** Steering is a great way to provide knowledge that might + not be obvious from reading the code (e.g., "We are planning to deprecate this + module next month"). + +## Next steps + +- Explore [Agent Skills](../skills.md) to add specialized expertise to your + planning turns. +- See the [Model steering reference](../model-steering.md) for technical + details. diff --git a/docs/sidebar.json b/docs/sidebar.json index e26004a973..6cac5ec9fd 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -47,6 +47,11 @@ "label": "Plan tasks with todos", "slug": "docs/cli/tutorials/task-planning" }, + { + "label": "Use Plan Mode with model steering", + "badge": "🔬", + "slug": "docs/cli/tutorials/plan-mode-steering" + }, { "label": "Web search and fetch", "slug": "docs/cli/tutorials/web-tools" @@ -106,6 +111,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": "Notifications", "badge": "🔬",