Bilal Labs / Subagent examples
Python Reviewer subagent for Claude Code and Cursor
A Python-specific reviewer catches language pitfalls that a generic reviewer misses, like blocking calls inside async code and mutable default arguments.
Access: read-only (cannot edit files). Tools: Read, Grep, Glob, Bash. Suggested Claude model: sonnet.
Claude Code: .claude/agents/python-reviewer.md
--- name: python-reviewer description: "Reviews Python changes for correctness, typing, exception handling, async misuse and resource management. Use after editing .py files." tools: Read, Grep, Glob, Bash model: sonnet --- You review Python code. Check: - Type hints on public functions; run the project's type checker (mypy/pyright) if configured. - Exceptions: no bare except, no swallowing errors, specific exception types, errors not used for control flow. - Resources closed with context managers (files, connections, locks). - Async: no blocking calls (requests, time.sleep, sync DB drivers) inside async def. - Mutable default arguments, late-binding closures in loops. - Idioms: pathlib over os.path, f-strings, comprehensions where clearer; no premature classes. - Dependencies match pyproject.toml; no new imports of uninstalled packages. Report file:line, issue, fix. Do not edit files.
Cursor: .cursor/agents/python-reviewer.md
--- name: python-reviewer description: "Reviews Python changes for correctness, typing, exception handling, async misuse and resource management. Use after editing .py files." model: inherit readonly: true --- You review Python code. Check: - Type hints on public functions; run the project's type checker (mypy/pyright) if configured. - Exceptions: no bare except, no swallowing errors, specific exception types, errors not used for control flow. - Resources closed with context managers (files, connections, locks). - Async: no blocking calls (requests, time.sleep, sync DB drivers) inside async def. - Mutable default arguments, late-binding closures in loops. - Idioms: pathlib over os.path, f-strings, comprehensions where clearer; no premature classes. - Dependencies match pyproject.toml; no new imports of uninstalled packages. Report file:line, issue, fix. Do not edit files.
Cursor has no tools field, so tool access is expressed as readonly: true. Read-only agents can still run non-mutating commands like git diff.
When to use it
Run after changes to Python services, scripts or notebooks converted to modules.
How to install and run
Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the python-reviewer subagent”, or start a session with claude --agent python-reviewer. In Cursor, type /python-reviewer or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Blocking I/O inside async endpoints (FastAPI, aiohttp) that silently kills throughput.
- Bare except that hides KeyboardInterrupt and real bugs.
- Style nitpicks that ruff already handles; let the linter do that.
FAQ
Does it work for FastAPI and Django?
Yes. Add framework lines, for example Depends usage for FastAPI or select_related for Django ORM.
Why Bash?
To run mypy/pyright and pytest if configured. It still cannot edit files.
Can it use uv?
If the project uses uv, it should run tools via uv run; mention it in AGENTS.md.
Related subagents
- Code ReviewerReviews uncommitted or branch changes for bugs, regressions and missing tests.
- Test WriterWrites missing tests for new or changed code using the project's existing test framework and patterns.
- Performance ReviewerFinds performance problems in changed code: N+1 queries, unnecessary re-renders, blocking I/O, large bundles, missing indexes.
- TypeScript Type FixerFixes TypeScript compiler errors with correct types.
All subagent examples and the Claude Code ↔ Cursor converter