dotfiles/claude/memory/feedback-tool-installation-pipx-default.md

name, description, type, originSessionId

name	description	type	originSessionId
General-purpose Python CLI tools install via pipx, not per-tool venvs	For Python tools the steward uses as commands (docling, ruff, black, ansible, etc.), prefer pipx over creating dedicated venvs. pipx isolates dependencies under the hood while putting the CLI on PATH globally — same shape as Homebrew tools.	feedback	a5411fd1-4a96-43e7-aa1a-1a50d8951a8f

For Python CLI tools that belong in the steward's general toolset, install via pipx, not in a per-tool venv:

brew install pipx
pipx ensurepath
pipx install <tool>

End state: tool is a regular shell command (docling input.epub -o output.md) alongside Homebrew binaries like pandoc, mempalace. Each has its own isolated environment under the hood — same isolation benefit as a venv, without requiring the steward to activate one to use the tool.

Why: Steward's direct articulation (2026-05-13): "Not better to install it as part of my general toolset?" and "Please remember this for future critical tools. I don't understand why we need venv containers for some tools, I'll admit." The asymmetric ergonomic cost of activating a venv every time vs having the tool on PATH is real, especially for tools used across projects.

How to apply:

• pipx (default for CLI tools) — anything the steward invokes as a command from anywhere. docling, ruff, black, mypy, ansible, poetry, etc. Goes on PATH globally; isolated under the hood.
• Per-project venv — only when (a) the steward (or I) is developing the tool itself (editable install via pip install -e, so source-tree edits take effect immediately — this is why mempalace lives in ~/_Dev/mempalace/.venv/), (b) we're A/B testing competing versions side-by-side (like mempalace-pr442-venv vs mempalace-3.3.5-bge-m3-venv), or (c) the project explicitly requires dependency isolation that pipx can't provide.
• System Python (pip install --user) — rarely the right answer; pollutes system site-packages and is hard to clean up. Avoid.
• Homebrew direct — if the tool has a Homebrew formula (e.g., pandoc, pipx itself), that's the cleanest. Check brew search <tool> before defaulting to pipx.

When unsure, the question to ask: "Is the steward going to invoke this as a command from outside any specific project?" If yes → pipx. If the answer is "only inside the project source tree, while modifying that source tree" → per-project venv.