From 30dd2f1dfebc8b9ac1f4726807be5482909532fb Mon Sep 17 00:00:00 2001
From: Tommaso Sciortino <sciortino@gmail.com>
Date: Wed, 22 Oct 2025 13:27:10 -0700
Subject: [PATCH] Document todo tool (#11695)

---
 docs/cli/keyboard-shortcuts.md    |  1 +
 docs/get-started/configuration.md | 12 +++++++
 docs/index.md                     |  1 +
 docs/sidebar.json                 |  4 +++
 docs/tools/index.md               |  2 ++
 docs/tools/todos.md               | 56 +++++++++++++++++++++++++++++++
 6 files changed, 76 insertions(+)
 create mode 100644 docs/tools/todos.md

diff --git a/docs/cli/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md
index e52f373bb9..2e7a86c022 100644
--- a/docs/cli/keyboard-shortcuts.md
+++ b/docs/cli/keyboard-shortcuts.md
@@ -12,6 +12,7 @@ This document lists the available keyboard shortcuts in the Gemini CLI.
 | `Ctrl+L` | Clear the screen.                                                                                                     |
 | `Ctrl+O` | Toggle the display of the debug console.                                                                              |
 | `Ctrl+S` | Allows long responses to print fully, disabling truncation. Use your terminal's scrollback to view the entire output. |
+| `Ctrl+T` | Toggle the display of the todo list.                                                                                  |
 | `Ctrl+Y` | Toggle auto-approval (YOLO mode) for all tool calls.                                                                  |
 
 ## Input Prompt
diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index 45353b9034..6b7cabc331 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -401,6 +401,18 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** A denylist of MCP servers to exclude.
   - **Default:** `undefined`
 
+#### `useSmartEdit`
+
+- **`useSmartEdit`** (boolean):
+  - **Description:** Enable the smart-edit tool instead of the replace tool.
+  - **Default:** `true`
+
+#### `useWriteTodos`
+
+- **`useWriteTodos`** (boolean):
+  - **Description:** Enable the write_todos tool.
+  - **Default:** `false`
+
 #### `security`
 
 - **`security.folderTrust.enabled`** (boolean):
diff --git a/docs/index.md b/docs/index.md
index 55b2267ad1..808dd9e7ee 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -68,6 +68,7 @@ This documentation is organized into the following sections:
   `google_web_search` tool.
 - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory`
   tool.
+- **[Todo Tool](./tools/todos.md):** Documentation for the `write_todos` tool.
 
 ### Extensions
 
diff --git a/docs/sidebar.json b/docs/sidebar.json
index ef76affe22..80e2494e4b 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -146,6 +146,10 @@
         "label": "Memory",
         "slug": "docs/tools/memory"
       },
+      {
+        "label": "Todos",
+        "slug": "docs/tools/todos"
+      },
       {
         "label": "MCP Servers",
         "slug": "docs/tools/mcp-server"
diff --git a/docs/tools/index.md b/docs/tools/index.md
index a9fd61b748..421ce24bb7 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -86,6 +86,8 @@ Gemini CLI's built-in tools can be broadly categorized as follows:
   tool for reading content from multiple files or directories.
 - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
   information across sessions.
+- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
+  requests.
 
 Additionally, these tools incorporate:
 
diff --git a/docs/tools/todos.md b/docs/tools/todos.md
new file mode 100644
index 0000000000..b345094412
--- /dev/null
+++ b/docs/tools/todos.md
@@ -0,0 +1,56 @@
+# Todo Tool (`write_todos`)
+
+This document describes the `write_todos` tool for the Gemini CLI.
+
+## Description
+
+The `write_todos` tool allows the Gemini agent to create and manage a list of
+subtasks for complex user requests. This provides you, the user, with greater
+visibility into the agent's plan and its current progress.
+
+### Arguments
+
+`write_todos` takes one argument:
+
+- `todos` (array of objects, required): The complete list of todo items. This
+  replaces the existing list. Each item includes:
+  - `description` (string): The task description.
+  - `status` (string): The current status (`pending`, `in_progress`,
+    `completed`, or `cancelled`).
+
+## Behavior
+
+The agent uses this tool to break down complex multi-step requests into a clear
+plan.
+
+- **Progress Tracking:** The agent updates this list as it works, marking tasks
+  as `completed` when done.
+- **Single Focus:** Only one task will be marked `in_progress` at a time,
+  indicating exactly what the agent is currently working on.
+- **Dynamic Updates:** The plan may evolve as the agent discovers new
+  information, leading to new tasks being added or unnecessary ones being
+  cancelled.
+
+When active, the current `in_progress` task is displayed above the input box,
+keeping you informed of the immediate action. You can toggle the full view of
+the todo list at any time by pressing `Ctrl+T`.
+
+Usage example (internal representation):
+
+```javascript
+write_todos({
+  todos: [
+    { description: 'Initialize new React project', status: 'completed' },
+    { description: 'Implement state management', status: 'in_progress' },
+    { description: 'Create API service', status: 'pending' },
+  ],
+});
+```
+
+## Important notes
+
+- **Enabling:** This tool is disabled by default. To use it, you must enable it
+  in your `settings.json` file by setting `"useWriteTodos": true`.
+
+- **Intended Use:** This tool is primarily used by the agent for complex,
+  multi-turn tasks. It is generally not used for simple, single-turn questions.