claude-interceptors for coding agents

tl;dr

install:	`curl -sSL https://raw.githubusercontent.com/mjbommar/claude-interceptors/master/install.sh \| bash`
what:	teaches coding agents to stop using pip and use uv instead
agents:	claude code, gemini cli, codex, any llm with tool use
fixes:	pip → uv, black → ruff, pylint → ruff, mypy → ty
result:	agents learn modern tools, code runs 10-100x faster

overview

claude code keeps suggesting pip install. gemini cli runs black on every file. codex still thinks virtualenv is the way. they learned from documentation written before these tools were replaced by faster alternatives.

claude-interceptors fixes this. when an agent runs pip install, the interceptor stops it and explains that uv is 10-100x faster. the agent sees the message, adjusts its approach, and uses the modern tool instead.

installation

quick install

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

# restart terminal or run
source ~/.bashrc

# enable for current session
claude-interceptor-enable

# verify it's working
pip --help  # should show interceptor message

management commands

# enable/disable per session
claude-interceptor-enable    # turn on interceptors
claude-interceptor-disable   # turn off interceptors

# check status
claude-interceptor-status    # show if enabled and installed

# update to latest
claude-interceptor update

# uninstall completely
claude-interceptor uninstall

how agents see it

when claude code or another agent runs an outdated command:

$ pip install pandas
❌ Direct pip install detected!

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

🔧 To proceed anyway:
  pip install pandas --force
  CLAUDE_INTERCEPTOR_BYPASS=1 pip install pandas

the agent reads this output, learns the correct command, and adjusts. next time, it uses uv add directly.

intercepted commands

package management

pip → uv

# old way
pip install requests
pip install -r requirements.txt

# interceptor suggests
uv add requests                  # add to project
uv pip install requests          # temporary install
uv pip sync requirements.txt     # faster requirements install

virtualenv → uv venv

# old way
virtualenv myenv
python -m venv myenv

# interceptor suggests
uv venv myenv       # 10-100x faster
python -m venv myenv  # built-in alternative

code formatting

black → ruff format

# old way (slow)
black src/

# interceptor suggests (10-30x faster)
ruff format src/

linting

pylint/flake8 → ruff

# old way (very slow)
pylint src/
flake8 src/

# interceptor suggests (100x faster)
ruff check src/

isort → ruff

# old way
isort .

# interceptor suggests
ruff check --select I --fix .

type checking

mypy/pyright → ty

# old way
mypy src/
pyright .

# interceptor suggests (10-100x faster)
ty src/
ty .

agent behavior examples

claude code workflow

claude code trying to set up a project:

# claude suggests
$ pip install -r requirements.txt

# interceptor teaches
❌ Direct pip install detected!
🤖 AI Agent Instructions:
  📦 uv pip sync requirements.txt  # 10-100x faster

# claude adjusts and uses
$ uv pip sync requirements.txt

gemini cli formatting

gemini trying to format code:

# gemini runs
$ black src/ --line-length 88

# interceptor educates
❌ black usage detected!
🤖 AI Agent Instructions:
  ⚡ ruff format src/  # 10-30x faster, same output

# gemini learns
$ ruff format src/

when agents need bypass

some packages only work with pip:

# agent can use --force when necessary
pip install weird-internal-package --force

# or set environment variable
CLAUDE_INTERCEPTOR_BYPASS=1 pip install legacy-tool

configuration

per-session control

interceptors only affect the current terminal:

# terminal 1
claude-interceptor-enable
pip install requests  # shows interceptor

# terminal 2
pip install requests  # normal pip

permanent setup

for quick access:

# add to ~/.bashrc
alias ci-on='claude-interceptor-enable'
alias ci-off='claude-interceptor-disable'

# toggle as needed
ci-on   # interceptors on
ci-off  # interceptors off

why agents need this

training data problem

claude was trained on stackoverflow answers from 2021. gemini learned from tutorials using pip and virtualenv. codex studied millions of repos that used black and pylint.

none of them know about uv (2024) or that ruff replaced five different tools. the interceptors fill this knowledge gap.

agent adaptation

agents are good at learning from error messages. when they see the interceptor output, they immediately understand and adjust. this creates a feedback loop that improves their suggestions over time.

performance gains

the speed differences are real:

old tool	new tool	improvement
pip	uv	10-100x
black	ruff format	10-30x
pylint	ruff check	100x
mypy	ty	10-100x
virtualenv	uv venv	10-100x

troubleshooting

interceptor not working

# check status
claude-interceptor-status

# verify PATH
echo $PATH | grep claude-interceptors

# reinstall
claude-interceptor uninstall
curl -sSL .../install.sh | bash

conflicts

# disable temporarily
claude-interceptor-disable

# or bypass one command
pip install package --force

other shells

bash only for now. for zsh:

# add to ~/.zshrc
alias claude-interceptor-enable='source <(claude-interceptor enable)'
alias claude-interceptor-disable='source <(claude-interceptor disable)'

design for agents

the interceptors are built specifically for ai agents:

clear error format - agents parse error messages well
explicit instructions - tells agents exactly what command to use
bypass options - agents can use --force when needed
learning-friendly - each message teaches the modern alternative

agents see these as helpful errors that guide them to better commands, not as blocking failures.