Python Developer Tooling Handbook – AI Assistants

Claude Code for Python: A Complete Guide

Tim Hopper — Wed, 06 May 2026 06:23:27 -0400

Claude Code is a terminal-based AI assistant that reads your files, runs commands, edits code, and iterates on errors. Describe what you want in plain English, and Claude Code determines which files to read, which commands to run, and what code to write. When something breaks, it reads the error, adjusts, and tries again.

This guide covers how to use Claude Code for Python development specifically. Each section is self-contained, so skip to whatever is relevant.

Getting Started with Python Using Codex

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Codex CLI is OpenAI’s terminal-based coding agent. It reads your repository, edits files, runs commands, and iterates on errors, all from your terminal. Describe what you want in plain English, and Codex decides which files to read, which commands to run, and what code to write.

What separates Codex from other terminal agents is how it sandboxes every command the model runs. Codex isolates execution with OS-level enforcement (Seatbelt on macOS, Landlock and seccomp on Linux), not just application-layer checks. This means you can grant Codex more autonomy without worrying that a bad command will reach beyond your project directory or make network calls you didn’t authorize.

Enough Git to Supervise Your AI Coding Agent

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

AI coding agents like Claude Code, Codex, Cursor, and GitHub Copilot run Git commands on your behalf. You don’t need to memorize those commands, but you do need to understand what they mean. Otherwise you’re approving operations you can’t verify.

When your agent says “I’ve committed the changes and pushed to GitHub,” you should know where those changes went and how to undo them if something is wrong. This article provides that mental model. A companion how-to guide walks through putting your project on GitHub for the first time.

How to configure Claude Code to use uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code defaults to pip when it needs to install packages or run scripts. A CLAUDE.md file in your project root overrides that default so every session uses uv instead.

Tip

How to configure Claude Code to use virtual environments

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code starts a fresh shell for every Bash tool call, so source .venv/bin/activate in one command has no effect on the next. Without configuration, Claude reaches for system Python and installs packages outside the project’s virtual environment. Four configuration patterns work around the stateless-shell limitation:

uv run for projects on uv, which sidesteps activation entirely
A CLAUDE.md instruction that tells Claude to call the venv’s interpreter directly
A .claude/settings.json env block that pre-sets VIRTUAL_ENV and PATH for every session
A PreToolUse hook that blocks bare python and pip so the rules are enforced, not just suggested

Trace why `source activate` doesn’t persist

Each Bash tool call Claude Code runs spawns a separate shell process. Environment changes made by source .venv/bin/activate (it sets VIRTUAL_ENV and prepends .venv/bin to PATH) live only inside that shell. When the next tool call starts a new shell, those variables are gone.

How to configure Claude Code with a Python type checker

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

Claude Code does not run a Python type checker by default, and the gap is wider than it looks. Listing uv run ty check in CLAUDE.md looks like enough configuration, but Pyrefly’s documented agentic-loop pattern shows that models routinely skip the command unless the type checker is wrapped in a loop that runs after every edit. With the wrapper in place, the model engages with errors; without it, the model treats the checker as optional.

How to configure Cursor for a uv project

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

Cursor is a fork of VS Code, so most Python tooling configuration works the same way. The key difference is Cursor’s AI agent, which needs explicit rules to use uv instead of pip. This guide covers both the editor setup and the agent configuration.

How to configure Cursor rules to use uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide shows you how to configure Cursor editor rules to automatically use uv for Python package management instead of pip. Cursor rules help ensure consistent tooling across your development workflow by providing context to the AI about your project preferences.

Prerequisites

Cursor editor installed
uv installed on your system
A uv-based Python project (e.g. created with uv init)

Create Cursor rules to use uv

1. Create a global Cursor rules file

To apply uv rules across all your Python projects, create a global Cursor rules file by opening the Cursor Command Palette (View Menu → Command Palette), search for “New Cursor Rule”, and create a new rule named “uv”.

How to configure Ruff with Claude Code

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code does not run Ruff by default, so Python edits land unformatted and lint errors slip through unless you wire Ruff in yourself. Out of the box, Claude often calls bare ruff (which may resolve outside the project’s virtual environment) and skips formatting after edits. Wiring Ruff in correctly takes four layers, each with a different job.

This guide covers all four and how they stack together:

A CLAUDE.md instruction that points Claude at Ruff
The Astral plugin’s /astral:ruff skill for on-demand Ruff guidance
A PostToolUse hook that auto-formats every Python edit
A pre-commit gate that catches anything Claude missed before commit time

Prerequisites

Claude Code installed
uv installed
A Python project with Ruff added as a dev dependency (uv add --dev ruff)
jq installed if you want to use the shell version of the auto-format hook

Pick the right layer for your goal

Each layer answers a different question. Pick the ones that match what you actually need; nothing requires installing all four.

How to create a new Python project with Codex

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Codex produces consistent project scaffolding when you explicitly point it at the Modern Python Project Setup Guide for AI Assistants. Use the canonical Markdown URL (https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants/index.md) inside your first prompt so Codex follows the uv-based workflow on macOS, Linux, and Windows.

Launch Codex with the guide loaded

1. Open a terminal in your repository root

Codex works best when it starts in the directory that already contains your project files (or the Git repo where the project will live). On macOS/Linux you can cd /path/to/repo; on Windows use PowerShell’s Set-Location.

How to install the Astral plugins for Claude Code

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

Astral publishes an official Claude Code plugin that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Prerequisites

Claude Code installed
uv installed (required by the ty language server)

Install the plugin for yourself

1. Add the Astral marketplace

Run this slash command inside Claude Code:

How to Set Up CLAUDE.md for a Python Project

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code reads a CLAUDE.md file in your project root every session. Without one, it falls back to pip install, bare python commands, and setup.py.

The Python Developer Tooling Handbook maintains a CLAUDE.md template for Python projects using uv, Ruff, and pytest.

What the template covers

Package management with uv (uv add, uv run, uv sync instead of pip)
Project creation with uv init and pyproject.toml (never setup.py)
Testing with pytest (discovery conventions, file layout, execution)
Linting and formatting with ruff
Type checking with ty or mypy
Pre-commit hooks with prek or pre-commit
Anti-patterns Claude should avoid (manual venvs, pip install, requirements.txt)

At 86 lines, the template stays inside Anthropic’s recommended 200-line limit for CLAUDE.md files.

How to stop AI agents from bypassing pre-commit hooks

Tim Hopper — Fri, 15 May 2026 22:01:03 -0400

Claude Code can ship broken code by running git commit --no-verify to skip your pre-commit hooks. The behavior is documented and persistent: Anthropic’s claude-code issue #40117 describes Claude Code Opus 4.6 bypassing explicit deny rules and CLAUDE.md instructions across six consecutive commits, using --no-verify, git stash, and quiet flags. The issue was closed as “not planned,” which means defense comes from outside the agent.

This guide walks four enforcement layers plus a CI backstop:

How to use Python skills with Claude Code

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Skills bottle up your Python workflow. Instead of re-explaining “tighten these type annotations” or “use uv instead of pip” every session, save the procedure to a markdown file once and let Claude Code reach for it when you ask, either by slash command or by describing the task in plain English. Long reference material that would crowd a CLAUDE.md only loads when the skill runs.

This guide installs the Astral plugin, walks through writing a custom Python skill, and shows when a skill beats CLAUDE.md or a hook.

How to write Claude Code hooks for Python projects

Tim Hopper — Sat, 16 May 2026 06:16:22 -0400

Claude Code hooks are scripts that run at specific points during a session, letting you enforce project conventions programmatically. A CLAUDE.md file suggests how Claude should behave; hooks guarantee it by blocking disallowed commands, auto-formatting files, or injecting context before Claude sees your prompt. See the official hooks documentation for the full reference.

How hooks work

Hooks fire on events during a Claude Code session. Claude Code supports over 25 event types (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, and more). This guide covers the four most useful for Python projects:

Modern Python Project Setup Guide for AI Assistants

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

Important

For AI assistants: this guide is meant to be ingested directly. Paste it (or link it) into your project’s CLAUDE.md, AGENTS.md, .cursorrules, or .github/copilot-instructions.md so coding agents follow the same conventions you would. A plain markdown version is available for direct ingestion into agent contexts.

Python Developer Tooling Handbook – AI Assistants

Claude Code for Python: A Complete Guide

Getting Started with Python Using Codex

Enough Git to Supervise Your AI Coding Agent

How to configure Claude Code to use uv

How to configure Claude Code to use virtual environments

Trace why source activate doesn’t persist

How to configure Claude Code with a Python type checker

How to configure Cursor for a uv project

How to configure Cursor rules to use uv

Prerequisites

Create Cursor rules to use uv

1. Create a global Cursor rules file

How to configure Ruff with Claude Code

Prerequisites

Pick the right layer for your goal

How to create a new Python project with Codex

Launch Codex with the guide loaded

1. Open a terminal in your repository root

How to install the Astral plugins for Claude Code

Prerequisites

Install the plugin for yourself

1. Add the Astral marketplace

How to Set Up CLAUDE.md for a Python Project

What the template covers

How to stop AI agents from bypassing pre-commit hooks

How to use Python skills with Claude Code

How to write Claude Code hooks for Python projects

How hooks work

Modern Python Project Setup Guide for AI Assistants

Trace why `source activate` doesn’t persist