## Description In `examples/deployment/macos-launchagent/install.sh` (lines 96-113 on `1da8930a`), when the plist already exists the script runs `launchctl bootout` on the running service first and only then asks `Reinstall? [y/N]`. Answering `N` prints `Installation cancelled.` and exits 0, but the service is already stopped, so a cancelled install leaves the proxy down until the next login or a manual `launchctl bootstrap`. This PR moves the stop block below the prompt, unchanged, so `bootout` runs only after the user confirmed, or in `--unattended` mode (which never prompts). Nothing else changes. Part of #4730 ## Type of Change - [x] 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) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `examples/deployment/macos-launchagent/install.sh`: the `launchctl print` / `launchctl bootout` block moves from before the `Reinstall?` prompt to after it, with a one-line comment. 6 lines moved, 1 comment added. ## Testing - [x] Unit tests pass (`pytest`) (the new test file only; I did not run the full suite) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed This is a shell example script, so the Python lint and type checks do not apply to it. The new test file is checked with ruff (below). The project's bug-fix policy asks for a test that fails before and passes after, so a committed test runs the real script against stubs (below), and the earlier manual driver is kept under it. ### Test Output #### Committed regression test `tests/test_macos_launchagent_install_cancel.py` runs the real `install.sh` under `bash` with stub `uname`, `launchctl`, `headroom` and `lsof` on `PATH` and a fake `HOME`. It is skipped when `bash` is not on `PATH`. Environment: Ubuntu on WSL2, bash, Python venv `/var/tmp/cb-fix-8mh5/repo/.venv`, pytest `-p no:cacheprovider`, test file run from a scratch copy (no `headroom` import, no repo conftest). Same test file, `install.sh` taken from `origin/main` (`1da8930a`): ```text FAILED test_declining_reinstall_keeps_the_service_running 1 failed, 1 passed in 0.14s (test_confirming_reinstall_stops_the_service passes: bootout is still called after y) ``` Same test file, `install.sh` from this branch: ```text 2 passed in 0.06s ``` `ruff format --check` and `ruff check` on the new file: clean. #### Earlier manual driver Driver: copies `install.sh` and the plist template into a scratch directory, puts stubs first on `PATH` (`uname` prints `Darwin`; `headroom` exits 0; `lsof` exits 1; `launchctl` appends each call to a log and exits 0, so `launchctl print` reports a running service), points `HOME` at a fake home that already contains `Library/LaunchAgents/com.headroom.proxy.plist`, and feeds stdin. Git Bash on Windows 11. Paths shortened to `<run>`; output filtered to the lines that matter. `origin/main` (`1da8930a`), `echo N | bash install.sh`: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ==> Stopping existing service... Installation cancelled. rc=0 --- launchctl call log: launchctl print gui/197609/com.headroom.proxy launchctl bootout gui/197609/com.headroom.proxy ``` This branch, `echo N | bash install.sh`: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist Installation cancelled. rc=0 --- launchctl call log: (no calls) ``` This branch, `printf 'y\n\n' | bash install.sh` (answer `y`, then the default port). Reinstall still boots out and bootstraps; `origin/main` produces the same four calls: ```text ⚠ LaunchAgent already installed at: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ==> Stopping existing service... ✓ Created: <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist ✓ LaunchAgent loaded successfully ✓ Service is running ⚠ Service is running but port 8787 is not listening yet ✓ Headroom proxy installed successfully! rc=0 --- launchctl call log: launchctl print gui/197609/com.headroom.proxy launchctl bootout gui/197609/com.headroom.proxy launchctl bootstrap gui/197609 <run>/fakehome/Library/LaunchAgents/com.headroom.proxy.plist launchctl print gui/197609/com.headroom.proxy ``` (The "port 8787 is not listening" warning comes from the `lsof` stub exiting 1; it is not a finding.) ## Real Behavior Proof - Environment: Git Bash on Windows 11 with stubbed `uname`, `launchctl`, `headroom`, `lsof`; no macOS, no real LaunchAgent. - Exact command / steps: the driver above, `echo N | bash install.sh` on `origin/main`'s script and on this branch's, then `printf 'y\n\n' | bash install.sh` on both. - Observed result: on `origin/main`, answering `N` made the stub log `launchctl bootout` before `Installation cancelled.`; on this branch the log is empty. Answering `y` makes the same four `launchctl` calls on both. - Not tested: real macOS launchd (the proof uses stubs on Windows and WSL, not a live LaunchAgent); real `launchctl` on macOS; the `--unattended` path (the block there runs unchanged, only its place in the file differs, but I did not run it). ## Runtime Rollout Safety - Rollout-managed feature(s): none; example script only. - Minimum rollout channel: n/a - Stable/default behavior changed: only the cancel path: the running service is no longer stopped when the user declines. - Kill switch / disable path: n/a - Unsafe override required: no - Qualification impact: none - Rollback path: revert this commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes (new test file only; the stubbed runs above are the check) - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes - Scope is an example script; the effect of the bug is a stopped proxy on the user's own machine. - Other defects in the same directory are in #4730 and separate PRs. Produced with AI assistance (Claude Code) operated by me (HetCreep); the driver was run on my machine against a clone of the repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
Headroom Examples
This directory contains examples demonstrating Headroom's capabilities.
Quick Start Examples
basic_usage.py
Basic integration with OpenAI client:
export OPENAI_API_KEY='your-key'
python examples/basic_usage.py
anthropic_example.py
Integration with Anthropic Claude:
export ANTHROPIC_API_KEY='your-key'
python examples/anthropic_example.py
streaming_example.py
Streaming responses with optimization:
export OPENAI_API_KEY='your-key'
python examples/streaming_example.py
tabular_compression_demo.py
Tabular + spreadsheet compression on generated sample data (no API key needed).
Shows where CSV/markdown tables and .xlsx workbooks compress and where compact,
all-unique data correctly passes through:
python examples/tabular_compression_demo.py # run all scenarios
python examples/tabular_compression_demo.py --write DIR # also save the sample files
Evaluation Examples
smart_vs_naive_eval.py
Compare SmartCrusher against naive truncation:
export OPENAI_API_KEY='your-key'
python examples/smart_vs_naive_eval.py
real_world_eval.py
Comprehensive evaluation with Anthropic models:
export ANTHROPIC_API_KEY='your-key'
python examples/real_world_eval.py
real_world_openai_eval.py
Comprehensive evaluation with OpenAI models:
export OPENAI_API_KEY='your-key'
python examples/real_world_openai_eval.py
Demo Directories
langchain_demo/
Full LangChain agent integration demo:
# No API key needed for compression demo
PYTHONPATH=. python -m examples.langchain_demo.show_compression
# Full comparison (requires API key)
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.langchain_demo.run_comparison
See langchain_demo/README.md for details.
claude_code_remote_control/
Keep Claude Code's Remote Control while routing through Headroom: ANTHROPIC_BASE_URL
stays unset and a local mitmproxy addon hands /v1/messages to Headroom via HTTPS_PROXY:
mitmdump --listen-host 127.0.0.1 --listen-port 8790 \
--allow-hosts '^api\.anthropic\.com(:443)?$' \
-s examples/claude_code_remote_control/route_to_headroom.py
See claude_code_remote_control/README.md for the Claude Code settings.
mcp_demo/
MCP (Model Context Protocol) integration demo:
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval
vertex_gemini_benchmark/
Gemini 3.8 Flash on Google Cloud Vertex AI (Gemini Enterprise Agent Platform) benchmark:
# Ensure Google Cloud ADC is active
gcloud auth application-default login
export GCP_PROJECT_ID="your-project-id"
# Run comparative benchmark (Direct vs Headroom Proxied)
python examples/vertex_gemini_benchmark/benchmark.py --model gemini-3.8-flash
See vertex_gemini_benchmark/README.md for full benchmark scenarios and methodology.
strands_bedrock_demo.py
AWS Strands Agents + Bedrock integration demo. Showcases two Headroom integration patterns:
- HeadroomHookProvider - Compresses tool outputs in real-time
- HeadroomStrandsModel - Optimizes entire conversation context
# Configure AWS credentials
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_DEFAULT_REGION='us-west-2' # Optional, defaults to us-west-2
# Or use AWS profile
export AWS_PROFILE='your-profile-name'
# Run the full demo (both integration patterns)
python examples/strands_bedrock_demo.py
# Run only the hook provider demo
python examples/strands_bedrock_demo.py --hook
# Run only the model wrapper demo
python examples/strands_bedrock_demo.py --model
# Specify a different AWS region
python examples/strands_bedrock_demo.py --region us-east-1
The demo uses Claude 3 Haiku via Bedrock for cost efficiency. It creates agents with 4 tools that return verbose JSON output (search results, logs, database records, metrics) and displays compression statistics with visual comparisons.
Requirements:
- AWS account with Bedrock enabled
- Claude 3 Haiku model access in your region
pip install strands-agents headroom-ai[strands]
Running Examples
All examples can be run from the repository root:
# Install dependencies
pip install -e ".[dev]"
# Run any example
python examples/<example_name>.py
Expected Results
| Example | Token Savings | Notes |
|---|---|---|
| basic_usage | 50-70% | Simple tool output compression |
| langchain_demo | 70-85% | Real agent with multiple tools |
| mcp_demo | 60-80% | MCP tool outputs |
| strands_bedrock_demo | 60-85% | Strands + Bedrock with verbose tools |
| real_world_eval | 50-90% | Varies by scenario |
Troubleshooting
ModuleNotFoundError: No module named 'headroom'
Run from the repository root with PYTHONPATH:
PYTHONPATH=. python examples/basic_usage.py
Or install in development mode:
pip install -e .
API Key Errors
Ensure your API keys are set:
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
AWS Credentials Errors (for Strands demo)
Ensure AWS credentials are configured:
# Option 1: Environment variables
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
# Option 2: AWS profile
export AWS_PROFILE='your-profile-name'
# Option 3: AWS credentials file (~/.aws/credentials)
Also ensure Bedrock and the Claude 3 Haiku model are enabled in your AWS account.