Use Interceptors to teach Claude Code to use uv

AI coding agents like Claude Code, Cursor, or GitHub Copilot often default to using system Python interpreters instead of using uv.

Armin Ronacher, creator of Flask and Jinja, shared an elegant solution to this problem: creating dummy Python interpreter that actively redirect AI agents toward better tooling choices.

The Interceptor Solution

Ronacher’s approach involves creating fake python executables that intercept agent commands and provide helpful error messages. Here’s how to implement this pattern on a per-project basis using direnv.

mkdir -p ~/.local/bin/interceptors

#!/bin/bash
echo "❌ Direct python usage detected!"
echo ""
echo "🤖 AI Agent Instructions:"
echo "Instead of 'python script.py', use:"
echo "  uv run script.py"
echo ""
echo "Instead of 'pip install package', use:"
echo "  uv add package"
echo ""
echo "For interactive Python, use:"
echo "  uv run python"
echo ""
echo "This ensures proper dependency isolation and project management."
exit 1

chmod +x ~/.local/bin/interceptors/python

# python3 dummy
#!/bin/bash
echo "❌ Direct python3 usage detected!"
echo "🤖 Use 'uv run python' instead for proper environment management."
exit 1

# pip dummy  
#!/bin/bash
echo "❌ Direct pip usage detected!"
echo "🤖 Use 'uv add <package>' or 'uv pip install <package>' instead."
exit 1

# Prepend our dummy scripts to PATH for this project
PATH_add $HOME/.local/bin/interceptors

direnv allow

How It Works in Practice

When an AI agent tries to run python script.py within your project directory, instead of executing the system Python, it encounters your dummy script:

$ python hello.py
❌ Direct python usage detected!

🤖 AI Agent Instructions:
Instead of 'python script.py', use:
  uv run script.py

Instead of 'pip install package', use:  
  uv add package

For interactive Python, use:
  uv run python

This ensures proper dependency isolation and project management.

This immediate feedback trains the AI agent to use better patterns in subsequent interactions.

Quick Setup

For convenience, you can set up the interceptors automatically using a single command:

curl -fsSL "https://pydevtools.com/scripts/setup-uv-interceptor.sh" | sh

This script will:

1. Check prerequisites: Verify that direnv is installed
2. Create interceptor scripts: Set up the dummy python, python3, and pip executables in ~/.local/bin/interceptors/
3. Configure the project: Add the interceptor path to your .envrc file
4. Activate direnv: Automatically run direnv allow for the current directory
5. Test the setup: Verify that the interceptors are working correctly

The interceptors are created once in your home directory but configured per-project through individual .envrc files. To add interceptors to additional projects, simply run the script again in those project directories.

After running the script, you should see output similar to:

🛠️  Setting up AI Agent Python Interceptors

[INFO] direnv is installed
[INFO] Created interceptor directory: ~/.local/bin/interceptors
[INFO] Created python interceptor: ~/.local/bin/interceptors/python
[INFO] Created python3 interceptor: ~/.local/bin/interceptors/python3
[INFO] Created pip interceptor: ~/.local/bin/interceptors/pip
[INFO] Added interceptor PATH to existing .envrc
[INFO] Allowed direnv for current directory

🎉 Setup Complete!

You can run it multiple times safely, and it will only make necessary changes.

Learn More

• Use CLAUDE.md to configure uv