flake8-agents

Flake8 Typed License: MIT

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.

Usage

uv sync
uv run flake8 --select AGT src
uv run module-size src --warn-lines 800 --error-lines 1000

Minimal Flake8 config:

[flake8]
select = AGT

Rules

Suppressions

Code	Catches	Example
`AGT001`	unused explicit AGT `noqa` suppressions	`value: int = 1 # noqa: AGT105`
`AGT100`	broad type-checker suppressions	`value = 1 # type: ignore[assignment]`

Type escapes

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": ...`

Dynamic anti-patterns

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")`

Import boundaries

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

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

Python support

flake8-agents supports Python >=3.11 and is typed (py.typed). Runtime dependencies are intentionally small: flake8 and typing-extensions.

Design note

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.

License

MIT. See LICENSE.

Metadata

Release files for flake8-agents 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flake8-agents 0.2.0
File	Size	Uploaded
flake8_agents-0.2.0.tar.gz	103.4 kB	Jun 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for flake8-agents 0.2.0
File	Interpreter	ABI	Platform	Reset
flake8_agents-0.2.0-py3-none-any.whl 23.8 kB Jun 12, 2026	Python 3	none	any	Details

Total release size: 127.2 kB

Release files / flake8_agents-0.2.0.tar.gz

Download URL	flake8_agents-0.2.0.tar.gz
Size	103.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`a093ec735a005fec12f4ab47c26943fa564ad12251b5ed5cfa948fa5d92d1c8b`
BLAKE2b-256 checksum How to use checksums	`725b94465d5efb8d71d7bd79a624c87f5b7f53877dda652cd3310a52e5a6a056`
Upload date	Jun 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / flake8_agents-0.2.0-py3-none-any.whl

Download URL	flake8_agents-0.2.0-py3-none-any.whl
Size	23.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`df5b1bbf0688fed19c2c93458d06717fd9afbad7880c4d2bf22660d7255ea5f3`
BLAKE2b-256 checksum How to use checksums	`b31c5bba8537de22dc35add255646414656ab15590ba7e86aa6f7be40464cbb9`
Upload date	Jun 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`