# Working with GitHub Copilot CLI on a Flask project

URL: https://agentvera.dev/en/blog/copilot-cli-for-flask/ · Published: 2026-11-01

A practical guide for Flask developers using GitHub Copilot CLI: setup, instructions file, prompts, pitfalls, and testing with pytest and blueprints.

**In short:**

- Put Flask-specific commands, layout, and rules in .github/copilot-instructions.md so Copilot CLI respects app factory and blueprints.
- Work in small steps: ask for a plan, run pytest after each change, and review the diff for app context and SQLAlchemy mistakes.
- Use parallel agents in worktrees with code review and checkpoints when one Flask codebase has several independent feature streams.

[GitHub Copilot CLI](/en/agents/copilot-cli/) is a terminal coding agent that works well for Flask projects when you give it project-specific instructions and keep the feedback loop tight. Start `copilot` in your project root and treat it as a pair programmer that reads your code, writes changes, and runs commands. This guide covers setup, a practical working loop, common Flask tasks, pitfalls, testing, and running several agents safely.

## Why Copilot CLI fits Flask’s structure

Flask codebases tend to be small but convention-heavy: an application factory, blueprints, per-request context, and Jinja templates that share layout blocks. GitHub Copilot CLI can follow these patterns when they are described in the instructions file, which means less repeated explanation for each route or template. Because Flask development often consists of short edit-run-test cycles, a terminal agent that can run `pytest -q` and show the diff immediately matches the workflow. It is especially useful for scaffolding blueprints, writing view functions that stay consistent with existing URL rules, and keeping tests aligned with the app factory.

## Put Flask’s rules where Copilot CLI reads them

GitHub Copilot CLI reads project instructions from `.github/copilot-instructions.md` or `AGENTS.md`. Put concrete commands there, not generic advice. For a Flask project, the file should tell the agent how to install dependencies, run the app, run tests, lint, and where code lives. It should also state Flask-specific rules: always use the application factory, register blueprints explicitly, use `url_for()` instead of hardcoded URLs, and access SQLAlchemy sessions only inside an app context.

Here is a short example:

```markdown
# Flask project instructions

## Commands
- Install: `python -m pip install -e ".[dev]"`
- Run: `flask --app wsgi:app run --debug`
- Test: `pytest -q`
- Lint: `ruff check . && ruff format --check .`

## Layout
- `app/` contains the application factory `create_app()`
- `app/blueprints/` holds blueprints; register each in `create_app()`
- `app/templates/` holds Jinja templates; extend `base.html` and override blocks
- `app/models.py` holds SQLAlchemy models
- `tests/` holds pytest tests

## Flask rules
- Never create a global Flask app; always use `create_app()`
- Route handlers return strings, `Response`, or valid tuples
- Use `url_for()` in templates and redirects, never hardcode URLs
- Keep blueprint endpoints prefixed and self-contained
- When changing models, add a migration and a test
```

For larger apps, include a generated codebase map in `AGENTS.md` so the agent can find route and model details without grepping; see [Codebase map for AI agents: find code without grep](/en/blog/codebase-map-for-ai-agents/).

## A loop that keeps Flask changes reviewable

Do not let the agent make a large change without a plan. Start each task by asking for a short plan that lists files to create or modify and the test command to run. Then approve the plan or ask for adjustments. Work in small steps: one route, one template, one test. After each change, have the agent run `pytest -q` and show the diff. Review the diff before moving on; Flask context bugs often appear as ordinary type errors but are caused by using `current_app` or `request` outside a request.

Here are example prompts that align with that loop:

| Task | Prompt for Copilot CLI |
| --- | --- |
| Add a blueprint | Add a `users` blueprint with `GET /users` and `POST /users`, using the existing `User` model and Jinja templates that extend `base.html`. |
| Fix a redirect | Update the `auth` blueprint to take `next` from query string, validate it to allow only relative URLs, and redirect safely after login. |
| Write a test | Write a pytest fixture that creates the app with a temporary SQLite database and tests that `POST /users` creates a user and redirects to `GET /users`. |
| Refactor a form | Move the profile update form to `forms.py`, use WTForms validation, and update the route and template to match. |

Ask the agent to explain any changes that touch `app/__init__.py`, the application factory, or blueprint registration.

## Where Copilot CLI helps and where to double-check Flask context

Copilot CLI is reliable for repetitive Flask boilerplate: creating a blueprint with its `__init__.py`, view functions, and templates; adding simple CRUD routes; writing pytest fixtures that call the app factory; and wiring static files or context processors. It also handles template fragments well when you point it at `base.html` and the existing block structure.

Watch it closely in areas where Flask’s implicit context matters. The most common mistake is using `current_app`, `g`, or `request` in a helper function that is not called from a request. Another is lazy-loading SQLAlchemy relationships outside the request, which raises a `DetachedInstanceError`. The agent may also hardcode URLs instead of using `url_for()`, misname endpoint strings, or forget to register a blueprint in `create_app()`. With app factory patterns, circular imports are a risk if the agent puts blueprint imports at module level instead of inside the factory. Review every diff that touches `models.py`, `extensions.py`, or `app/__init__.py`.

## Verifying routes, templates, and database behavior

Require the agent to run tests after each meaningful change. For Flask, the fastest signal is `pytest -q` with fixtures that build the app through `create_app()` and use a temporary SQLite database. Also ask the agent to run `flask --app wsgi:app routes` after adding or changing routes, so you can verify the URL map without starting the server. If you want the agent to verify rendered pages in a real browser, the setup described in [AI agent browser testing: let the agent check your app](/en/blog/ai-agent-browser-testing/) is a useful complement to pytest.

When reviewing agent-written tests, check that they don’t depend on a fixed database path, that they clean up between tests, and that they cover both success and validation failure paths for forms. A good prompt is: `Run pytest, show the diff, and explain any test failures or Flask context errors before I commit.`

## Parallel agents for larger Flask codebases

When a Flask project has several independent workstreams, the AgentVera desktop app lets you run GitHub Copilot CLI and other coding agents side by side in real terminal panels. The most valuable parts for Flask are parallel agents in separate git worktrees, so one agent can add a blueprint while another refactors SQLAlchemy models without overwriting files; automatic code review after each turn, which links findings to file:line and catches route or template context mistakes; and checkpoints that let you undo a bad migration or blueprint split. These give Flask teams enough isolation and review to work safely with multiple agents.

## Keep the feedback loop tight

GitHub Copilot CLI becomes a much stronger Flask collaborator when you invest in a clear instructions file and a disciplined loop of small changes, tests, and diff reviews. Use the app factory and blueprints as your consistency anchors, watch the request context and SQLAlchemy session traps, and verify with pytest and `flask routes`. When one agent is not enough, run parallel agents in worktrees with code review and checkpoints to keep Flask changes isolated and reviewable.

## Frequently asked questions

**Can GitHub Copilot CLI generate a complete Flask app?** Yes, it can scaffold an application factory, blueprints, routes, templates, and pytest tests. The result is more consistent when you first add Flask-specific rules to .github/copilot-instructions.md and review each diff.

**How do I make Copilot CLI follow Flask application factory and blueprints?** Create .github/copilot-instructions.md or AGENTS.md with commands, folder layout, and rules such as no global app, register blueprints in create_app, and use url_for instead of hardcoded URLs. Refer Copilot to that file at the start of the session.

**Does Copilot CLI run pytest automatically?** It can run pytest when you ask it to, for example after each change with pytest -q. You should require it to show the diff and explain failures, and ensure tests use create_app and a temporary database.

**What are common Flask mistakes to watch for with Copilot CLI?** Watch for using current_app or request outside a request context, lazy-loading SQLAlchemy relationships outside the session, hardcoded URLs, and forgetting to register blueprints. Review diffs in app/__init__.py, models.py, and extensions.py closely.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/