🤖

Gemini Code Assist Track — G06: Agent Mode I Stop asking questions and start delegating work. Agent mode plans multi-file changes, shows you every diff, runs commands with your approval — and you ship a 5-file feature in the lab.

Agent Mode I: Delegating Multi-File Work

Everything so far was conversation: you ask, it answers, you apply. Agent mode flips the relationship — you state an outcome, and the AI does the work: reading files, planning, editing across the codebase, and running commands. Your job changes from typist to reviewer.

What Agent Mode Is

Analogy First

Chat is asking a brilliant consultant questions across a desk: they advise, you do. Agent mode is handing a competent junior engineer a ticket: "add tagging to recipes — storage, API, search, tests." They go off, read the codebase, come back with a plan ("I'll touch these five files, in this order"), and then do the work — showing you each change for sign-off, asking before running anything on your machine. The pain agent mode removes isn't thinking — chat already helped there — it's the orchestration: holding seven coordinated edits in your head and applying them in the right order without dropping one. The junior never gets tired, never forgets file four, and shows receipts for everything.

Technical Definition

Agent mode is the agenticOperating as an agent: pursuing a goal through multiple self-directed steps — reading files, making edits, invoking tools — rather than producing a single response. mode of Gemini Code Assist chat. Given a task, the agent can:

Read your project (within .aiexclude limits) and your GEMINI.md rules
Plan a multi-step approach and present it before acting
Edit multiple files, presenting each change as a reviewable diff
Run tools — shell commands, file operations, grep — with your per-action approval, plus MCP servers for external systems (G07)

Enable it: VS Code — toggle Agent in the chat input area. IntelliJ — the Agent tab in the Gemini tool window. (Since June 2026 agent mode requires a Standard or Enterprise license — see G00.) One honest limitation: source citations are not available in agent mode — weigh that for IP-sensitive work.

The Plan → Diff → Approve Loop

Press play to watch one full agent cycle — this is exactly the shape of your lab:

Agent mode — one full cycle

You:Add tagging to recipes: storage, API endpoints, search filter, tests

Agent reads: storage.py, app.py, search.py, tests/, GEMINI.md...

Plan:1) storage.py: tags column + migration 2) add/get with tags

3) app.py: accept tags on POST, filter on GET 4) search.py: tag filter

5) tests: new cases for all of the above — Proceed?

You:Proceed, but tags must be lowercase-normalized on write

✦ Edit 1/5: storage.py — diff shown → you approve

✦ Edit 2/5: app.py — diff shown → you approve

⚠ Agent requests: run `pytest tests/ -v` [Allow once?]

You:Allow

✓ 14 passed — agent reports done, summarizes all changes

Press ▶ to watch a full agent cycle

The three approval gates

Plan gate — the agent proposes its approach first. This is your cheapest intervention point: redirecting a plan costs seconds; redirecting finished code costs minutes. (You used it above: "tags must be lowercase-normalized.")
Diff gate — every file edit appears as an inline diff (green added / red removed) you approve or reject individually.
Command gate — any shell command (install, test run, file delete) requires explicit permission before execution.

Why It Matters

The gates are what make delegation safe enough to use daily. Without them, an agent is a chaos machine with filesystem access; with them, it's a junior engineer whose every commit you review. The discipline transfer from G02–G04 (review before accept) is the same skill — now applied to plans and diffs instead of ghost text. Auto-approve mode exists (G07) and has its place, but you earn it after you've watched the gates work.

Checkpoints & Reverting

Technical Definition

Before applying changes, Gemini Code Assist records a checkpoint — a snapshot of affected files. If an agent session goes sideways, Revert to checkpoint restores the files to their pre-suggestion state (generally available in IntelliJ; VS Code offers per-diff rejection and undo). This is the in-IDE safety net — but your real safety net is git: you committed Recipe Box at the end of G05, so git diff shows everything any agent did, and git restore . is the nuclear undo.

Gotcha

Checkpoints cover file edits — they do not undo command effects. If you approve pip install something or a script that writes to your database, reverting files won't uninstall the package or restore the data. That's why the command gate deserves your sharpest attention: read every command like it's about to run, because it is.

Lab: Ship a 5-File Feature

The task mirrors real work: recipe tagging, touching storage, API, search, and tests. Prerequisites: Recipe Box as of G05 (with GEMINI.md, .aiexclude, passing pytest suite, git-committed).

Safety first: clean git state

terminal

git status        # should be clean
pytest tests/ -v  # should be all green — this is your "before" truth

Never start an agent session on a dirty tree: you want git diff afterward to show only what the agent did.

Write the task like a ticket, not a wish

Toggle Agent mode on and give it this — note it specifies outcomes and constraints, not implementation:

agent prompt

Add tagging support to Recipe Box:

1. Recipes can have zero or more string tags (e.g. "vegan", "quick").
   Store them in SQLite — your choice of schema, but explain the tradeoff
   you chose in the plan.
2. POST /recipes accepts an optional "tags" list; invalid tags
   (non-string, empty) → 400.
3. GET /recipes?tag=vegan filters by tag.
4. search_recipes gains an optional tags parameter (match = recipe has
   ALL given tags).
5. Tags are normalized to lowercase on write.
6. Update the pytest suite to cover all of this; everything must pass.

Follow the GEMINI.md rules. Show me your plan before editing.

WHAT: a 6-requirement ticket. WHY "explain the tradeoff": tags can be a JSON column (simple) or a join table (relational). Forcing the agent to justify its choice in the plan tells you whether it actually reasoned. GOTCHA: "Show me your plan before editing" makes the plan gate explicit — do this until it's habit.

Review the plan like a tech lead

Before approving, check the plan against this list:

Does it touch all the right files (storage.py, app.py, search.py, tests/) — and only those?
Does its schema choice come with the requested justification?
Does it mention migrating the existing recipes table (your DB already has data)?
Does it plan to run the tests at the end?

If anything's off, say so in plain language now — e.g. "don't drop the table; migrate it". Iterating on the plan is the whole point of the gate.

Review each diff — here's what "reviewing" means

For every file diff the agent presents, run the same three questions:

def add_recipe(recipe: dict) -> int:
    tags = [t.strip().lower() for t in recipe.get("tags", [])]
    if any(not isinstance(t, str) or not t for t in recipe.get("tags", [])):
        raise ValueError("tags must be non-empty strings")
    try:
        with sqlite3.connect(DB_PATH) as conn:

(1) Correct? — wait, the validation above runs after the lowercase comprehension would crash on non-strings. Order bug: validate first, then normalize. Reject this hunk and tell the agent exactly that. (2) In scope? — did it sneak in unrelated "improvements"? Reject those too. (3) Rule-compliant? — parameterized SQL, StorageError wrapping, type hints (your GEMINI.md is the contract).

Let it prove itself, then commit

When the agent asks to run pytest — allow it. Expect a wrinkle: some pre-existing tests may legitimately need updates (e.g., a test asserting exact dict shape now sees a tags key). Distinguish carefully: updating a test because the contract intentionally grew is fine; weakening a test to make a bug pass is not. When everything's green:

terminal

git diff --stat   # see the full footprint of what the agent changed
pytest tests/ -v  # your independent verification, outside the agent
git add -A; git commit -m "Add recipe tagging (agent-assisted, human-reviewed)"

✅

Success criteria All tests green from your terminal (not just the agent's claim); curl -X POST with tags returns 201; GET /recipes?tag=vegan filters; git diff --stat shows changes only in expected files. If any criterion fails, that's your next agent prompt — with the evidence pasted in.

What Just Happened?

You delegated a coordinated 5-file feature and stayed in control through three gates: you corrected the plan (cheapest), caught an ordering bug in a diff (the review skill from G04, repurposed), and verified the result independently (never outsource the final pytest). Also notice GEMINI.md silently steering the agent the whole time — the G05 investment paying off at scale.

Chat vs Agent: Choosing the Right Mode

Situation	Use	Because
"Why does this fail?" / "How does X work?"	Chat	You need understanding, not edits
Single-file change you can review in one glance	Chat (or smart action)	Agent overhead buys nothing
Coordinated change across 3+ files	Agent	Orchestration is the agent's superpower
"Make all TODOs in this project real"	Agent	Needs project-wide reading + many edits
Exploring design options before deciding	Chat	Cheap iteration on ideas; no files touched
Migration (library/version) across the codebase	Agent	Mechanical, broad, verifiable by tests

Rule of thumb: chat to decide, agent to execute. The expensive failure is the reverse — letting an agent "explore" (it explores by editing) or hand-applying a 9-file change chat described (you'll drop file six).

Knowledge Check

1. The fundamental shift from chat to agent mode is…

A bigger model answers your questions

From advising you to acting for you: the AI reads, plans, edits multiple files, and runs tools — while you review at gates

It works without a license

It only writes documentation

2. Why is the plan gate the cheapest place to intervene?

Redirecting an approach before any code exists costs seconds; fixing finished wrong code costs the work plus the unwinding

Plans are billed at a lower rate

The agent refuses corrections after planning

It isn't — diffs are cheaper

3. What do checkpoints NOT undo?

Edits to Python files

Edits to multiple files at once

Side effects of approved commands — installed packages, modified databases, deleted artifacts

Changes to GEMINI.md

4. The agent's test run passes. Before committing you should still…

Nothing — the agent's word is verification

Run pytest yourself and inspect git diff — independent verification of both behavior and change footprint

Re-run the agent with the same prompt to compare

Delete the checkpoint

5. "Chat to decide, agent to execute" means…

Chat is deprecated once you have agent mode

Explore options and build understanding in chat (no files touched); hand the chosen, well-specified task to the agent for coordinated execution

Agents can't answer questions

Use both simultaneously on the same task

Quiz Complete!

Ready for G07: Agent Mode II — MCP Servers & Power Tools →