From 89580b9bfcfc2b4a5da1912f8bb7b00cd241b4bb Mon Sep 17 00:00:00 2001 From: Anjali Sridhar Date: Thu, 2 Apr 2026 11:37:47 -0700 Subject: [PATCH 1/2] docs: add experimental task tracker docs --- docs/reference/tools.md | 15 ++++++++++ docs/tools/tracker.md | 61 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 docs/tools/tracker.md diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 91c626fa690..0a768a2198b 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -92,6 +92,21 @@ each tool. | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog. | | [`write_todos`](../tools/todos.md) | `Other` | Maintains an internal list of subtasks. The model uses this to track its own progress. | +### Task Tracker (Experimental) + + +> [!NOTE] +> This is an experimental feature currently under active development. Enable via `experimental.taskTracker`. + +| Tool | Kind | Description | +| :---------------------------------------------- | :------ | :-------------------------------------------------------------------------- | +| [`tracker_create_task`](../tools/tracker.md) | `Other` | Creates a new task in the persistent tracker. | +| [`tracker_update_task`](../tools/tracker.md) | `Other` | Updates an existing task's status, description, or dependencies. | +| [`tracker_get_task`](../tools/tracker.md) | `Other` | Retrieves the full details of a specific task. | +| [`tracker_list_tasks`](../tools/tracker.md) | `Other` | Lists tasks in the tracker, optionally filtered by status, type, or parent. | +| [`tracker_add_dependency`](../tools/tracker.md) | `Other` | Adds a dependency between two tasks, ensuring topological execution. | +| [`tracker_visualize`](../tools/tracker.md) | `Other` | Renders an ASCII tree visualization of the current task graph. | + ### Memory | Tool | Kind | Description | diff --git a/docs/tools/tracker.md b/docs/tools/tracker.md new file mode 100644 index 00000000000..b35712cb293 --- /dev/null +++ b/docs/tools/tracker.md @@ -0,0 +1,61 @@ +# Tracker tools (`tracker_*`) + + +> [!NOTE] +> This is an experimental feature currently under active development. + +The `tracker_*` tools allow the Gemini agent to maintain an internal, persistent +graph of tasks and dependencies for multi-step requests. This suite of tools +provides a more robust and granular way to manage execution plans than the +legacy `write_todos` tool. + +## Technical reference + +The agent uses these tools to manage its execution plan, decompose complex goals +into actionable sub-tasks, and provide real-time progress updates to the CLI +interface. The task state persists across sessions in the `.tracker/tasks/` +directory, allowing you to resume long-running projects or verify progress +incrementally. + +### Available Tools + +- `tracker_create_task`: Creates a new task in the tracker. You can specify a + title, description, and task type (`epic`, `task`, `bug`). +- `tracker_update_task`: Updates an existing task's status (`open`, + `in_progress`, `blocked`, `closed`), description, or dependencies. +- `tracker_get_task`: Retrieves the full details of a specific task by its + 6-character hex ID. +- `tracker_list_tasks`: Lists tasks in the tracker, optionally filtered by + status, type, or parent ID. +- `tracker_add_dependency`: Adds a dependency between two tasks, ensuring + topological execution. +- `tracker_visualize`: Renders an ASCII tree visualization of the current task + graph. + +## Technical behavior + +- **Interface:** Updates the progress indicator and task tree above the CLI + input prompt. +- **Persistence:** Task state is saved automatically to `.tracker/tasks/` in the + project workspace. +- **Dependencies:** Tasks can depend on other tasks, forming a directed acyclic + graph (DAG). The agent must resolve dependencies before starting blocked + tasks. +- **Interaction:** Users can view the current state of the tracker by asking the + agent to visualize it, or by running `gemini-cli` commands if implemented. + +## Use cases + +- Breaking down a complex feature implementation into a hierarchy of epics and + tasks. +- Coordinating multi-file refactoring projects that span multiple sessions. +- Tracking bugs and feature requests directly within the context of an active + codebase. +- Providing visibility into the agent's current focus and remaining work. + +## Next steps + +- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for + usage details and migration from the legacy todo list. +- Learn about [Session management](../cli/session-management.md) for context on + persistent state. From f6614f9188eb6a304080a5b0943951692fd50da9 Mon Sep 17 00:00:00 2001 From: Anjali Sridhar Date: Thu, 2 Apr 2026 12:53:22 -0700 Subject: [PATCH 2/2] docs: correct tracker storage path and session behavior --- docs/reference/tools.md | 2 +- docs/tools/tracker.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 0a768a2198b..cc0caebfae4 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -100,7 +100,7 @@ each tool. | Tool | Kind | Description | | :---------------------------------------------- | :------ | :-------------------------------------------------------------------------- | -| [`tracker_create_task`](../tools/tracker.md) | `Other` | Creates a new task in the persistent tracker. | +| [`tracker_create_task`](../tools/tracker.md) | `Other` | Creates a new task in the experimental tracker. | | [`tracker_update_task`](../tools/tracker.md) | `Other` | Updates an existing task's status, description, or dependencies. | | [`tracker_get_task`](../tools/tracker.md) | `Other` | Retrieves the full details of a specific task. | | [`tracker_list_tasks`](../tools/tracker.md) | `Other` | Lists tasks in the tracker, optionally filtered by status, type, or parent. | diff --git a/docs/tools/tracker.md b/docs/tools/tracker.md index b35712cb293..387d0bd654a 100644 --- a/docs/tools/tracker.md +++ b/docs/tools/tracker.md @@ -13,9 +13,8 @@ legacy `write_todos` tool. The agent uses these tools to manage its execution plan, decompose complex goals into actionable sub-tasks, and provide real-time progress updates to the CLI -interface. The task state persists across sessions in the `.tracker/tasks/` -directory, allowing you to resume long-running projects or verify progress -incrementally. +interface. The task state is stored in the `.gemini/tmp/tracker/` +directory, allowing the agent to manage its plan for the current session. ### Available Tools @@ -36,8 +35,9 @@ incrementally. - **Interface:** Updates the progress indicator and task tree above the CLI input prompt. -- **Persistence:** Task state is saved automatically to `.tracker/tasks/` in the - project workspace. +- **Persistence:** Task state is saved automatically to the + `.gemini/tmp/tracker/` directory. Task states are session-specific + and do not persist across different sessions. - **Dependencies:** Tasks can depend on other tasks, forming a directed acyclic graph (DAG). The agent must resolve dependencies before starting blocked tasks. @@ -46,9 +46,9 @@ incrementally. ## Use cases -- Breaking down a complex feature implementation into a hierarchy of epics and - tasks. -- Coordinating multi-file refactoring projects that span multiple sessions. +- Coordinating multi-file refactoring projects. +- Breaking down a mission into a hierarchy of epics and tasks for better + visibility. - Tracking bugs and feature requests directly within the context of an active codebase. - Providing visibility into the agent's current focus and remaining work.