Gemini CLI Plan Mode and Task Tracking

Yes. Gemini CLI has a plan mode, and it is one of its approval modes rather than a separate tool. Google’s plan mode documentation↗ (opens in a new tab) describes it as a read-only environment for working out a solution before implementing it: Gemini can read the code, search, and ask you questions, but it cannot change any file except its own plan. You enter it by pressing Shift+Tab until the mode shows Plan, by typing /plan, or by starting with gemini --approval-mode=plan. When the plan is ready you approve it, and Gemini leaves plan mode and starts the work. What it does not do is keep that plan anywhere a colleague, or next week’s session, will look. That last step is yours.

The four approval modes

Plan mode makes more sense once you see the setting it belongs to. The Gemini CLI reference↗ (opens in a new tab) lists four values for --approval-mode, with default as the default:

• default: Gemini prompts for approval before tools that change things, such as writing a file or running a shell command.
• auto_edit: edit tools such as write_file and replace are approved automatically; other actions still ask.
• plan: read-only research and planning. Edits are blocked until you approve a plan.
• yolo: every action is approved automatically. The older --yolo flag is deprecated in favour of --approval-mode=yolo.

During a session, Shift+Tab cycles Default, Auto-Edit and Plan. YOLO is not in that cycle and cannot be set as the default in settings; it is enabled only on the command line, which is how it should be.

Entering plan mode

gemini --approval-mode=plan          # start the whole session in plan mode
/plan add retry logic to the export job   # inside a session, with or without a goal
# or press Shift+Tab until the mode reads Plan

You can also just ask: “start a plan for moving the settings page to the new form library” makes Gemini call its enter_plan_mode tool, which asks you to confirm the switch. To make plan mode the default, set general.defaultApprovalMode to plan in settings.json, or change it through /settings.

What it can and cannot do while planning

In plan mode Gemini keeps its reading tools: read_file, list_directory, glob, grep_search, web search, and web_fetch, which asks before fetching. It can hand research to its own investigator subagents and load skills. It cannot run shell commands or write outside its plans folder; the only writes allowed are Markdown plan files there.

• It asks you questions. The ask_user tool lets it lay out options and wait for your choice before it commits to an approach, which is often the most useful part of the session.
• MCP tools are allowed only if they are read-only, and they ask for confirmation by default. A board’s list and search tools are fine; tools that create or move tasks wait until you leave plan mode.
• It is about your files, not your judgement. Plan mode stops Gemini acting before you have read what it intends. Whether the plan is any good is still yours to decide.

Approving, changing, or leaving a plan

When Gemini has a finished plan it calls exit_plan_mode and shows it to you. Choose “Yes, automatically accept edits” or “Yes, manually accept edits” and it switches to Auto-Edit or Default respectively and starts implementing. To change the plan, type your feedback, or press Ctrl+X to open it in your editor and change it directly. Esc cancels. To leave without approving anything, press Shift+Tab or tell it to exit plan mode.

By default Gemini routes the planning to a Pro model and switches to a Flash model once the plan is approved, on the reasoning that thinking costs more than typing. If you would rather keep one model throughout, set general.plan.modelRouting to false.

Where the plan is saved

Plans are Markdown files under ~/.gemini/tmp/<project>/<session-id>/plans/. That is a temporary folder keyed to one session. You can move them into the project by setting general.plan.directory, for example to .gemini/plans; the documentation requires a custom path to sit inside the project.

{
  "general": {
    "defaultApprovalMode": "plan",
    "plan": { "directory": ".gemini/plans" }
  }
}

Even inside the repository, a plan file is written once and then overtaken by the work. Step three turns into two steps, step five turns out to be unnecessary, and the file does not know. Keep that in mind for the tracking section below.

GEMINI.md: what Gemini reads before it plans

A plan is only as good as what Gemini knows about the project. It reads that from GEMINI.md files, which Google’s GEMINI.md documentation↗ (opens in a new tab) says come from three places: a global ~/.gemini/GEMINI.md, files in your workspace folders and their parents, and files it finds just in time as tools open folders further down. All of them are concatenated and sent to the model.

• /memory show prints the combined context, so you can see exactly what it was told.
• /memory reload re-reads the files after you edit them.
• @file.md inside a GEMINI.md imports another file, so a long file can be split up.
• The context.fileName setting takes a list, such as ["AGENTS.md", "GEMINI.md"], so a repository that already keeps its rules in AGENTS.md does not need a second copy.

If several assistants work on the same repository, the question of which file each reads is covered in AI context files compared.

MCP: connecting Gemini to other tools

Gemini CLI reads MCP servers from mcpServers in ~/.gemini/settings.json or the project’s .gemini/settings.json. According to the MCP server documentation↗ (opens in a new tab), a streamable HTTP server takes httpUrl and an SSE server takes url; includeTools and excludeTools narrow what the model sees; and trust, which skips every confirmation for that server, is off by default. Leave it off. /mcp auth signs in to a server that uses OAuth, and /mcp lists what is connected.

gemini mcp add fenbs https://fenbs.ai/api/mcp --transport http
gemini mcp list
# then, inside a session:
/mcp auth fenbs

The to-do list is not the tracking

Gemini has its own checklist. The write_todos tool↗ (opens in a new tab) keeps a list of subtasks for a multi-step request, each pending, in progress, completed, cancelled or blocked; the progress line above the prompt shows the current one and Ctrl+T shows the whole list. It is useful while Gemini works. It is also internal to the session, so it tells nobody else what happened and is gone when you close the terminal. The plan file has the same problem with a longer life.

Tracking Gemini CLI work on a board

The fix is to give the plan a home other people and other sessions read: the task the work belongs to. On fenbs a task has a Problem box, written once, and a Plan box that is rewritten whenever something is learnt, which is the shape plan mode produces. Over MCP those are note and plan. Connect Gemini as on the Gemini CLI integration page, then put the rhythm in GEMINI.md so it happens every time:

## The board
- Before planning: call fenbs_whoami, then fenbs_get_context for this project,
  then fenbs_search for the task. Plan against what is already there.
- When I approve a plan: before editing any file, write it into the task's plan
  with fenbs_update_item, or file the task with fenbs_create_item (note = the
  problem, plan = the steps, files and how it will be checked).
- Starting: move the task to In Progress and comment what you are starting.
- If the approach changes, rewrite the plan on the task before carrying on.
- Finishing: set testStatus and testNotes, comment the commit, move it to Completed.

Notice the order. The read tools work in plan mode, so Gemini can search the board while it plans. The write tools wait until you approve, which is exactly when a plan becomes worth recording. Every change it makes is recorded in the board’s History under the assistant’s name, on your behalf.

If a person has already read a task and pressed “Let AI do this”, there is a shorter path: tell Gemini to call fenbs_next_approved_task when it has nothing else to do. It gets the most urgent approved task with its plan and limits, held for it while it works so two assistants never take the same one, and gives it back with fenbs_release_task if it cannot finish. Plan mode then becomes a check on the plan somebody else approved, rather than a way to write one.