Gemini CLI for Python projects: a practical guide

Gemini CLI is Google’s terminal coding agent for working directly in a project. For Python, the practical way to use it is to run gemini inside a virtual environment with a GEMINI.md that records your exact install, lint, type-check, and test commands. The agent reads that file and uses your real terminal, so it can act on pytest, ruff, and mypy feedback instead of guessing.

Where Gemini CLI earns its keep in Python codebases

Python has fast feedback loops: you change a module, run pytest, run ruff, run mypy, and read specific tracebacks. Gemini CLI is useful when those loops are explicit. It can open your code, make a narrow edit, run the command you named, read the error, and iterate. That matches Python’s style of small modules, explicit imports, and tests that should fail for one reason at a time. Typed Python makes the loop even stronger because mypy output often names the exact file and line the agent needs to revisit. The agent is not a replacement for good project layout; it is a force multiplier when your pyproject.toml already declares deterministic commands.

Making the project agent-ready with GEMINI.md

Before starting gemini, create the virtual environment and install the project in editable mode. The agent does not manage your environment magically; it runs commands in the current terminal. A clean setup prevents most Python-specific failures.

The most important file is GEMINI.md at the repo root. Keep it concrete and short. For a Python project, it should state the Python version, the venv activation command, how to install, and the exact commands for testing, linting, and type checking. It should also state folder conventions and rules such as “do not edit pyproject.toml without approval” and “run pytest, ruff, and mypy after each change.” Here is a realistic example:

# Project instructions for Gemini CLI

Python 3.12. Activate the existing venv with:
source .venv/bin/activate

Install the package and dev tools:
pip install -e ".[dev]"

Run tests:
pytest -q

Lint and format checks:
ruff check .

Type check:
mypy src

Layout:
- src/mypkg/ contains application code
- tests/ mirrors src/mypkg/ one-to-one
- scripts/ is for one-off utilities

Rules:
- Keep changes small and scoped to one module or behavior.
- Use `from __future__ import annotations`; do not introduce `Any` without a comment.
- Prefer explicit `-> None` on functions that return nothing.
- After every change, run pytest, ruff, and mypy. Fix only errors related to the change.
- Do not modify pyproject.toml, CI files, or lockfiles unless explicitly asked.
- When a test fails, read the full traceback before editing; do not weaken assertions to make a test pass.

This file turns the agent from a general assistant into a project-specific Python pair. The key files the agent will touch have clear roles:

A day-to-day edit-test-review loop

Use a plan, small step, test, review loop. Ask for one behavior at a time, require the verification commands from GEMINI.md, and read the diff before accepting. This is close to AI pair programming: how to work with a coding agent, but the Python version is stricter: if the venv is not active, commands fail; if tests are not run, a type fix can silently break imports.

Example prompts for typical Python tasks:

• “Add a frozen dataclass User in src/mypkg/models.py with fields id: int, email: str, and is_active: bool = True. Add a to_dict method and a matching pytest test in tests/test_models.py.”
• “Write pytest tests for validate_email in src/mypkg/validation.py using pytest.mark.parametrize. Cover an empty string, a missing @, and a valid address.”
• “Refactor load_config to return a Config TypedDict instead of a plain dict. Update call sites in src/mypkg and add type coverage in mypy.”
• “Run pytest -q, ruff check ., and mypy src. Fix only the failures introduced by the previous change, then rerun all three.”
• “Explain the failing test traceback for test_parse_iso, propose the smallest fix, show it as a diff, and wait for approval.”

Keep each turn small enough that you can review the entire diff in a few minutes. If the agent says it cannot run a command, check that the venv is active in your terminal and that the editable install completed.

What Gemini CLI does well in Python and where to be careful

Gemini CLI is good at adding type hints, generating pytest cases from a function signature, refactoring a module into smaller modules, updating imports after a rename, and converting a function to async when the surrounding code already follows a clear pattern. It can also write the boilerplate for a dataclass, Pydantic model, or CLI entry point when your pyproject.toml already has the dependencies.

Watch it closely in areas that are error-prone in Python. The most common issue is environment confusion: the agent may run a command with the system Python instead of the venv if the activation line is missing from GEMINI.md or the shell session was reopened. Another pitfall is broad dependency edits: adding or upgrading packages without checking the lockfile or Python version constraints. It may also use Any too freely, add # type: ignore to silence mypy, or change a test assertion to make a failing test pass. Review any changes to tests/ with suspicion, and require a separate test run before accepting a “fix.”

The agent may also overlook the difference between runtime and import-time side effects, especially in __init__.py. For a Python project, a helpful rule is to ask the agent to explain why a change belongs in a particular module before editing.

Using tests and types as acceptance gates

Do not accept an agent turn without a green verification command. The minimum bar for Python work is: pytest -q, ruff check ., and mypy src. Have the agent run all three after every change, and paste the output into the conversation when something fails. For new behavior, require a test before the implementation is considered complete. This makes the agent work like a test-driven loop: it writes or updates a test, sees it fail, edits the source, and reruns the test.

Use git diff to review exactly what changed. For tricky tracebacks, follow a similar workflow to How to debug code with AI: a practical workflow: ask for the root cause first, then a minimal patch, then the verification commands. If the agent changes a type, confirm mypy passes on the source directory; if it touches packaging, confirm the editable install still works in the venv.

Coordinating several agents with AgentVera

When one Python change touches several areas, you can run multiple Gemini CLI sessions side by side with AgentVera. It runs the real command line tools in separate terminal panels, so each agent can work in its own git worktree and avoid overwriting files. After a turn ends, a second model reviews the code and links findings to exact lines, which helps catch type errors, weak tests, or venv issues. Token budgets keep a long refactor from running away while preserving the conversation after the cap. This is useful for Python worktrees because you can keep a baseline branch intact while agents try independent edits.

Bottom line

Gemini CLI works best on a Python project when the project tells the agent exactly how to verify work. Write a short GEMINI.md with your venv activation, editable install, pytest, ruff, and mypy commands, then use a small review loop. For larger efforts, parallel worktrees and automatic review help keep the codebase clean. If you are new to Gemini CLI itself, start with the Gemini CLI overview or the step-by-step guide.