Gemini CLI works well on Flask projects because it operates in the same project directory as your application factory, blueprints, templates, and tests. You can guide it with a project-level GEMINI.md, ask for small changes, run pytest after each turn, and review the diff. This guide covers the setup, prompts, verification, and pitfalls specific to Flask. Gemini CLI
Why Gemini CLI fits Flask’s blueprint and factory structure
Flask applications are mostly plain Python plus Jinja templates, which means Gemini CLI can read the exact request flow from route decorators to template rendering. It can inspect how blueprints are registered in create_app, follow imports between models and views, and run the same commands you use: python -m pytest, ruff check ., and python -m flask --app run.py routes. This makes it useful for refactoring a route, adding a SQLAlchemy query, or updating a Jinja template without needing a separate browser tool. Because Flask projects are often structured around small units like blueprints, Gemini CLI can make one blueprint change and verify it with focused tests.
Project setup: GEMINI.md for Flask commands and conventions
Put a GEMINI.md file at the repository root. Gemini CLI reads this file before acting, so it is the most reliable way to keep the agent aligned with your Flask conventions. Keep it short and command-focused; do not paste entire documentation. Include build, test, lint, run commands, folder layout, and rules that prevent common Flask mistakes. For a typical application factory project with blueprints and SQLAlchemy, a useful GEMINI.md looks like this:
## Commands
- Install: python -m pip install -e '.[dev]'
- Test: python -m pytest -q
- Lint: ruff check .
- Run dev server: python -m flask --app run.py run --debug
## Layout
- app/ contains create_app() and extensions
- app/blueprints/ holds one blueprint package per feature
- app/templates/<blueprint>/ holds that blueprint's Jinja files
- app/models.py contains all SQLAlchemy models
- tests/ mirrors app/ with test_*.py files
## Flask rules
- All routes must be registered inside blueprints, not directly on app
- Use url_for, never hardcode URL paths
- Models live in app/models.py; no lazy loading after session close
- Templates must not run queries or business logic
- app context and request context must not be used at import timeReplace commands with the exact ones for your package manager and test runner. The important part is that every convention a new contractor would need is written down. When in doubt, add a rule for the mistake you do not want to see.
A practical loop: plan, edit, test, review
Treat Gemini CLI like a fast junior engineer: give it a clear, small task, then inspect the diff and run the tests yourself. Do not ask it to build a whole feature in one turn. A reliable loop follows AI pair programming principles: plan the change, edit one area, run focused tests, review the diff, then commit or ask for the next step.
Example prompts for typical Flask tasks:
- Read the auth blueprint and list all its routes and their endpoint names. Then propose a new password reset endpoint that matches the existing conventions.
- Add a
last_seendatetime column to the User model in app/models.py. Update the profile blueprint and its template to show the value. Do not create a migration yet. - In tests/test_orders.py, add a session-scoped app fixture and a client fixture. Then add two tests: the order detail route returns 200 for the owner and 403 for another logged-in user.
- Refactor the duplicate order query in the dashboard blueprint into a helper in app/services.py. Update the dashboard view to pass the result through context.
- Run python -m pytest -q. Fix any failures you introduced. Show me the git diff as a unified patch and summarize the files changed.
After each prompt, run the relevant test file, then the whole suite. Keep changes small enough that git diff remains reviewable in under a minute.
Flask tasks the agent handles well and pitfalls to watch
Gemini CLI handles many Flask changes well: registering new blueprints in create_app, adding route handlers, adjusting Jinja templates, writing SQLAlchemy queries, and expanding pytest coverage. The areas that need close review are the Flask-specific edges.
| Flask area | What to ask for | What to check after the edit |
|---|---|---|
| Blueprint registration | Add a new settings blueprint and register it with the url_prefix /settings | Confirm it registers in create_app and uses the project’s blueprint package layout, not a single file with Blueprint defined inline |
| URL building | Update this template link to the profile endpoint | Ensure url_for('profile.index', user_id=user.id) has the blueprint name, not just url_for('profile') |
| SQLAlchemy models | Add a relationship between Post and Comment | Check for lazy loading after the session is gone; add selectinload or join where needed |
| Jinja templates | Show the order total and status in the list | Ensure the template receives variables from the view, not queries; keep logic in Python |
| pytest fixtures | Create a fixture for an app with the test database | Confirm the fixture yields app context or request context and rolls back data between tests |
Common pitfalls to correct immediately:
- The agent adds
@app.routedirectly inside create_app or at module level instead of using the blueprint specified in GEMINI.md. - It uses
url_for('dashboard')when the blueprint endpoint isdashboard.index. - It imports
current_apporrequestat module import time, which works only inside an application context or request context. - It produces SQLAlchemy relationships that trigger lazy loads after the session has been closed, giving
DetachedInstanceError. - It puts query-building or conditional business logic into Jinja templates because the prompt was phrased as make the template show active orders.
- It tries to run database migrations or
flask db upgradewithout being asked, or writes migration code by hand when your project uses Alembic autogenerate.
When you spot one of these, add a rule to GEMINI.md and ask it to fix the specific file. This is faster than re-explaining the same convention in every prompt.
Testing and verifying Flask changes with the agent
Verification is not optional. For Flask changes, run:
python -m pytest -qafter every code change; if the change touches one blueprint, runpython -m pytest tests/test_auth.py -qfirst.ruff check .to catch unused imports in blueprint files.python -m flask --app run.py routesto confirm a new route is registered under the expected endpoint and URL rule.- Start the dev server and manually hit the affected URLs when the change involves templates, forms, or redirects.
Ask Gemini CLI to run the tests itself after a change, but do not trust its summary alone. Open the diff and look at the routes, url_for calls, and SQLAlchemy session usage. If a test fails, ask it to debug code with AI by reading the traceback and the fixture setup rather than replacing a test with a weaker assertion.
Parallel agents on a Flask project with AgentVera
For larger Flask work, you can split tasks by blueprint or layer: one agent may add authentication while another works on the order list. AgentVera runs the real Gemini CLI in separate terminal panels and can place each agent in its own git worktree, so parallel changes do not overwrite each other. After each agent turn, automatic code review checks for Flask issues like broken url_for calls or unregistered blueprints, and checkpoints let you undo a change that breaks the application factory. This AI agent orchestration fits a modular Flask codebase well.
Wrap-up
Gemini CLI is most effective on Flask projects when you treat it as a code-aware teammate: put your conventions in GEMINI.md, ask for one focused change at a time, run pytest and ruff after every turn, and review the diff for Flask-specific mistakes. The loop may feel slower at first, but it prevents the common failure mode of an agent generating a large patch that breaks the application factory or template rendering. Use focused prompts, keep blueprints and url_for rules explicit, and the agent will handle many day-to-day Flask tasks cleanly.