Agents fall back to 'source .venv/bin/activate && diffctx' instead of pipx-installed binary

[nikolay-e]

Symptom observed

A parallel Claude Code /qa session running ~/yay-tsa was caught running:

source /Users/nikolay/diffctx/.venv/bin/activate && diffctx --diff HEAD~3..HEAD -f yaml
source /Users/nikolay/diffctx/.venv/bin/activate && diffctx --diff -f yaml

instead of the pipx-installed binary at /Users/nikolay/.local/bin/diffctx. The dev venv was reachable, the agent picked it.

Why it matters

1. Drift. The venv runs a working-tree build that doesn't match any published version — bugs observed there can't be reproduced from any tagged release.
2. Shell mutation. source activate persists for the rest of the bash session and silently changes PATH, PYTHONHOME, etc. for every subsequent command in the same shell.
3. Onboarding signal. Multiple independent agents reaching for the venv suggests the install/discovery path is not as obvious as it should be.

Reproduction

1. Fresh claude --dangerously-skip-permissions in any project directory.
2. Ask it to run a diffctx extraction with pipx install diffctx NOT already done.
3. Observe the agent walking the filesystem and finding the dev venv at ~/diffctx/.venv rather than offering pipx install diffctx.

Suggested fixes (any one helps)

• README: lead with pipx install diffctx as the canonical one-liner above all other install methods; explicitly say "do not source the project venv for non-dev use".
• diffctx --version first line in CI/Action contexts could check __file__ against typical venv paths under user home and warn "diffctx is running from a project-local venv (...). For reproducible runs install with pipx install diffctx.".
• GitHub Action (nikolay-e/diffctx-claude-code-review-action): already installs via pip install diffctx inside a Docker image — no venv-sourcing issue there. The problem is local agent runs.

Reference

Caught while migrating treemapper-claude-code-review-action → diffctx-claude-code-review-action. Skill rule added at ~/.claude/commands/qa.md ## Code review / diffctx mandates pipx-binary and flags any venv-source as a finding that files this issue.