claude-interceptors | mike bommarito

claude-interceptors intercepts outdated python commands and suggests modern alternatives. it’s particularly useful for training ai agents to use the right tools and helping developers discover faster replacements for traditional python workflows.

problem it solves

ai agents frequently suggest outdated python commands like pip install or virtualenv because they were trained on old documentation. developers also stick with slow tools like black and pylint out of habit. this creates slow, fragmented workflows when better alternatives exist.

the interceptors educate both agents and humans by:

catching old commands before they run
suggesting modern, faster alternatives with clear explanations
providing context about why the new tools are better
always allowing bypass when needed

how it works

when you run pip install requests, instead of installing, you see:

❌ Direct pip install detected!

🤖 AI Agent Instructions:
  Choose the right uv command for your use case:
  📦 uv add requests                    # Add to pyproject.toml dependencies
  📦 uv add --group dev requests        # Add to dev dependency group
  📦 uv pip install requests            # Temporary install (no pyproject.toml change)

🔧 To proceed anyway:
  pip install requests --force

intercepted commands

the tool intercepts these commands and their modern replacements:

pip → uv add or uv pip (10-100x faster)
python script.py → uv run script.py (better dependency management)
virtualenv → uv venv (no extra dependencies)
black → ruff format (10-30x faster)
pylint/flake8 → ruff check (100x faster)
mypy/pyright → ty (rust-based type checking)
isort → ruff check --select I --fix (built into ruff)

installation

# one-line install
curl -sSL https://raw.githubusercontent.com/mjbommar/claude-interceptors/master/install.sh | bash

# restart terminal or source bashrc
source ~/.bashrc

# enable for current session
claude-interceptor-enable

# test it
pip install requests  # will show interceptor message

design philosophy

the interceptors are designed to be educational rather than restrictive. they never prevent you from running the original command (just add --force), and they can be enabled or disabled per session. this makes them safe for production environments while still providing value during development.

currently supports bash with the core interceptors working in any shell. the architecture is simple bash scripts that check for bypass flags, provide helpful suggestions, and exit with a non-zero code to prevent accidental execution.