gemini-cli/docs/tools/tracker.md

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 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 for usage details and migration from the legacy todo list.
• Learn about Session management for context on persistent state.