Make install work on PEP 668 systems + fix venv MCP-server wiring

[Neverdecel]

Why

The flagship one-liner and Quick start used a global pip install, which fails with error: externally-managed-environment on Debian/Ubuntu and other PEP 668 systems — the most common Linux setup, so nearly every new user hits it. Working around it with a venv then exposed a second, quieter trap in coderag install.

What

1. Docs — README.md

• Flagship one-liner now uses pipx, which installs CodeRAG into an isolated environment and puts coderag on PATH — exactly what an agent needs to launch the server. A blockquote covers installing pipx and the plain-pip + venv fallback for PEP 668.
• Quick start now leads with python3 -m venv .venv && source .venv/bin/activate, plus a note on the coderag install activation footgun (below).

2. Fix — coderag/install.py (_server_invocation)

coderag install recorded a bare coderag mcp whenever coderag was on PATH at install time — including an activated virtualenv, whose bin/coderag disappears once deactivated. The agent then launches the server from its own shell and can't find coderag.

Now it writes a bare coderag only when it's durably on PATH: a non-venv (system/user) install, or a launcher outside the current venv prefix (e.g. a pipx shim in ~/.local/bin). Inside a venv it pins this interpreter's coderag console script by absolute path — looked up lexically in sys.executable's bin dir so a venv's python symlink isn't followed back to the base interpreter — falling back to <python> -m coderag.surfaces.cli mcp. pipx and system installs still get a clean bare coderag.

Tests

Adds coverage for each resolution case in tests/test_install.py: system install, activated venv, venv-not-activated, pipx shim outside the venv, and the module fallback.

• pytest -m "not integration" — green (exit 0)
• ruff check . / ruff format --check . — clean
• mypy coderag — Success, no issues found in 40 source files

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2K45QFkrJEACjmWPwUvqY

---

Generated by Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!