| # Tracker tools (`tracker_*`) |
| |
| <!-- prettier-ignore --> |
| > [!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 is stored in the `.gemini/tmp/tracker/<session-id>` |
| directory, allowing the agent to manage its plan for the current session. |
| |
| ### 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 the |
| `.gemini/tmp/tracker/<session-id>` 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. |
| - **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 |
| |
| - 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. |
| |
| ## 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. |
| |
