flake8-agents is a Flake8 plugin for codebases that use AI-generated Python.
It exists because generated code often hides problems from static analysis with
reflection, broad types, casts, raw namespace access, and stale suppressions.
The plugin turns those escape hatches into explicit AGT diagnostics.
uv sync
uv run flake8 --select AGT src
uv run module-size src --warn-lines 800 --error-lines 1000Minimal Flake8 config:
[flake8]
select = AGT| Code | Catches | Example |
|---|---|---|
AGT001 |
unused explicit AGT noqa suppressions |
value: int = 1 # noqa: AGT105 |
AGT100 |
broad type-checker suppressions | value = 1 # type: ignore[assignment] |
| Code | Catches | Example |
|---|---|---|
AGT101 |
typing.cast used as a narrowing bypass |
result = cast(int, value) |
AGT102 |
broad object annotations |
def handle(value: object) -> None: ... |
AGT103 |
known-shape containers that erase value shape | payload: dict[str, object] |
AGT104 |
vague callable signatures | callback: Callable[..., int] |
AGT105 |
broad Any at non-local boundaries |
def handle(value: Any) -> None: ... |
AGT106 |
legacy type-parameter factories | T = TypeVar("T") |
AGT107 |
classmethod factories returning their class name | def build(cls) -> "Box": ... |
| Code | Catches | Example |
|---|---|---|
AGT200 |
dynamic attribute reads | value = getattr(target, "name") |
AGT201 |
dynamic attribute writes | setattr(target, "name", value) |
AGT202 |
raw namespace extraction | namespace = vars(target) |
AGT203 |
dynamic import builtin | module = __import__("package") |
AGT204 |
importlib.import_module calls |
module = importlib.import_module("package") |
AGT205 |
setattr-style mutation methods | target.setattr("name", value) |
AGT206 |
direct __setattr__ calls |
target.__setattr__("name", value) |
AGT207 |
direct __new__ construction |
instance = Target.__new__(Target) |
AGT208 |
direct raw __dict__ indexing |
value = target.__dict__["name"] |
AGT209 |
aliasing raw __dict__
|
namespace = target.__dict__ |
AGT210 |
indexing raw __dict__ aliases |
value = namespace["name"] |
AGT211 |
aliasing dotted module imports | import package.module as alias |
AGT212 |
types.SimpleNamespace dynamic attribute bags |
data = types.SimpleNamespace(name="value") |
| Code | Catches | Example |
|---|---|---|
AGT300 |
private project imports across module boundaries | from module import _private |
AGT301 |
configured retired project import paths | import module.legacy |
AGT302 |
declarations before the module import section is complete |
VALUE = 1 before import ast
|
module-size is a separate command that fails on oversized Python modules.
uv run module-size src --warn-lines 800 --error-lines 1000| Option | Default | Meaning |
|---|---|---|
paths |
required | Python files or directories to scan |
--warn-lines |
800 |
print warning findings at or above this line count |
--error-lines |
1000 |
return failure at or above this line count |
--exclude REGEX |
none | skip files whose resolved path matches the regex |
--suppress-warnings |
false |
hide warning findings from stdout |
PATH LINES LEVEL THRESHOLD
/path/to/src/package/large.py 1012 error 1000
flake8-agents supports Python >=3.11 and is typed (py.typed). Runtime
dependencies are intentionally small: flake8 and typing-extensions.
AGT rules prefer code that people and static tools can inspect. They are not
a blanket claim that dynamic declarations, dynamic imports, casts, broad types,
or suppressions are anti-patterns in every codebase. The concern is AI-generated
code overusing those escape hatches until intent and program shape are hard for
humans to audit. AI models may improve, but today's generated code can take the
shortest path to satisfy the last prompt, paper over uncertainty, or make an
incomplete change look complete. These rules also make those moves harder to
hide. When the trade-off is intentional, keep the code and add a targeted
explicit noqa with the specific diagnostic code, for example # noqa: AGT204.
MIT. See LICENSE.
