headroom-kit 0.1.0__tar.gz

headroom_kit-0.1.0/.github/workflows/checks.yml

@@ -0,0 +1,35 @@
+name: checks
+
+on:
+  pull_request:
+  push:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.12.3"
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked --dev
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: HEADROOM_KIT_INSTALL=1 uv run pytest
+      - run: node --test tests/test_client_adapters.mjs
+      - run: uv run pre-commit run anti-slop-python --all-files

headroom_kit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,138 @@
+name: publish
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+      - ".gitignore"
+      - "LICENSE"
+      - "NOTICE.md"
+
+concurrency:
+  group: publish-main
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  checks:
+    uses: ./.github/workflows/checks.yml
+
+  publish:
+    needs: checks
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/headroom-kit
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.12.3"
+          enable-cache: true
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Verify this commit is still main
+        id: main
+        run: |
+          git fetch origin main
+          if [[ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]]; then
+            echo "main has advanced; skipping release."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Determine next release version
+        id: release_version
+        if: steps.main.outputs.skip != 'true'
+        run: |
+          python3 - << 'EOF' >> "$GITHUB_OUTPUT"
+          import re
+          import subprocess
+
+          def resolve_version():
+              subprocess.run(["git", "fetch", "--tags", "--force"], capture_output=True)
+
+              head_tags_proc = subprocess.run(
+                  ["git", "tag", "--points-at", "HEAD"],
+                  capture_output=True, text=True, check=True
+              )
+              for tag in head_tags_proc.stdout.splitlines():
+                  tag = tag.strip()
+                  if re.match(r"^v\d+\.\d+\.\d+$", tag):
+                      print(f"tag={tag}")
+                      print(f"version={tag.lstrip('v')}")
+                      print("is_new_tag=false")
+                      return
+
+              tags_proc = subprocess.run(
+                  ["git", "tag", "-l", "v[0-9]*.[0-9]*.[0-9]*", "--sort=-v:refname"],
+                  capture_output=True, text=True, check=True
+              )
+              tags = [t.strip() for t in tags_proc.stdout.splitlines() if t.strip()]
+
+              if not tags:
+                  next_tag = "v0.1.0"
+              else:
+                  latest = tags[0]
+                  match = re.match(r"^v(\d+)\.(\d+)\.(\d+)$", latest)
+                  if match:
+                      major, minor, patch = map(int, match.groups())
+                      next_tag = f"v{major}.{minor}.{patch + 1}"
+                  else:
+                      next_tag = "v0.1.0"
+
+              print(f"tag={next_tag}")
+              print(f"version={next_tag.lstrip('v')}")
+              print("is_new_tag=true")
+
+          resolve_version()
+          EOF
+
+      - name: Create and push git tag
+        if: steps.main.outputs.skip != 'true' && steps.release_version.outputs.is_new_tag == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "${{ steps.release_version.outputs.tag }}"
+          git push origin "${{ steps.release_version.outputs.tag }}"
+
+      - name: Build distribution packages
+        if: steps.main.outputs.skip != 'true'
+        run: uv build
+
+      - name: Create GitHub Release
+        if: steps.main.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="${{ steps.release_version.outputs.tag }}"
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "GitHub release $tag already exists."
+          else
+            gh release create "$tag" dist/* \
+              --title "$tag" \
+              --generate-notes
+          fi
+
+      - name: Publish to PyPI
+        if: steps.main.outputs.skip != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

headroom_kit-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local PR diagrams. Do not commit rendered SVGs.
+.pr-lens/

headroom_kit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/ruarfff/anti-slop-python
+    rev: f512a14e39df65644ae299b563c8dfb383cb8f6f # v0.2.0
+    hooks:
+      - id: anti-slop-python

headroom_kit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

headroom_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruairí O'Brien
+
+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.

headroom_kit-0.1.0/NOTICE.md

@@ -0,0 +1,6 @@
+# Notices
+
+Headroom Kit is distributed under the [MIT License](LICENSE).
+
+Headroom, coding agents, and editor extensions remain separate projects with
+their own licenses. Kit does not vendor Headroom or redistribute coding agents.

headroom_kit-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: headroom-kit
+Version: 0.1.0
+Summary: Launch existing coding agents through a local Headroom proxy
+Project-URL: Homepage, https://github.com/ruarfff/headroom-kit
+Project-URL: Repository, https://github.com/ruarfff/headroom-kit
+Project-URL: Issues, https://github.com/ruarfff/headroom-kit/issues
+Author: Ruairí O'Brien
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: codex,copilot,headroom,opencode,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.13
+Requires-Dist: headroom-ai[code,proxy]==0.37.0
+Description-Content-Type: text/markdown
+
+# Headroom Kit
+
+[![PyPI - Version](https://img.shields.io/pypi/v/headroom-kit)](https://pypi.org/project/headroom-kit/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/headroom-kit)](https://pypi.org/project/headroom-kit/)
+[![skills.sh](https://skills.sh/b/ruarfff/headroom-kit)](https://skills.sh/ruarfff/headroom-kit)
+[![License: MIT](https://img.shields.io/github/license/ruarfff/headroom-kit)](LICENSE)
+
+Run an existing coding agent through a local [Headroom](https://github.com/headroomlabs-ai/headroom) proxy. Kit owns routing, Copilot authentication, editor isolation, and the shared proxy. Headroom owns compression and metrics. This package does not install agents, replace the `headroom` command, or download Python packages when an agent launches.
+
+```text
+agent -> headroom-kit -> Headroom on 127.0.0.1 -> model provider
+```
+
+## Install
+
+You need Python 3.13 and the agent you want to launch. Kit and Headroom 0.37.0 install into the same environment:
+
+```sh
+uv tool install --python 3.13 headroom-kit
+```
+
+A normal virtual environment works too:
+
+```sh
+uv venv --python 3.13
+uv pip install headroom-kit
+. .venv/bin/activate
+```
+
+Do not point Kit at a separate `headroom` executable. It imports Headroom's Python modules. Copilot login is `headroom-kit copilot-auth login` in that same install. Headroom may still download its own model files on first proxy startup. That is separate from installing this package.
+
+Check both versions without starting a proxy:
+
+```sh
+headroom-kit --version
+```
+
+## Set up with an agent
+
+This repository includes `install-headroom-kit`, an Agent Skill that installs the CLI and checks the Headroom version without starting a proxy.
+
+The [`skills` CLI](https://github.com/vercel-labs/skills) can install it for the current project:
+
+```sh
+npx skills add ruarfff/headroom-kit --skill install-headroom-kit
+```
+
+Make it available to your agents:
+
+```sh
+npx skills add ruarfff/headroom-kit --skill install-headroom-kit --agent '*' --global --yes
+```
+
+See the [`skills` CLI documentation](https://github.com/vercel-labs/skills#supported-agents).
+
+## Commands
+
+```text
+headroom-kit [--config PATH] run <agent> -- <agent arguments...>
+headroom-kit copilot-auth login
+headroom-kit status
+headroom-kit stop <port>
+```
+
+Agents: `codex`, `codex-app`, `copilot`, `copilot-vscode`, `pi`, `opencode`.
+
+```sh
+headroom-kit copilot-auth login
+headroom-kit run codex --
+headroom-kit run copilot -- --model auto
+headroom-kit run pi -- --provider openai --model <model-id>
+headroom-kit run opencode --
+headroom-kit status
+headroom-kit stop 8787
+```
+
+Arguments after `--` are forwarded unchanged. `headroom-kit run codex -- --help` shows Codex help and does not start a proxy. `status` and `stop` do not need provider credentials or model downloads.
+
+Shared proxies stay up after the client exits. Stopping one interrupts every client on that port. Kit will not adopt or stop an unrelated listener. An incompatible managed proxy must be stopped explicitly before a new one can use the port.
+
+## Configure
+
+Built-in defaults are enough for a normal install. `--config` accepts a JSON object of non-secret integration defaults. Precedence is `HEADROOM_*` environment variables, then the file, then the built-in defaults. See [configuration](docs/configuration.md).
+
+`HEADROOM_VERSION`, and config keys `version`, `uv`, and `python`, are rejected. Install the tested Headroom release instead of selecting one at launch.
+
+## Agents
+
+Install and sign in to the agent yourself. Kit does not install it.
+
+| Agent | Prerequisite |
+| --- | --- |
+| `codex` | Existing Codex sign-in. Built-in OpenAI provider only. |
+| `copilot` | `headroom-kit copilot-auth login`, then a Copilot CLI that honours `COPILOT_API_URL`. |
+| `pi` | Pi installed. Copilot routing uses `headroom-kit copilot-auth login`. |
+| `opencode` | OpenCode v2. |
+| `copilot-vscode` | `code` or `code-insiders`. Uses an isolated profile, not your normal editor data. |
+| `codex-app` | macOS only. Quit Codex before launch. |
+
+Windows is not part of this package. Linux and macOS CLI lifecycle checks run in CI. GUI behaviour is platform-specific; live Linux agent support is not verified. Details are in [usage](docs/usage.md) and [validation](docs/validation.md).
+
+[MIT](LICENSE). See [NOTICE](NOTICE.md) for attribution.

headroom_kit-0.1.0/README.md

@@ -0,0 +1,102 @@
+# Headroom Kit
+
+[![PyPI - Version](https://img.shields.io/pypi/v/headroom-kit)](https://pypi.org/project/headroom-kit/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/headroom-kit)](https://pypi.org/project/headroom-kit/)
+[![skills.sh](https://skills.sh/b/ruarfff/headroom-kit)](https://skills.sh/ruarfff/headroom-kit)
+[![License: MIT](https://img.shields.io/github/license/ruarfff/headroom-kit)](LICENSE)
+
+Run an existing coding agent through a local [Headroom](https://github.com/headroomlabs-ai/headroom) proxy. Kit owns routing, Copilot authentication, editor isolation, and the shared proxy. Headroom owns compression and metrics. This package does not install agents, replace the `headroom` command, or download Python packages when an agent launches.
+
+```text
+agent -> headroom-kit -> Headroom on 127.0.0.1 -> model provider
+```
+
+## Install
+
+You need Python 3.13 and the agent you want to launch. Kit and Headroom 0.37.0 install into the same environment:
+
+```sh
+uv tool install --python 3.13 headroom-kit
+```
+
+A normal virtual environment works too:
+
+```sh
+uv venv --python 3.13
+uv pip install headroom-kit
+. .venv/bin/activate
+```
+
+Do not point Kit at a separate `headroom` executable. It imports Headroom's Python modules. Copilot login is `headroom-kit copilot-auth login` in that same install. Headroom may still download its own model files on first proxy startup. That is separate from installing this package.
+
+Check both versions without starting a proxy:
+
+```sh
+headroom-kit --version
+```
+
+## Set up with an agent
+
+This repository includes `install-headroom-kit`, an Agent Skill that installs the CLI and checks the Headroom version without starting a proxy.
+
+The [`skills` CLI](https://github.com/vercel-labs/skills) can install it for the current project:
+
+```sh
+npx skills add ruarfff/headroom-kit --skill install-headroom-kit
+```
+
+Make it available to your agents:
+
+```sh
+npx skills add ruarfff/headroom-kit --skill install-headroom-kit --agent '*' --global --yes
+```
+
+See the [`skills` CLI documentation](https://github.com/vercel-labs/skills#supported-agents).
+
+## Commands
+
+```text
+headroom-kit [--config PATH] run <agent> -- <agent arguments...>
+headroom-kit copilot-auth login
+headroom-kit status
+headroom-kit stop <port>
+```
+
+Agents: `codex`, `codex-app`, `copilot`, `copilot-vscode`, `pi`, `opencode`.
+
+```sh
+headroom-kit copilot-auth login
+headroom-kit run codex --
+headroom-kit run copilot -- --model auto
+headroom-kit run pi -- --provider openai --model <model-id>
+headroom-kit run opencode --
+headroom-kit status
+headroom-kit stop 8787
+```
+
+Arguments after `--` are forwarded unchanged. `headroom-kit run codex -- --help` shows Codex help and does not start a proxy. `status` and `stop` do not need provider credentials or model downloads.
+
+Shared proxies stay up after the client exits. Stopping one interrupts every client on that port. Kit will not adopt or stop an unrelated listener. An incompatible managed proxy must be stopped explicitly before a new one can use the port.
+
+## Configure
+
+Built-in defaults are enough for a normal install. `--config` accepts a JSON object of non-secret integration defaults. Precedence is `HEADROOM_*` environment variables, then the file, then the built-in defaults. See [configuration](docs/configuration.md).
+
+`HEADROOM_VERSION`, and config keys `version`, `uv`, and `python`, are rejected. Install the tested Headroom release instead of selecting one at launch.
+
+## Agents
+
+Install and sign in to the agent yourself. Kit does not install it.
+
+| Agent | Prerequisite |
+| --- | --- |
+| `codex` | Existing Codex sign-in. Built-in OpenAI provider only. |
+| `copilot` | `headroom-kit copilot-auth login`, then a Copilot CLI that honours `COPILOT_API_URL`. |
+| `pi` | Pi installed. Copilot routing uses `headroom-kit copilot-auth login`. |
+| `opencode` | OpenCode v2. |
+| `copilot-vscode` | `code` or `code-insiders`. Uses an isolated profile, not your normal editor data. |
+| `codex-app` | macOS only. Quit Codex before launch. |
+
+Windows is not part of this package. Linux and macOS CLI lifecycle checks run in CI. GUI behaviour is platform-specific; live Linux agent support is not verified. Details are in [usage](docs/usage.md) and [validation](docs/validation.md).
+
+[MIT](LICENSE). See [NOTICE](NOTICE.md) for attribution.