Plan tasks with todos

Keep complex jobs on the rails with Gemini CLI's built-in task planning. In this guide, you'll learn how to ask for a plan, execute it step-by-step, and monitor progress with the todo list.

Prerequisites

• Gemini CLI installed and authenticated.
• A complex task in mind (for example, a multi-file refactor or new feature).

Why use task planning?

Standard LLMs have a limited context window and can "forget" the original goal after 10 turns of code generation. Task planning provides:

1. Visibility: You see exactly what the agent plans to do before it starts.
2. Focus: The agent knows exactly which step it's working on right now.
3. Resilience: If the agent gets stuck, the plan helps it get back on track.

How to ask for a plan

The best way to trigger task planning is to explicitly ask for it.

Prompt: I want to migrate this project from JavaScript to TypeScript. Please make a plan first.

Gemini will analyze your codebase and use the write_todos tool to generate a structured list.

Example Plan:

1. Create tsconfig.json.
2. Rename .js files to .ts.
3. Fix type errors in utils.js.
4. Fix type errors in server.js.
5. Verify build passes.

How to review and iterate

Once the plan is generated, it appears in your CLI. Review it.

• Missing steps? Tell the agent: "You forgot to add a step for installing @types/node."
• Wrong order? Tell the agent: "Let's verify the build after each file, not just at the end."

The agent will update the todo list dynamically.

How to execute the plan

Tell the agent to proceed.

Prompt: Looks good. Start with the first step.

As the agent works, you'll see the todo list update in real-time above the input box.

• Current focus: The active task is highlighted (for example, [IN_PROGRESS] Create tsconfig.json).
• Progress: Completed tasks are marked as done.

How to monitor progress (Ctrl+T)

For a long-running task, the full todo list might be hidden to save space. You can toggle the full view at any time.

Action: Press Ctrl+T.

This shows the complete list, including pending, in-progress, and completed items. It's a great way to check "how much is left?" without scrolling back up.

How to handle unexpected changes

Plans change. Maybe you discover a library is incompatible halfway through.

Prompt: Actually, let's skip the 'server.js' refactor for now. It's too risky.

The agent will mark that task as cancelled or remove it, and move to the next item. This dynamic adjustment is what makes the todo system powerful—it's a living document, not a static text block.

Next steps

• Explore Session management to save your plan and finish it tomorrow.
• See the Todo tool reference for technical schema details.
• Learn about Memory management to persist planning preferences (for example, "Always create a test plan first").