fluent-pythonista

pyagent

An opinionated Python code review, refactoring, and explanation agent powered by Claude. Part of the custom-coding-agents workspace — see the workspace README for the shared install flow.

Quickstart

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# From the workspace root — one lockfile resolves both agents into a single venv.
uv sync --extra dev

# Set your API key (the workspace .env at the repo root is read automatically).
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Run a code review
uv run pyagent review path/to/file.py

# Refactor a single file
uv run pyagent refactor path/to/file.py

# Refactor an entire codebase (full two-phase: plan, then batched execute)
uv run pyagent refactor path/to/project/

# Narrow refactor focused on a specific concern (single context-packed pass)
uv run pyagent refactor path/to/project/ -i "modernize type hints"

# Explain a file
uv run pyagent explain path/to/file.py

# Start an interactive chat session
uv run pyagent chat --path path/to/project/

Commands

Command	Description
review <path>	Review code for correctness, style, and best practices
refactor <path>	Apply named refactoring patterns from the playbook
explain <path>	Explain code structure, patterns, and design decisions
chat	Interactive conversation about a codebase
info	Show configuration and knowledge base stats

All commands accept --instructions / -i (or --question / -q for explain) for additional guidance, and --model / -m to override the default model. review, refactor, and explain all auto-detect file vs directory paths — no mode flag required. pyagent --version prints the installed version and exits.

Refactor modes

refactor picks its mode implicitly from the path and whether you supplied -i:

Path	-i instructions	Mode
file	n/a	single file, refactored in place with surrounding package context
directory	(none)	full codebase refactor in two phases (plan → batched execution)
directory	focused instructions	partial refactor — a single context-packed pass over the highest-priority files matching your instructions

The intuition: a bare refactor ./proj means "refactor the whole project", so every file gets a turn. A refactor ./proj -i "modernize the auth module" is narrow and focused, so only the files relevant to the instructions are touched — faster and cheaper.

Two flags override the heuristic when needed:

Flag	Description
--full	Force the two-phase codebase refactor (directory only)
--partial	Force the context-packed single-pass refactor (directory only)
--dry-run	Show proposed changes without writing any files
--no-confirm / -y	Apply changes without a confirmation prompt
--no-backup	Skip creating backup files before writing

The full mode works in two phases:

1. Planning — The LLM receives the full structural summary of the codebase and produces a named, actionable refactoring strategy (themes, order of operations, file-specific notes). The plan is persisted to .pyagent/last_plan.json and last_plan.md.
2. Execution — All source files are grouped into token-budget-constrained batches. Each batch is refactored with the overall plan as context. Per-batch output is persisted to .pyagent/batches/batch_NNN.md for audit, and a plan-adherence check flags any batch that ignored the strategy (and retries it once).

The same diff-review → confirm → backup → write workflow applies in every mode — you see every proposed change before anything is written to disk.

# Full refactor of the whole project (implicit — directory, no -i)
uv run pyagent refactor ./my_project

# Narrow refactor with a focus (implicit — directory + -i)
uv run pyagent refactor ./my_project -i "modernize type hints and remove legacy patterns"

# Force the full mode even when -i is narrow
uv run pyagent refactor ./my_project -i "clean up the models" --full

# Preview without writing
uv run pyagent refactor ./my_project --dry-run

Architecture

src/pyagent/
├── __main__.py     # CLI entrypoint (typer + rich)
├── agent.py        # Core orchestration loop
├── config.py       # Pydantic settings (PYAGENT_* env vars)
├── context.py      # Codebase ingestion, AST parsing & file batching
├── logging.py      # Structured logger factory
├── memory.py       # Conversation state management
├── plan_model.py   # RefactorPlan / FileChange schemas
├── prompts.py      # Prompt templates per capability
├── rag.py          # Documentation retrieval
├── writer.py       # Diff rendering, backups, and on-disk writes
└── tools/
    ├── base.py       # Tool protocol
    ├── reviewer.py   # Code review tool
    ├── refactor.py   # Refactoring tool (single-file + batch)
    └── explainer.py  # Explanation tool

Configuration

All settings are read from environment variables (optionally via a .env file at the workspace root) and resolved by pyagent.config.Settings.

Env var	Default	Purpose
ANTHROPIC_API_KEY	required	API key for Claude access
PYAGENT_MODEL	claude-sonnet-4-20250514	Model ID to use
PYAGENT_MAX_TOKENS	8000	Upper bound on per-turn model output
PYAGENT_BATCH_MAX_TOKENS	20000	Per-batch token budget during two-phase codebase refactors
PYAGENT_CONTEXT_TOKEN_BUDGET	30000	Budget for single-pass context-packed refactors
PYAGENT_LOG_LEVEL	INFO	Log level
PYAGENT_DOCS_PATH	<repo>/docs/python	Directory of .md files indexed for RAG

Knowledge Base

The agent's opinions are codified in six documents under docs/python/:

Document	Purpose
python_standards.md	Language-level style, idioms, and conventions
tech_stack.md	Preferred tools and libraries with rationale
anti_patterns.md	Code smells and mistakes to flag
refactoring_playbook.md	Named patterns with before/after examples
architecture_patterns.md	Module design, DI, and structural best practices
review_rubric.md	Severity levels, scoring dimensions, output format

These docs are retrieved via RAG at runtime, so you can edit them to tune the agent's behavior without touching code.

Development

# Install with dev dependencies (from the workspace root or from this package).
uv sync --extra dev

# Run this package's tests.
uv run pytest agents/fluent-pythonista/test_core.py -v

# Lint and format.
uv run ruff check agents/fluent-pythonista/
uv run ruff format agents/fluent-pythonista/

Related

• archagent — the architecture-advisor companion that lives in the same workspace.