ContextQMD
Back to Gemini Cli

Tracker tools (`tracker_*`)

docs/tools/tracker.md

0.41.12.5 KB
Original Source

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