Clarify uv tool install path on macOS (#1196)

## Description

Clarifies the recommended install path for the Headroom CLI on macOS
Apple Silicon and Linux. The docs now prefer `uv tool install --python
3.13 "headroom-ai[all]"` for host-level CLI use, keep `pip install`
scoped to Python project environments, and call out absolute executable
paths for MCP clients that do not inherit interactive shell `PATH`.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Added `uv tool install --python 3.13` guidance to the README, docs
install page, quickstarts, and wiki install pages.
- Documented `uv tool update-shell` for shells that cannot find the
installed `headroom` command.
- Clarified absolute MCP server command paths for clients that do not
inherit the interactive shell `PATH`.
- Pointed Intel macOS users at the Docker-native install path until
native wheel support lands.

## Testing

Describe the tests you ran to verify your changes:

- [ ] Unit tests pass (`pytest`) - not run; docs-only change.
- [ ] Linting passes (`ruff check .`) - not run; docs-only change.
- [ ] Type checking passes (`mypy headroom`) - not run; docs-only
change.
- [ ] New tests added for new functionality - not applicable.
- [x] Manual testing performed
- [x] `git diff --check upstream/main...HEAD`

## Real Behavior Proof

```bash
$ git diff --check upstream/main...HEAD
# exits 0; no whitespace errors
```

`npm --prefix docs run types:check` was also attempted. It regenerated
MDX and route types successfully, then failed in existing docs app code
because `@/lib/...` imports cannot resolve from files such as
`app/(home)/layout.tsx`, `app/api/search/route.ts`, and
`components/button.tsx`. This PR only changes `README.md`,
`docs/content/docs/installation.mdx`,
`docs/content/docs/quickstart.mdx`, and `wiki/*.md` files.

## Review Readiness

- [x] Draft PR; docs wording and install-path accuracy are ready for
review.
- [x] No code or runtime files changed.
- [x] Known docs type-check blocker is documented above.

## Test Output

```bash
$ git diff --check upstream/main...HEAD
# no output
```

```text
$ npm --prefix docs run types:check
[MDX] generated files
✓ Types generated successfully
app/(home)/layout.tsx(2,29): error TS2307: Cannot find module @/lib/layout.shared or its corresponding type declarations.
...
components/button.tsx(4,20): error TS2307: Cannot find module @/lib/cn or its corresponding type declarations.
```

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- not applicable; docs-only change.
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works - not applicable; docs-only change.
- [ ] New and existing unit tests pass locally with my changes - not
run; docs-only change.
- [ ] I have updated the CHANGELOG.md if applicable - not applicable.

## Screenshots (if applicable)

Not applicable.

## Additional Notes

The PR remains a draft while docs verification is limited by the
existing docs app `@/lib/*` resolution issue.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>

README.md

@@ -89,9 +89,9 @@ Headroom compresses everything your AI agent reads — tool outputs, logs, RAG c
 
 ```bash
 # 1 — Install
-uv tool install "headroom-ai[all]"      # Install `headroom` CLI as a global tool in self-contained virtual env
-pip install "headroom-ai[all]"          # Python — ships the `headroom` CLI
-npm install headroom-ai                 # TypeScript SDK only — no `headroom` CLI
+uv tool install --python 3.13 "headroom-ai[all]"  # CLI as a global tool in a self-contained virtual env
+pip install "headroom-ai[all]"                    # Python — ships the `headroom` CLI
+npm install headroom-ai                           # TypeScript SDK only — no `headroom` CLI
 
 # 2 — Pick your mode  (the `headroom` commands below come from the uv or pip install)
 headroom deploy                         # turnkey local deployment + agent config
@@ -362,8 +362,9 @@ Everything in this repo stays open source (Apache 2.0). The managed offering is
 ## Install
 
 ```bash
-pip install "headroom-ai[all]"          # Python, everything — includes the `headroom` CLI
-npm install headroom-ai                 # TypeScript SDK (library only — no `headroom` CLI)
+uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
+pip install "headroom-ai[all]"                    # Python, everything — includes the `headroom` CLI
+npm install headroom-ai                           # TypeScript SDK (library only — no `headroom` CLI)
 docker pull ghcr.io/chopratejas/headroom:latest
 ```
 
@@ -371,6 +372,25 @@ Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`, `[memo
 
 > **Note**: `[all]` covers the core stack but excludes framework adapters. Install them separately: `pip install "headroom-ai[langchain]"` (also `[agno]`, `[strands]`, `[anyllm]`, `[bedrock]`).
 
+Using `uv` for the `headroom` CLI? Prefer `uv tool install` so the command lives in an isolated app environment. On macOS, pass `--python 3.13` if your default `python3` is newer than the current wheel set:
+
+```bash
+brew install python@3.13  # if Python 3.13 is not already available
+uv tool install --python 3.13 "headroom-ai[all]"
+uv tool update-shell      # if ~/.local/bin is not already on PATH
+headroom --version
+```
+
+For MCP clients such as Codex that do not inherit your interactive shell `PATH`, configure the absolute executable path returned by `command -v headroom`:
+
+```toml
+[mcp_servers.headroom]
+command = "/Users/you/.local/bin/headroom"
+args = ["mcp", "serve"]
+```
+
+Current native wheels cover macOS Apple Silicon and Linux. On Intel macOS, use Docker-native install until native wheel support lands.
+
 Using `pipx`? Choose a supported interpreter explicitly:
 
 ```bash

docs/content/docs/installation.mdx

@@ -7,6 +7,8 @@ description: Install Headroom via pip, npm, or Docker. Includes all Python extra
 
 ## Install options
 
+**uv tool** - you want the `headroom` CLI (`proxy`, `wrap`, `mcp`, `learn`, `perf`) installed once on your machine in an isolated app environment.
+
 **pip** - you're writing Python, or you need the CLI (`headroom proxy`, `wrap`, `mcp`, `learn`, `perf`), regardless of what language your app is in.
 
 **npm** - you're writing TypeScript/Node and want inline `compress()`, SDK wrapping (`withHeadroom`), or Vercel AI SDK middleware.
@@ -20,6 +22,49 @@ Current release wheels are built for Python **3.10 through 3.13** on Linux
 from the sdist and need a working native toolchain. If your installer is
 using a newer Python, force a supported interpreter.
 
+### CLI install with uv
+
+For a host-level `headroom` command on macOS Apple Silicon or Linux, prefer
+`uv tool install`. It keeps Headroom in a dedicated app environment instead of
+tying it to the current project or shell Python.
+
+```bash
+uv tool install --python 3.13 "headroom-ai[all]"
+headroom --version
+```
+
+On macOS with Homebrew, `python3` may point at a newer interpreter than the
+current Headroom wheel set. Passing `--python 3.13` keeps installation on a
+wheel-supported interpreter. If Python 3.13 is missing, install it with
+Homebrew or let uv download a managed interpreter:
+
+```bash
+brew install python@3.13
+uv tool install --python 3.13 "headroom-ai[all]"
+```
+
+If `headroom` is installed but your shell cannot find it, add uv's tool
+directory to `PATH`:
+
+```bash
+uv tool update-shell
+```
+
+For MCP clients such as Codex that do not inherit your interactive shell
+`PATH`, configure the absolute executable path returned by `command -v
+headroom`:
+
+```toml
+[mcp_servers.headroom]
+command = "/Users/you/.local/bin/headroom"
+args = ["mcp", "serve"]
+```
+
+Native Intel macOS installs are currently tracked in
+[chopratejas/headroom#525](https://github.com/chopratejas/headroom/issues/525).
+Use [Docker-Native Install](/docs/docker-install) on Intel Macs until native
+wheel support lands.
+
 ### Core package
 
 ```bash
@@ -103,7 +148,8 @@ Windows wheels are tracked in [#636](https://github.com/chopratejas/headroom/iss
 unsupported Python version, `pipx` may resolve an older compatible Headroom
 release instead of the newest one.
 
-Use Python 3.13 explicitly:
+Use Python 3.13 explicitly. If you already use uv, prefer the
+[`uv tool`](#cli-install-with-uv) path above.
 
 ```bash
 pipx install --python python3.13 "headroom-ai[all]"
@@ -257,7 +303,7 @@ python3 --version
 If needed (Mac with Homebrew):
 
 ```bash
-brew install python@3.11
+brew install python@3.13
 ```
 
 ### Editable install fails (`pip install -e`)

docs/content/docs/quickstart.mdx

@@ -15,6 +15,10 @@ npm install headroom-ai
 </Tab>
 <Tab value="Python">
 ```bash
+# CLI/proxy/wrap on your machine
+uv tool install --python 3.13 "headroom-ai[all]"
+
+# Python project or virtualenv
 pip install "headroom-ai[all]"
 ```
 </Tab>
@@ -24,7 +28,8 @@ pip install "headroom-ai[all]"
 The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the TS SDK:
 
 ```bash
-pip install "headroom-ai[proxy]"
+uv tool install --python 3.13 "headroom-ai[proxy]"
+# or, inside a Python project: pip install "headroom-ai[proxy]"
 headroom proxy --port 8787
 ```
 

wiki/getting-started.md

@@ -4,20 +4,30 @@ This guide will help you get up and running with Headroom in under 5 minutes.
 
 ## Installation
 
-**Python:**
+**CLI on macOS Apple Silicon/Linux with uv:**
+
+```bash
+uv tool install --python 3.13 "headroom-ai[all]"
+headroom --version
+```
+
+Use `uv tool update-shell` if the install succeeds but `headroom` is not on
+`PATH`.
+
+**Python project / virtualenv:**
 
 ```bash
 # Core package (minimal dependencies)
 pip install headroom-ai
 
 # With proxy server
-pip install headroom-ai[proxy]
+pip install "headroom-ai[proxy]"
 
 # With semantic relevance (for smarter compression)
-pip install headroom-ai[relevance]
+pip install "headroom-ai[relevance]"
 
 # Everything
-pip install headroom-ai[all]
+pip install "headroom-ai[all]"
 ```
 
 **TypeScript / Node.js:**

wiki/index.md

@@ -64,7 +64,7 @@ Headroom works as a **transparent proxy** (zero code changes), a **Python functi
 === "Proxy (Zero Code Changes)"
 
     ```bash
-    pip install "headroom-ai[all]"
+    uv tool install --python 3.13 "headroom-ai[all]"
     headroom proxy
     ```
 
@@ -391,6 +391,7 @@ Or via LiteLLM for 100+ providers (Together, Groq, Fireworks, Ollama, vLLM, etc.
 ## Installation
 
 ```bash
+uv tool install --python 3.13 "headroom-ai[all]"  # CLI on macOS Apple Silicon/Linux
 pip install headroom-ai                # Core library (Python)
 pip install "headroom-ai[all]"         # Everything (recommended)
 npm install headroom-ai                # TypeScript / Node.js
@@ -401,7 +402,8 @@ pip install "headroom-ai[agno]"        # Agno integration
 pip install "headroom-ai[evals]"       # Evaluation framework
 ```
 
-Requires Python 3.10+.
+Requires Python 3.10+. On macOS, use Python 3.13 for the uv/pipx CLI path if
+your default `python3` is newer than the current wheel set.
 
 ---
 

wiki/macos-deployment.md

@@ -22,13 +22,24 @@ This is ideal for local development environments where you want "set and forget"
 ### Installing Headroom with Proxy Support
 
 ```bash
-# Install with proxy support
-pip install headroom-ai[proxy]
+# Install the host CLI with proxy support
+uv tool install --python 3.13 "headroom-ai[proxy]"
+
+# If your shell cannot find `headroom` after installation
+uv tool update-shell
 
 # Verify installation
 headroom proxy --help
 ```
 
+On macOS with Homebrew, `python3` may point at a newer interpreter than the
+current Headroom wheel set. Passing `--python 3.13` keeps the CLI install on a
+wheel-supported interpreter. If Python 3.13 is missing, install it first:
+
+```bash
+brew install python@3.13
+```
+
 ### API Key Configuration
 
 Your Anthropic API key can be configured in several ways:
@@ -390,7 +401,7 @@ tail -n 50 ~/Library/Logs/headroom/proxy-error.log
 | Error | Solution |
 |-------|----------|
 | `ANTHROPIC_API_KEY not set` | Set API key in environment or plist |
-| `ModuleNotFoundError: No module named 'headroom'` | Install: `pip install headroom-ai[proxy]` |
+| `ModuleNotFoundError: No module named 'headroom'` | Install: `uv tool install --python 3.13 "headroom-ai[proxy]"` |
 | `command not found: headroom` | Update plist with correct path: `command -v headroom` |
 | `Address already in use` | Change port or stop conflicting service |
 
@@ -421,7 +432,7 @@ tail -f ~/Library/Logs/headroom/proxy-error.log
 
 **Common causes:**
 
-- Missing dependencies: `pip install headroom-ai[proxy]`
+- Missing dependencies: `uv tool install --python 3.13 "headroom-ai[proxy]"`
 - Invalid API key: Verify `ANTHROPIC_API_KEY`
 - Python version incompatible: Requires Python 3.10+
 

wiki/quickstart.md

@@ -6,7 +6,17 @@ Get Headroom running in 5 minutes with these copy-paste examples.
 
 ## Installation
 
-**Python:**
+**CLI on macOS Apple Silicon/Linux with uv:**
+
+```bash
+uv tool install --python 3.13 "headroom-ai[all]"
+headroom --version
+```
+
+Use `uv tool update-shell` if the install succeeds but `headroom` is not on
+`PATH`.
+
+**Python project / virtualenv:**
 
 ```bash
 # Core only (minimal dependencies)