Metadata-Version: 2.4
Name: venv-proxy
Version: 0.1.0
Summary: Automatic virtual environment resolution — never type 'source .venv/bin/activate' again
License: MIT License
        
        Copyright (c) 2026 venv-proxy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/JulienPoitou/venv-proxy
Project-URL: Issues, https://github.com/JulienPoitou/venv-proxy/issues
Keywords: virtualenv,venv,python,devtools,AI agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# venv-proxy

[![Tests](https://github.com/JulienPoitou/venv-proxy/actions/workflows/test.yml/badge.svg)](https://github.com/JulienPoitou/venv-proxy/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/venv-proxy.svg)](https://pypi.org/project/venv-proxy/)
[![Python](https://img.shields.io/pypi/pyversions/venv-proxy.svg)](https://pypi.org/project/venv-proxy/)
[![License](https://img.shields.io/pypi/l/venv-proxy.svg)](https://github.com/JulienPoitou/venv-proxy/blob/main/LICENSE)

**Never type `source .venv/bin/activate` again.**

Not you. Not your AI agent.

```bash
pip install venv-proxy
venv-proxy install
```

That's it. From now on, `python` and `pip` automatically use the right `.venv` — in any directory, in any shell, for any process.

---

## The problem

Every Python project has a `.venv`. Activating it is a manual step that breaks constantly:

```bash
# You forget it. Your agent ignores it. CI doesn't have it.
source .venv/bin/activate  # ← this shouldn't exist
```

When skipped, `pip install` pollutes your global Python. Dependencies conflict. Projects break silently.

**AI coding agents (Claude Code, Cursor, Copilot) make this worse.** They execute shell commands without TTY activation. They ignore your `CLAUDE.md` instructions. They install packages wherever they want.

[Real issue: anthropics/claude-code #9368](https://github.com/anthropics/claude-code/issues/9368) — duplicated 4 times, still open.

---

## How it works

venv-proxy installs lightweight shims for `python`, `python3`, `pip`, and `pip3` at the front of your PATH.

When invoked from any directory, each shim:

1. Walks up the filesystem from your current directory
2. Finds the nearest `.venv/bin/` folder
3. Replaces itself with the correct binary via `execv()` — **zero overhead, fully transparent**
4. Falls back to system Python if no `.venv` is found

```
my-project/
├── .venv/          ← found automatically
│   └── bin/
│       ├── python  ← used by shim
│       └── pip     ← used by shim
├── src/
│   └── main.py
└── tests/
    └── test_main.py  ← python here uses .venv too
```

---

## Install

```bash
pip install venv-proxy
venv-proxy install

# Add to your shell profile if not already there:
export PATH="$HOME/.local/bin:$PATH"
```

---

## Usage

```bash
# Before venv-proxy:
cd my-project
source .venv/bin/activate   # don't forget!
pip install requests         # now in .venv
python main.py

# After venv-proxy:
cd my-project
pip install requests         # automatically in .venv ✓
python main.py               # automatically uses .venv ✓
```

Works the same for AI agents — no config, no CLAUDE.md instructions needed.

---

## Commands

```bash
venv-proxy install     # install shims into ~/.local/bin
venv-proxy uninstall   # remove shims
venv-proxy status      # show which venv would be used from CWD
venv-proxy doctor      # diagnose PATH and shim issues
```

---

## Debug mode

```bash
VENV_PROXY_DEBUG=1 python script.py
# venv-proxy: using /home/user/my-project/.venv/bin/python
```

---

## FAQ

**Does it work with `uv`?**  
Yes. venv-proxy resolves `.venv/bin/python` regardless of how the venv was created (venv, virtualenv, uv, poetry).

**What if there's no `.venv`?**  
Falls back to system Python transparently.

**Does it slow things down?**  
No. It uses `os.execv()` which replaces the current process — there's no subprocess or wrapper overhead.

**Does it work in CI?**  
Yes. Any process that calls `python` or `pip` gets the right venv automatically.

**Windows?**  
Not yet. Linux and macOS only for now.

---

## Requirements

- Python 3.9+
- Linux or macOS

---

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.

---

## License

MIT

---

*Built because [this GitHub issue](https://github.com/anthropics/claude-code/issues/9368) has been open too long.*
