# 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](https://pydevtools.com/handbook/reference/uv.md).

[Armin Ronacher, creator of Flask and Jinja, shared an elegant solution to this problem](https://x.com/mitsuhiko/status/1949093355373142400): creating dummy Python interpreter that actively redirect AI agents toward better tooling choices.

> [!TIP]
> Understanding [why you should use virtual environments](https://pydevtools.com/handbook/explanation/why-should-i-use-a-virtual-environment.md) is crucial for maintainable Python development.

## The Interceptor Solution

Ronacher's approach involves creating fake `python` executables that intercept agent commands and provide helpful error messages. Here is how to implement this pattern on a per-project basis using [direnv](https://pydevtools.com/handbook/reference/direnv.md).

### Creating the Python Interpreter

First, create a directory for your dummy interpreters within your project:

```bash
mkdir -p ~/.local/bin/interceptors
```

Create a dummy `python` shell script in `~/.local/bin/interceptors/python`:

```bash
#!/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
```

Make it executable:

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

Create similar scripts for `python3` and `pip` and make them executable:

```bash
# 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
```

### Configuring direnv

> [!NOTE]
> [First install and configure direnv](https://direnv.net/docs/installation.html).

Create or update your `.envrc` file in the project root:

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

Allow direnv to load the configuration:

```bash
direnv allow
```

Now whenever you enter this project directory, the dummy scripts will be prioritized in your PATH, but only for this specific project.

## 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:

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

This script will:

1. Check prerequisites: Verify that [direnv](https://pydevtools.com/handbook/reference/direnv.md) 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](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-to-use-uv.md)