Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

chore: finish the org and docs-domain migration (#3389)

Tejas Chopra96dfc7005f9a
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4b008f6e0..5b4cf986b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -15,10 +15,10 @@
"version": "0.37.0",
"author": {
"name": "Headroom Contributors",
- "url": "https://github.com/chopratejas/headroom"
+ "url": "https://github.com/headroomlabs-ai/headroom"
},
- "homepage": "https://github.com/chopratejas/headroom",
- "repository": "https://github.com/chopratejas/headroom",
+ "homepage": "https://github.com/headroomlabs-ai/headroom",
+ "repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
diff --git a/.claude/.headroom_wrap_settings.lock b/.claude/.headroom_wrap_settings.lock
new file mode 100644
index 000000000..e69de29bb
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index c86795a37..2e734a692 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,8 @@
blank_issues_enabled: true
contact_links:
- name: Questions & Discussions
- url: https://github.com/chopratejas/headroom/discussions
+ url: https://github.com/headroomlabs-ai/headroom/discussions
about: Ask questions and discuss ideas in GitHub Discussions
- name: Documentation
- url: https://headroom-docs.vercel.app/docs
+ url: https://docs.headroomlabs.ai/docs
about: Check out the documentation for guides and API reference
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 4b008f6e0..5b4cf986b 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -15,10 +15,10 @@
"version": "0.37.0",
"author": {
"name": "Headroom Contributors",
- "url": "https://github.com/chopratejas/headroom"
+ "url": "https://github.com/headroomlabs-ai/headroom"
},
- "homepage": "https://github.com/chopratejas/headroom",
- "repository": "https://github.com/chopratejas/headroom",
+ "homepage": "https://github.com/headroomlabs-ai/headroom",
+ "repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 08c7729ab..edb2bce34 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,8 +1,8 @@
name: Validate Docs
# There is ONE documentation site: the Next.js/Fumadocs app in `docs/`, published
-# at https://headroom-docs.vercel.app by Vercel's own Git integration. That URL is
-# what README and `pyproject.toml` (Homepage, Documentation) point at.
+# at https://docs.headroomlabs.ai by Vercel's own Git integration. That URL is
+# what README and `pyproject.toml` (Homepage, Documentation) should point at.
#
# This workflow therefore only *validates* — it deploys nothing. Vercel owns
# deployment; duplicating it here is what produced a `deploy-vercel` job that
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1b6e7b6d7..775dc1691 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -89,7 +89,7 @@ A human maintainer reviews every dep change. PRs that add or bump a package must
## Development setup
```bash
-git clone https://github.com/chopratejas/headroom.git
+git clone https://github.com/headroomlabs-ai/headroom.git
cd headroom
python -m venv .venv && source .venv/bin/activate
node --version # Node 18+ required for commitlint hooks
diff --git a/Cargo.toml b/Cargo.toml
index 32fd4aed4..3fa9dbbb9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -23,7 +23,7 @@ default-members = [
edition = "2021"
rust-version = "1.80"
license = "Apache-2.0"
-repository = "https://github.com/chopratejas/headroom"
+repository = "https://github.com/headroomlabs-ai/headroom"
authors = ["Headroom Maintainers"]
[workspace.dependencies]
diff --git a/README.md b/README.md
index 929dfc8c5..e891ac2f0 100644
--- a/README.md
+++ b/README.md
@@ -11,19 +11,19 @@
<p align="center"><strong>60–95% fewer tokens (for JSON data), 15-20% fewer tokens (for coding agents) · library · proxy · MCP · content-aware compressors · local-first · reversible</strong></p>
<p align="center">
- <a href="https://github.com/chopratejas/headroom/actions/workflows/ci.yml"><img src="https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
- <a href="https://app.codecov.io/gh/chopratejas/headroom"><img src="https://codecov.io/gh/chopratejas/headroom/graph/badge.svg" alt="codecov"></a>
+ <a href="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml"><img src="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+ <a href="https://app.codecov.io/gh/headroomlabs-ai/headroom"><img src="https://codecov.io/gh/headroomlabs-ai/headroom/graph/badge.svg" alt="codecov"></a>
<a href="https://pypi.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg" alt="PyPI"></a>
<a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg" alt="npm"></a>
<a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-Kompress--v2--base-yellow.svg" alt="Model: Kompress-v2-base"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
- <a href="https://headroom-docs.vercel.app/docs"><img src="https://img.shields.io/badge/docs-online-blue.svg" alt="Docs"></a>
+ <a href="https://docs.headroomlabs.ai/docs"><img src="https://img.shields.io/badge/docs-online-blue.svg" alt="Docs"></a>
</p>
<!-- mcp-name: io.github.headroomlabs-ai/headroom -->
<p align="center">
- <a href="https://headroom-docs.vercel.app/docs">Docs</a> ·
+ <a href="https://docs.headroomlabs.ai/docs">Docs</a> ·
<a href="#get-started-60-seconds">Install</a> ·
<a href="#proof">Proof</a> ·
<a href="#agent-compatibility-matrix">Agents</a> ·
@@ -32,7 +32,7 @@
</p>
<p align="center"><sub>
- <b>AI agents / LLMs:</b> read <a href="llms.txt"><code>/llms.txt</code></a> here, or fetch <a href="https://headroom-docs.vercel.app/llms.txt">the live index</a> / <a href="https://headroom-docs.vercel.app/llms-full.txt">full docs blob</a>.
+ <b>AI agents / LLMs:</b> read <a href="llms.txt"><code>/llms.txt</code></a> here, or fetch <a href="https://docs.headroomlabs.ai/llms.txt">the live index</a> / <a href="https://docs.headroomlabs.ai/llms-full.txt">full docs blob</a>.
</sub></p>
---
@@ -83,7 +83,7 @@ Headroom compresses everything your AI agent reads — tool outputs, logs, RAG c
- **CacheAligner** - detects and warns about volatile content that can bust provider KV cache prefixes; never rewrites prompts
- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them
-→ [Architecture](https://headroom-docs.vercel.app/docs/architecture) · [CCR reversible compression](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-v2-base model card](https://huggingface.co/chopratejas/kompress-v2-base)
+→ [Architecture](https://docs.headroomlabs.ai/docs/architecture) · [CCR reversible compression](https://docs.headroomlabs.ai/docs/ccr) · [Kompress-v2-base model card](https://huggingface.co/chopratejas/kompress-v2-base)
## Get started (60 seconds)
@@ -152,7 +152,7 @@ args = ["mcp", "serve"]
| SQuAD v2 | QA | 100 | — | **97%** | 19% compression |
| BFCL | Tools | 100 | — | **97%** | 32% compression |
-Reproduce: `python -m headroom.evals suite --tier 1` · [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)
+Reproduce: `python -m headroom.evals suite --tier 1` · [Full benchmarks & methodology](https://docs.headroomlabs.ai/docs/benchmarks)
## Output token reduction (cut what the model writes back)
@@ -215,11 +215,11 @@ unshaped as a control group: `export HEADROOM_OUTPUT_HOLDOUT=0.1`. The dashboard
shows an **Output Tokens Saved** card next to input compression, labelled
`measured` or `estimated` with the confidence band.
-→ Full write-up incl. the measurement methodology: [Output token reduction](https://headroom-docs.vercel.app/docs/savings)
+→ Full write-up incl. the measurement methodology: [Output token reduction](https://docs.headroomlabs.ai/docs/savings)
<a href="https://www.star-history.com/?repos=chopratejas%2Fheadroom&type=date&legend=top-left">
<picture>
- <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=chopratejas/headroom&type=date&legend=top-left" />
+ <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=headroomlabs-ai/headroom&type=date&legend=top-left" />
</picture>
</a>
@@ -306,7 +306,7 @@ headroom wrap vscode
Keep the command running and use Copilot normally. Headroom holds the short-lived
upstream Copilot token only in the proxy process.
-See the [cross-platform VS Code Copilot guide](https://headroom-docs.vercel.app/docs/vscode-copilot)
+See the [cross-platform VS Code Copilot guide](https://docs.headroomlabs.ai/docs/vscode-copilot)
for paths, credential flow, remote-development notes, undo steps, and troubleshooting.
### Claude Code in Visual Studio Code
@@ -333,7 +333,7 @@ headroom unwrap vscode-claude
```
See the
-[VS Code Claude Code guide](https://headroom-docs.vercel.app/docs/vscode-claude-code)
+[VS Code Claude Code guide](https://docs.headroomlabs.ai/docs/vscode-claude-code)
for verification, configuration paths, custom profiles, remote development, and
troubleshooting.
@@ -360,7 +360,7 @@ troubleshooting.
| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
| LangChain | `HeadroomChatModel(your_llm)` |
| Agno | `HeadroomAgnoModel(your_model)` |
-| Strands | [Strands guide](https://headroom-docs.vercel.app/docs/strands) |
+| Strands | [Strands guide](https://docs.headroomlabs.ai/docs/strands) |
| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
| Multi-agent | `SharedContext().put / .get` |
| MCP clients | `headroom mcp install` |
@@ -455,7 +455,7 @@ pipx install --python python3.13 "headroom-ai[all]"
> **Pick 3.13 if you want dollar savings.** The dashboard's *Proxy $ Saved* tile prices compression with [LiteLLM](https://github.com/BerriAI/litellm), and LiteLLM can't be installed on Python 3.14+. On 3.14 token savings still track, but the dollar figure stays `$0.00`. If you already installed on 3.14, switch with `pipx reinstall headroom-ai --python python3.13` and restart the proxy.
-→ [Installation guide](https://headroom-docs.vercel.app/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
+→ [Installation guide](https://docs.headroomlabs.ai/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
> **CPU requirement (x86/x86_64):** the ONNX-backed features — Magika content
> detection and embedding relevance — use a precompiled ONNX Runtime that needs
@@ -573,13 +573,13 @@ download entirely.
| Start here | Go deeper |
|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
-| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart) | [Architecture](https://headroom-docs.vercel.app/docs/architecture) |
-| [Proxy](https://headroom-docs.vercel.app/docs/proxy) | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |
-| [MCP tools](https://headroom-docs.vercel.app/docs/mcp) | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr) |
-| [Memory](https://headroom-docs.vercel.app/docs/memory) | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization) |
-| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning) | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks) |
-| [Configuration](https://headroom-docs.vercel.app/docs/configuration) | [Limitations](https://headroom-docs.vercel.app/docs/limitations) |
-| [Persistent installs](https://headroom-docs.vercel.app/docs/persistent-installs) (`headroom init` / `headroom install apply`) | [Savings analytics](https://headroom-docs.vercel.app/docs/savings) (`headroom savings` / `headroom perf` / `headroom doctor`) |
+| [Quickstart](https://docs.headroomlabs.ai/docs/quickstart) | [Architecture](https://docs.headroomlabs.ai/docs/architecture) |
+| [Proxy](https://docs.headroomlabs.ai/docs/proxy) | [How compression works](https://docs.headroomlabs.ai/docs/how-compression-works) |
+| [MCP tools](https://docs.headroomlabs.ai/docs/mcp) | [CCR — reversible compression](https://docs.headroomlabs.ai/docs/ccr) |
+| [Memory](https://docs.headroomlabs.ai/docs/memory) | [Cache optimization](https://docs.headroomlabs.ai/docs/cache-optimization) |
+| [Failure learning](https://docs.headroomlabs.ai/docs/failure-learning) | [Benchmarks](https://docs.headroomlabs.ai/docs/benchmarks) |
+| [Configuration](https://docs.headroomlabs.ai/docs/configuration) | [Limitations](https://docs.headroomlabs.ai/docs/limitations) |
+| [Persistent installs](https://docs.headroomlabs.ai/docs/persistent-installs) (`headroom init` / `headroom install apply`) | [Savings analytics](https://docs.headroomlabs.ai/docs/savings) (`headroom savings` / `headroom perf` / `headroom doctor`) |
## Compared to
@@ -596,7 +596,7 @@ Headroom runs **locally**, covers **every** content type, works with every major
## Contributing
```bash
-git clone https://github.com/chopratejas/headroom.git && cd headroom
+git clone https://github.com/headroomlabs-ai/headroom.git && cd headroom
uv sync --extra dev && uv run pytest
```
diff --git a/RUST_DEV.md b/RUST_DEV.md
index 863ea61c1..2b5e76c19 100644
--- a/RUST_DEV.md
+++ b/RUST_DEV.md
@@ -14,6 +14,7 @@ crates/
headroom-proxy/ # binary: axum /healthz (Phase 2 grows this)
headroom-py/ # PyO3 cdylib exposing `headroom._core`
headroom-parity/ # lib + `parity-run` CLI for Python parity tests
+ headroom-simulators/ # binary: deterministic local upstream stub for proxy tests
tests/parity/
fixtures/<transform>/*.json # recorded Python outputs (Phase 1 ports match)
recorder.py # Python-side fixture recorder
@@ -36,7 +37,7 @@ exposes the same targets:
| `make test-parity` | Builds `headroom-py` via maturin, runs `parity-run run` |
| `make bench` | `cargo bench --workspace` |
| `make build-proxy` | Release-builds `headroom-proxy`, strips, prints size |
-| `make build-wheel` | `maturin build --release -m crates/headroom-py/pyproject.toml` |
+| `make build-wheel` | `maturin build --release -m crates/headroom-py/Cargo.toml` |
| `make fmt` | `cargo fmt --all` |
| `make lint` | `cargo fmt --check` + `cargo clippy --workspace -- -D warnings` |
@@ -282,9 +283,10 @@ doesn't rediscover them.
`plugins/headroom-agent-hooks/**/plugin.json` on every commit. Those
changes are harmless but each commit in Phase 0 picks them up. Phase 1
does not need to do anything special — just let the hook run.
-- **`rust-toolchain.toml`** pins `channel = "stable"` rather than a specific
- version so CI picks up the same toolchain the local box uses. Tighten to a
- pinned version (e.g. `1.78`) once the port stabilizes.
+- **`rust-toolchain.toml`** now pins `channel = "1.95.0"` (previously tracked
+ `"stable"`, which let CI drift ahead of local dev boxes — see the file's own
+ comment for the 2026-04-27 incident this fixed). Resolved; kept here for
+ history.
## Multi-worker deployment — CCR fragmentation
@@ -331,10 +333,14 @@ in-memory.
Each uvicorn worker is a separate Python process. The following state is
fragmented across workers:
-1. **Python `CompressionStore`** — defaults to `InMemoryBackend` (per-process)
- when `HEADROOM_CCR_BACKEND` is unset. Each worker has its own singleton; CCR
- markers written on worker A are invisible to worker B. Set
- `HEADROOM_CCR_BACKEND=sqlite` to use a shared cross-worker store.
+1. **Python `CompressionStore`** — defaults to `SQLiteBackend` at
+ `workspace_dir()/ccr_store.db` (restart-safe, shared across workers) when
+ `HEADROOM_CCR_BACKEND` is unset or `"sqlite"` (`_create_default_ccr_backend`
+ in `headroom/cache/compression_store.py`). Set `HEADROOM_CCR_BACKEND=memory`
+ to opt into the per-process `InMemoryBackend` instead — that is the setting
+ this section's fragmentation risk actually applies to; the log messages in
+ `headroom/proxy/server.py` (see below) still assume in-memory-by-default and
+ are stale on this point.
2. **`HeadroomProxy._compression_caches`** (`headroom/proxy/server.py`)
— per-session `CompressionCache` dict (instance var, always per-worker).
3. **`HeadroomProxy.session_tracker_store`** — per-session prefix-tracker
diff --git a/TESTING-copilot-subscription.md b/TESTING-copilot-subscription.md
index 1985d7193..ebcc3b910 100644
--- a/TESTING-copilot-subscription.md
+++ b/TESTING-copilot-subscription.md
@@ -3,7 +3,7 @@
This feature has live coverage on macOS and Windows. Additional Linux secret-store
coverage is still useful (see [Status](#status)). If you have a GitHub Copilot
subscription and 10 minutes, please run one of the flows below and
-[file a report](https://github.com/chopratejas/headroom/issues/new?template=copilot-subscription-test-report.md).
+[file a report](https://github.com/headroomlabs-ai/headroom/issues/new?template=copilot-subscription-test-report.md).
> ⚠️ This reads your Copilot login token and routes your
> Copilot CLI traffic through a local Headroom proxy. Only run it if you're
@@ -36,7 +36,7 @@ Headroom deliberately does **not** auto-select a per-account host from
`api.individual.githubcopilot.com`) that does **not** serve newer models on the
responses API and is not the host the official Copilot client routes with — using
it regressed `headroom wrap copilot` after 0.22.4
-([#610](https://github.com/chopratejas/headroom/issues/610)).
+([#610](https://github.com/headroomlabs-ai/headroom/issues/610)).
**Enterprise / data-residency:** if your organization is provisioned on a
dedicated Copilot API host (GitHub Enterprise Cloud with data residency, or an
@@ -49,7 +49,7 @@ headroom wrap copilot --subscription -- --model gpt-5.4
```
If you operate such an environment and would like Headroom to **auto-detect** the
-correct host instead of pinning it, please [open an issue](https://github.com/chopratejas/headroom/issues/new) —
+correct host instead of pinning it, please [open an issue](https://github.com/headroomlabs-ai/headroom/issues/new) —
the intended path is to resolve it from GitHub's token-exchange endpoint (the
source the official Copilot client uses), and we'd want to validate it against a
real enterprise tenant.
@@ -163,7 +163,7 @@ Schema, for reference: Keychain generic password, service `copilot-cli`
## What to report
Please open a
-[Copilot subscription test report](https://github.com/chopratejas/headroom/issues/new?template=copilot-subscription-test-report.md)
+[Copilot subscription test report](https://github.com/headroomlabs-ai/headroom/issues/new?template=copilot-subscription-test-report.md)
with:
- **OS + version** and **how you installed** (pipx/pip wheel, Docker, source).
diff --git a/benchmarks/codemode_ab.py b/benchmarks/codemode_ab.py
new file mode 100644
index 000000000..5dff5d163
--- /dev/null
+++ b/benchmarks/codemode_ab.py
@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""Live A/B for the headroom-codemode probe-batching directive.
+
+Runs a fixed exploration-task suite through `claude -p` twice per task -- once
+with the steering plugin active (HEADROOM_CODEMODE=1) and once without -- in a
+clean detached worktree, then scores cost, turns, burst structure, bytes
+fetched and answer correctness from the resulting session transcripts.
+
+Replay benchmarks cannot measure this: steering changes which calls the model
+emits, so the counterfactual is not present in recorded sessions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+PROJECTS = Path.home() / ".claude" / "projects"
+
+# (id, prompt, ground truth, kind)
+TASKS = [
+ (
+ "ccr_py_count",
+ "How many .py files are directly in headroom/ccr/? Answer with just the number.",
+ "10",
+ "num",
+ ),
+ (
+ "max_rounds",
+ "What is the default value of max_retrieval_rounds in ResponseHandlerConfig? Answer with just the number.",
+ "3",
+ "num",
+ ),
+ (
+ "plugin_dirs",
+ "How many directories are directly under plugins/? Answer with just the number.",
+ "5",
+ "num",
+ ),
+ (
+ "logcompressor_lines",
+ "How many lines are in crates/headroom-core/src/transforms/log_compressor.rs? Answer with just the number.",
+ "1795",
+ "num",
+ ),
+ (
+ "openclaw_version",
+ "What version is declared in plugins/openclaw/package.json? Answer with just the version string.",
+ "0.37.0",
+ "exact",
+ ),
+ (
+ "test_ccr_files",
+ "How many files directly in tests/ (not in subdirectories) have names starting with test_ccr? Answer with just the number.",
+ "24",
+ "num",
+ ),
+ (
+ "crate_names",
+ "List the directory names under crates/ as a comma-separated sorted list, nothing else.",
+ "headroom-core,headroom-parity,headroom-proxy,headroom-py,headroom-simulators",
+ "set",
+ ),
+ (
+ "agenthooks_events",
+ "How many distinct hook event names are defined in plugins/headroom-agent-hooks/hooks/hooks.json? Answer with just the number.",
+ "2",
+ "num",
+ ),
+]
+
+# Multi-probe suite: each task needs several small independent facts, i.e. the
+# exact shape the directive targets. This measures the CEILING for steering,
+# not a field average -- real observed bursts average 2.6 calls.
+TASKS_MULTI = [
+ (
+ "crate_rs_counts",
+ "For each directory under crates/, report how many .rs files it contains recursively. "
+ "Answer as name=count pairs, comma-separated, sorted by name, nothing else.",
+ "headroom-core=99,headroom-parity=3,headroom-proxy=86,headroom-py=2,headroom-simulators=7",
+ "seq",
+ ),
+ (
+ "file_existence",
+ "Do these paths exist? pyproject.toml, uv.lock, Cargo.toml, mkdocs.yml, tsconfig.json. "
+ "Answer as five yes/no values, comma-separated, in that order, nothing else.",
+ "yes,yes,yes,no,no",
+ "seq",
+ ),
+ (
+ "dir_counts",
+ "Report three numbers: how many .py files are directly in benchmarks/, how many .md files "
+ "are directly in wiki/, and how many directories are directly under plugins/. "
+ "Answer as three comma-separated numbers in that order, nothing else.",
+ "25,35,5",
+ "seq",
+ ),
+ (
+ "ccr_symbols",
+ "In headroom/ccr/, report how many .py files contain the string 'CCR_TOOL_NAME', how many "
+ "contain 'async def', and how many contain 'class '. Answer as three comma-separated numbers "
+ "in that order, nothing else.",
+ "6,5,8",
+ "seq",
+ ),
+ (
+ "plugin_versions",
+ "Report the version field from each of: plugins/openclaw/package.json, "
+ "plugins/headroom-agent-hooks/.claude-plugin/plugin.json. "
+ "Answer as two comma-separated version strings in that order, nothing else.",
+ "0.37.0,0.37.0",
+ "seq",
+ ),
+ (
+ "line_counts",
+ "Report the line count of each of these files: headroom/ccr/response_handler.py, "
+ "headroom/ccr/tool_injection.py, headroom/ccr/mcp_server.py. "
+ "Answer as three comma-separated numbers in that order, nothing else.",
+ "1095,615,1199",
+ "seq",
+ ),
+]
+
+
+def score(kind: str, truth: str, answer: str) -> bool:
+ """Grade an answer.
+
+ Answers often carry a trailing citation ("3\n\n(file.py:72)"), so numeric
+ grading reads the FIRST number, not the last -- otherwise a line number in
+ the citation is graded as the answer.
+ """
+ a = (answer or "").strip().replace("`", "")
+ if kind == "num":
+ nums = re.findall(r"\d[\d,]*", a)
+ return bool(nums) and nums[0].replace(",", "") == truth
+ if kind == "exact":
+ return truth in a
+ if kind == "seq":
+ want = [t.strip().lower() for t in truth.split(",")]
+ # take the first len(want) comma/whitespace-separated fields of the
+ # first line that has at least that many -- ignores trailing prose
+ for line in [a] + a.splitlines():
+ got = [t.strip().lower() for t in re.split(r"[,\s]+", line) if t.strip()]
+ if len(got) >= len(want) and got[: len(want)] == want:
+ return True
+ return False
+ if kind == "set":
+ got = {t.strip().lower() for t in re.split(r"[,\s]+", a) if t.strip()}
+ want = {t.strip().lower() for t in truth.split(",")}
+ return want.issubset(got)
+ return False
+
+
+def trace(session_id: str) -> dict:
+ """Pull burst structure and bytes fetched out of the session transcript."""
+ hits = list(PROJECTS.glob(f"**/{session_id}.jsonl"))
+ if not hits:
+ return {"trace_found": False}
+ rows = []
+ for line in hits[0].open(errors="replace"):
+ try:
+ rows.append(json.loads(line))
+ except Exception:
+ pass
+
+ calls = bash_calls = 0
+ bursts: list[int] = []
+ run = 0
+ fetched = 0
+ pend: set[str] = set()
+ batched = 0 # compound shell commands (a proxy for directive compliance)
+
+ def text_of(x):
+ if isinstance(x, str):
+ return x
+ if isinstance(x, list):
+ return "\n".join(
+ b.get("text", "")
+ if isinstance(b, dict) and b.get("type") == "text"
+ else json.dumps(b)
+ for b in x
+ )
+ return json.dumps(x) if x is not None else ""
+
+ for d in rows:
+ t = d.get("type")
+ if t == "assistant":
+ tus = [
+ b
+ for b in (d.get("message") or {}).get("content") or []
+ if isinstance(b, dict) and b.get("type") == "tool_use"
+ ]
+ if tus:
+ run += 1
+ for b in tus:
+ calls += 1
+ pend.add(b.get("id"))
+ if b.get("name") == "Bash":
+ bash_calls += 1
+ cmd = (b.get("input") or {}).get("command") or ""
+ if re.search(r";|&&", cmd):
+ batched += 1
+ else:
+ if run:
+ bursts.append(run)
+ run = 0
+ elif t in ("user", "attachment"):
+ for b in (d.get("message") or {}).get("content") or []:
+ if (
+ isinstance(b, dict)
+ and b.get("type") == "tool_result"
+ and b.get("tool_use_id") in pend
+ ):
+ pend.discard(b.get("tool_use_id"))
+ fetched += len(text_of(b.get("content")))
+ if run:
+ bursts.append(run)
+ return {
+ "trace_found": True,
+ "tool_calls": calls,
+ "bash_calls": bash_calls,
+ "compound_bash": batched,
+ "bursts": len(bursts),
+ "max_burst": max(bursts) if bursts else 0,
+ "mean_burst": round(sum(bursts) / len(bursts), 2) if bursts else 0,
+ "fetched_chars": fetched,
+ }
+
+
+def run_one(task, arm: str, wt: Path, plugin_dir: Path, model: str | None) -> dict:
+ tid, prompt, truth, kind = task
+ env = dict(os.environ)
+ env["HEADROOM_CODEMODE"] = "1" if arm == "steered" else "0"
+ cmd = [
+ "claude",
+ "-p",
+ prompt,
+ "--output-format",
+ "json",
+ "--permission-mode",
+ "auto",
+ "--plugin-dir",
+ str(plugin_dir),
+ ]
+ if model:
+ cmd += ["--model", model]
+ t0 = time.time()
+ proc = subprocess.run(cmd, cwd=wt, env=env, capture_output=True, text=True, timeout=600)
+ wall = time.time() - t0
+ try:
+ d = json.loads(proc.stdout)
+ except Exception:
+ return {
+ "task": tid,
+ "arm": arm,
+ "error": (proc.stdout or proc.stderr)[:300],
+ "wall_s": wall,
+ }
+ u = d.get("usage") or {}
+ rec = {
+ "task": tid,
+ "arm": arm,
+ "session_id": d.get("session_id"),
+ "cost_usd": d.get("total_cost_usd"),
+ "num_turns": d.get("num_turns"),
+ "wall_s": round(wall, 1),
+ "input_tokens": u.get("input_tokens", 0),
+ "cache_creation": u.get("cache_creation_input_tokens", 0),
+ "cache_read": u.get("cache_read_input_tokens", 0),
+ "output_tokens": u.get("output_tokens", 0),
+ "answer": str(d.get("result", ""))[:200],
+ }
+ rec["correct"] = score(kind, truth, rec["answer"])
+ rec.update(trace(rec["session_id"] or ""))
+ return rec
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--worktree", required=True)
+ ap.add_argument("--plugin-dir", required=True)
+ ap.add_argument("--reps", type=int, default=1)
+ ap.add_argument("--model", default=None)
+ ap.add_argument("--out", default="benchmark_results/codemode_ab.json")
+ ap.add_argument("--suite", choices=["simple", "multi"], default="simple")
+ args = ap.parse_args()
+
+ wt = Path(args.worktree).resolve()
+ pd = Path(args.plugin_dir).resolve()
+ out = Path(args.out)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ results = json.loads(out.read_text()) if out.exists() else []
+ done = {(r["task"], r["arm"], r.get("rep")) for r in results}
+
+ suite = TASKS_MULTI if args.suite == "multi" else TASKS
+ for rep in range(args.reps):
+ for task in suite:
+ # interleave arms so prompt-cache warmth cannot favour one side
+ for arm in ("steered", "control") if rep % 2 == 0 else ("control", "steered"):
+ if (task[0], arm, rep) in done:
+ continue
+ rec = run_one(task, arm, wt, pd, args.model)
+ rec["rep"] = rep
+ results.append(rec)
+ out.write_text(json.dumps(results, indent=2))
+ print(
+ f" {task[0]:22s} {arm:8s} rep{rep} "
+ f"${rec.get('cost_usd', 0) or 0:.4f} turns={rec.get('num_turns')} "
+ f"calls={rec.get('tool_calls')} ok={rec.get('correct')}",
+ flush=True,
+ )
+ dirty = subprocess.run(
+ ["git", "status", "--porcelain"], cwd=wt, capture_output=True, text=True
+ ).stdout.strip()
+ if dirty:
+ print(f" !! worktree dirtied, resetting: {dirty[:120]}", flush=True)
+ subprocess.run(["git", "reset", "--hard", "-q"], cwd=wt)
+ subprocess.run(["git", "clean", "-qfd"], cwd=wt)
+ print(f"\nwrote {out}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/benchmarks/codemode_ab_report.py b/benchmarks/codemode_ab_report.py
new file mode 100644
index 000000000..e4af02be5
--- /dev/null
+++ b/benchmarks/codemode_ab_report.py
@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Paired report for the code-mode steering A/B (benchmarks/codemode_ab.py)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+from collections import defaultdict
+
+
+def paired(rows, key):
+ """Per-(task,rep) steered-minus-control deltas for a numeric field."""
+ by = defaultdict(dict)
+ for r in rows:
+ if r.get("error") or r.get(key) is None:
+ continue
+ by[(r["task"], r.get("rep"))][r["arm"]] = r[key]
+ return [
+ (k, v["steered"] - v["control"], v["control"], v["steered"])
+ for k, v in by.items()
+ if "steered" in v and "control" in v
+ ]
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--results", required=True)
+ args = ap.parse_args()
+ rows = json.loads(open(args.results).read())
+ # Re-grade stored answers with the current scorer so a grading fix does not
+ # require re-running (and re-paying for) the suite.
+ sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
+ from codemode_ab import TASKS, TASKS_MULTI, score
+
+ spec = {t[0]: (t[2], t[3]) for t in list(TASKS) + list(TASKS_MULTI)}
+ for r in rows:
+ if r.get("task") in spec and "answer" in r:
+ truth, kind = spec[r["task"]]
+ r["correct"] = score(kind, truth, r["answer"])
+ errs = [r for r in rows if r.get("error")]
+ rows = [r for r in rows if not r.get("error")]
+ print(f"runs: {len(rows)} errors: {len(errs)}")
+
+ for arm in ("control", "steered"):
+ a = [r for r in rows if r["arm"] == arm]
+ if not a:
+ continue
+ ok = sum(1 for r in a if r.get("correct"))
+ print(f"\n[{arm}] n={len(a)} correct={ok}/{len(a)} ({100 * ok / len(a):.0f}%)")
+ for f, label, unit in (
+ ("cost_usd", "cost", "$"),
+ ("num_turns", "turns", ""),
+ ("tool_calls", "tool calls", ""),
+ ("bash_calls", "bash calls", ""),
+ ("compound_bash", "compound bash", ""),
+ ("fetched_chars", "bytes fetched", ""),
+ ("wall_s", "wall", "s"),
+ ):
+ vals = [r.get(f) or 0 for r in a]
+ print(
+ f" {label:16s} mean {unit}{statistics.mean(vals):>10.4f} "
+ f"median {unit}{statistics.median(vals):>10.4f} total {unit}{sum(vals):>12.2f}"
+ )
+
+ print("\n=== PAIRED (steered - control), per task ===")
+ for f, label in (
+ ("cost_usd", "cost $"),
+ ("num_turns", "turns"),
+ ("tool_calls", "tool calls"),
+ ("fetched_chars", "bytes fetched"),
+ ("compound_bash", "compound bash"),
+ ):
+ d = paired(rows, f)
+ if not d:
+ continue
+ deltas = [x[1] for x in d]
+ wins = sum(1 for x in deltas if x < 0)
+ losses = sum(1 for x in deltas if x > 0)
+ mean = statistics.mean(deltas)
+ ctrl_tot = sum(x[2] for x in d)
+ pct = 100 * sum(deltas) / ctrl_tot if ctrl_tot else 0
+ line = (
+ f" {label:16s} mean Δ {mean:+12.4f} total Δ {sum(deltas):+12.4f} "
+ f"({pct:+.1f}%) steered better/worse/tie: {wins}/{losses}/{len(deltas) - wins - losses}"
+ )
+ if len(deltas) > 1:
+ sd = statistics.stdev(deltas)
+ se = sd / (len(deltas) ** 0.5)
+ line += f" 95%CI [{mean - 1.96 * se:+.4f}, {mean + 1.96 * se:+.4f}]"
+ print(line)
+
+ print("\n=== per-task cost detail ===")
+ d = paired(rows, "cost_usd")
+ print(f" {'task':24s} {'control':>10s} {'steered':>10s} {'delta':>10s} {'Δ%':>7s}")
+ for (task, _rep), delta, c, s in sorted(d):
+ print(f" {task:24s} {c:10.4f} {s:10.4f} {delta:+10.4f} {100 * delta / c:+6.1f}%")
+
+ d = paired(rows, "correct")
+ regress = [k for k, dd, c, s in d if c and not s]
+ if regress:
+ print(f"\n !! correctness REGRESSED on: {regress}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/benchmarks/results/index_proof_table.txt b/benchmarks/results/index_proof_table.txt
new file mode 100644
index 000000000..75c95002a
--- /dev/null
+++ b/benchmarks/results/index_proof_table.txt
@@ -0,0 +1,32 @@
+Native content detection requires ONNX Runtime 1.24+; using pure-Python detection for this process.
+seed=20260902 model=gpt-5.6 tokenizer=TiktokenCounter
+
+=== default (protect_recent=4) ===
+Scenario Before After Savings
+--------------------------------------------------------------
+Code search (100 results) 17,199 13,597 21%
+SRE incident debugging 55,957 24,340 57%
+Codebase exploration 58,801 33,895 42%
+GitHub issue triage 46,067 32,429 30%
+--------------------------------------------------------------
+TOTAL 178,024 104,261 41%
+
+=== full corpus (protect_recent=0) ===
+Scenario Before After Savings
+--------------------------------------------------------------
+Code search (100 results) 17,199 13,597 21%
+SRE incident debugging 55,957 24,340 57%
+Codebase exploration 58,801 33,895 42%
+GitHub issue triage 46,067 32,429 30%
+--------------------------------------------------------------
+TOTAL 178,024 104,261 41%
+
+
+Markdown for docs/content/docs/index.mdx (full-corpus config, which must be stated on the page):
+
+| Scenario | Before | After | Savings |
+|---|---|---|---|
+| Code search (100 results) | 17,199 | 13,597 | **21%** |
+| SRE incident debugging | 55,957 | 24,340 | **57%** |
+| Codebase exploration | 58,801 | 33,895 | **42%** |
+| GitHub issue triage | 46,067 | 32,429 | **30%** |
diff --git a/crates/headroom-core/src/ccr/mod.rs b/crates/headroom-core/src/ccr/mod.rs
index d810414ef..cf076f848 100644
--- a/crates/headroom-core/src/ccr/mod.rs
+++ b/crates/headroom-core/src/ccr/mod.rs
@@ -27,7 +27,7 @@
//! [`backends::from_config`] selects one at startup and surfaces every
//! init error to the caller (per `feedback_no_silent_fallbacks.md`).
//!
-//! [`CompressionStore`]: https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py
+//! [`CompressionStore`]: https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cache/compression_store.py
pub mod backends;
diff --git a/crates/headroom-py/build.rs b/crates/headroom-py/build.rs
index f8108932d..848e6b6e3 100644
--- a/crates/headroom-py/build.rs
+++ b/crates/headroom-py/build.rs
@@ -16,7 +16,7 @@
// don't reference any of these symbols.
//
// Issues:
-// - #355 (https://github.com/chopratejas/headroom/issues/355)
+// - #355 (https://github.com/headroomlabs-ai/headroom/issues/355)
// for the `__isoc23_*` family
// - PR #396 dry-run for the `__libc_single_threaded` symbol
diff --git a/e2e/init/Dockerfile b/e2e/init/Dockerfile
index 0a2d0b15b..c4fbb870a 100644
--- a/e2e/init/Dockerfile
+++ b/e2e/init/Dockerfile
@@ -43,7 +43,7 @@ ENV DEBIAN_FRONTEND=noninteractive \
# Single-wheel refactor side effect: `headroom` is now installed
# from a wheel into site-packages, so `__file__.parents[2]` no
# longer points at the repo root (it points at site-packages).
- # `_marketplace_source()` falls back to `chopratejas/headroom`
+ # `_marketplace_source()` falls back to `headroomlabs-ai/headroom`
# (the GitHub remote) instead of the local `/workspace` path the
# `seq_claude_local` e2e assertion expects. Pin the source via
# the existing override env var so the local `/workspace`
diff --git a/examples/07-context-compression.ipynb b/examples/07-context-compression.ipynb
index ff2ed74eb..7e49dcc1c 100644
--- a/examples/07-context-compression.ipynb
+++ b/examples/07-context-compression.ipynb
@@ -17,7 +17,7 @@
"\n",
"## Context Compression in Practice\n",
"\n",
- "[Headroom](https://github.com/chopratejas/headroom) is an open-source context optimization library that provides multi-algorithm compression. It auto-detects content type (JSON, code, logs, text) and routes to the optimal compressor:\n",
+ "[Headroom](https://github.com/headroomlabs-ai/headroom) is an open-source context optimization library that provides multi-algorithm compression. It auto-detects content type (JSON, code, logs, text) and routes to the optimal compressor:\n",
"\n",
"- **SmartCrusher**: Statistically analyzes JSON arrays \u2014 keeps errors, anomalies, and query-relevant items\n",
"- **Kompress**: ModernBERT token classifier \u2014 removes redundant tokens from text while preserving meaning\n",
diff --git a/headroom/cli/init.py b/headroom/cli/init.py
index 2b6f4bf4c..8914900d8 100644
--- a/headroom/cli/init.py
+++ b/headroom/cli/init.py
@@ -656,7 +656,7 @@ def _marketplace_source() -> str:
repo_root = Path(__file__).resolve().parents[2]
if (repo_root / ".claude-plugin" / "marketplace.json").exists():
return str(repo_root)
- return "chopratejas/headroom"
+ return "headroomlabs-ai/headroom"
def _run_checked(command: list[str], *, action: str) -> None:
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 6ea93ca37..4cdafc265 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -6079,7 +6079,7 @@ def vscode_claude(
click.echo(" Keep this command running. Press Ctrl+C to stop the proxy.")
click.echo(" Authentication and the selected Claude model are preserved.")
click.echo(" Undo later with: headroom unwrap vscode-claude")
- click.echo(" Guide: https://headroom-docs.vercel.app/docs/vscode-claude-code")
+ click.echo(" Guide: https://docs.headroomlabs.ai/docs/vscode-claude-code")
return
click.echo(f" Add these values under 'env' in {target_settings}:")
click.echo(f' "ANTHROPIC_BASE_URL": "{proxy_url}",')
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index 6e5353cd9..8f4c5a494 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -1961,7 +1961,7 @@
Press <kbd class="px-1.5 py-0.5 bg-border rounded text-gray-400">R</kbd> to refresh
</div>
<div>
- <a href="https://headroom-docs.vercel.app/docs" target="_blank" class="hover:text-gray-300 transition-colors">Documentation</a>
+ <a href="https://docs.headroomlabs.ai/docs" target="_blank" class="hover:text-gray-300 transition-colors">Documentation</a>
</div>
</div>
</footer>
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index fc57686a3..bef15b77b 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -3014,7 +3014,7 @@ def format_tool_search_disabled_hint(tools: list[Any]) -> str:
"ENABLE_TOOL_SEARCH is unset with a custom ANTHROPIC_BASE_URL. Set "
"ENABLE_TOOL_SEARCH=true (or auto) to keep on-demand tool loading active, "
"or launch via `headroom wrap claude` (which sets it automatically). "
- "See https://github.com/chopratejas/headroom/issues/746"
+ "See https://github.com/headroomlabs-ai/headroom/issues/746"
)
diff --git a/llms.txt b/llms.txt
index fe2412fdb..580e1a97b 100644
--- a/llms.txt
+++ b/llms.txt
@@ -8,10 +8,10 @@ The canonical, always-current documentation index lives at the docs site below.
## Canonical docs (start here)
-- [Live llms.txt (full doc index)](https://headroom-docs.vercel.app/llms.txt): Auto-generated index of every doc page with descriptions.
-- [Live llms-full.txt (every doc page concatenated)](https://headroom-docs.vercel.app/llms-full.txt): One Markdown blob containing every doc page. Use when you can spend the tokens for full context.
-- [Docs site](https://headroom-docs.vercel.app/docs): Human-browsable docs with search.
-- [GitHub repo](https://github.com/chopratejas/headroom): Source, issues, releases.
+- [Live llms.txt (full doc index)](https://docs.headroomlabs.ai/llms.txt): Auto-generated index of every doc page with descriptions.
+- [Live llms-full.txt (every doc page concatenated)](https://docs.headroomlabs.ai/llms-full.txt): One Markdown blob containing every doc page. Use when you can spend the tokens for full context.
+- [Docs site](https://docs.headroomlabs.ai/docs): Human-browsable docs with search.
+- [GitHub repo](https://github.com/headroomlabs-ai/headroom): Source, issues, releases.
- [PyPI package](https://pypi.org/project/headroom-ai/): Python install.
- [npm package](https://www.npmjs.com/package/headroom-ai): TypeScript install.
@@ -25,42 +25,42 @@ The canonical, always-current documentation index lives at the docs site below.
## Entry points
-- [Quickstart](https://headroom-docs.vercel.app/docs/quickstart): 5-minute end-to-end (install → compress → call the model).
-- [Installation](https://headroom-docs.vercel.app/docs/installation): All install paths, extras, Docker tags, env vars.
-- [Proxy server](https://headroom-docs.vercel.app/docs/proxy): Run as a local HTTP proxy in front of OpenAI / Anthropic / Gemini.
-- [MCP server](https://headroom-docs.vercel.app/docs/mcp): `headroom_compress`, `headroom_retrieve`, `headroom_stats` for Claude Code / Cursor / any MCP host.
-- [API reference](https://headroom-docs.vercel.app/docs/api-reference): Python + TypeScript `compress()` API.
+- [Quickstart](https://docs.headroomlabs.ai/docs/quickstart): 5-minute end-to-end (install → compress → call the model).
+- [Installation](https://docs.headroomlabs.ai/docs/installation): All install paths, extras, Docker tags, env vars.
+- [Proxy server](https://docs.headroomlabs.ai/docs/proxy): Run as a local HTTP proxy in front of OpenAI / Anthropic / Gemini.
+- [MCP server](https://docs.headroomlabs.ai/docs/mcp): `headroom_compress`, `headroom_retrieve`, `headroom_stats` for Claude Code / Cursor / any MCP host.
+- [API reference](https://docs.headroomlabs.ai/docs/api-reference): Python + TypeScript `compress()` API.
## How it works
-- [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works): Three-stage pipeline + automatic content routing.
-- [SmartCrusher](https://headroom-docs.vercel.app/docs/smart-crusher): Statistical JSON / array compression (70–90% on tool outputs).
-- [Code compression](https://headroom-docs.vercel.app/docs/code-compression): AST-aware via tree-sitter (preserves imports, signatures, types).
-- [Text & log compression](https://headroom-docs.vercel.app/docs/text-and-logs): Search results, build logs, diffs.
-- [CCR (reversible)](https://headroom-docs.vercel.app/docs/ccr): Compress-Cache-Retrieve — originals never deleted; LLM retrieves on demand.
+- [How compression works](https://docs.headroomlabs.ai/docs/how-compression-works): Three-stage pipeline + automatic content routing.
+- [SmartCrusher](https://docs.headroomlabs.ai/docs/smart-crusher): Statistical JSON / array compression (70–90% on tool outputs).
+- [Code compression](https://docs.headroomlabs.ai/docs/code-compression): AST-aware via tree-sitter (preserves imports, signatures, types).
+- [Text & log compression](https://docs.headroomlabs.ai/docs/text-and-logs): Search results, build logs, diffs.
+- [CCR (reversible)](https://docs.headroomlabs.ai/docs/ccr): Compress-Cache-Retrieve — originals never deleted; LLM retrieves on demand.
## SDK / framework integrations
-- [Anthropic SDK](https://headroom-docs.vercel.app/docs/anthropic-sdk): `withHeadroom(anthropic)` wrapper.
-- [OpenAI SDK](https://headroom-docs.vercel.app/docs/openai-sdk): `withHeadroom(openai)` wrapper.
-- [Vercel AI SDK](https://headroom-docs.vercel.app/docs/vercel-ai-sdk): Middleware + `withHeadroom()`.
-- [LangChain](https://headroom-docs.vercel.app/docs/langchain): Chat models, memory, retrievers, agents.
-- [Agno](https://headroom-docs.vercel.app/docs/agno): Model wrapping + observability hooks.
-- [Strands](https://headroom-docs.vercel.app/docs/strands): Model wrapping + hook-based tool output compression.
-- [LiteLLM](https://headroom-docs.vercel.app/docs/litellm): Single callback; works with all 100+ LiteLLM providers.
+- [Anthropic SDK](https://docs.headroomlabs.ai/docs/anthropic-sdk): `withHeadroom(anthropic)` wrapper.
+- [OpenAI SDK](https://docs.headroomlabs.ai/docs/openai-sdk): `withHeadroom(openai)` wrapper.
+- [Vercel AI SDK](https://docs.headroomlabs.ai/docs/vercel-ai-sdk): Middleware + `withHeadroom()`.
+- [LangChain](https://docs.headroomlabs.ai/docs/langchain): Chat models, memory, retrievers, agents.
+- [Agno](https://docs.headroomlabs.ai/docs/agno): Model wrapping + observability hooks.
+- [Strands](https://docs.headroomlabs.ai/docs/strands): Model wrapping + hook-based tool output compression.
+- [LiteLLM](https://docs.headroomlabs.ai/docs/litellm): Single callback; works with all 100+ LiteLLM providers.
## Memory & cross-agent state
-- [Persistent memory](https://headroom-docs.vercel.app/docs/memory): Per-project SQLite + HNSW vector store. No cross-project bleed (GH #462).
-- [SharedContext](https://headroom-docs.vercel.app/docs/shared-context): Compressed inter-agent context handoffs.
-- [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning): Offline analysis writes corrections to `CLAUDE.local.md` (default, gitignored) or `CLAUDE.md` (shared) / `AGENTS.md` / `GEMINI.md`.
+- [Persistent memory](https://docs.headroomlabs.ai/docs/memory): Per-project SQLite + HNSW vector store. No cross-project bleed (GH #462).
+- [SharedContext](https://docs.headroomlabs.ai/docs/shared-context): Compressed inter-agent context handoffs.
+- [Failure learning](https://docs.headroomlabs.ai/docs/failure-learning): Offline analysis writes corrections to `CLAUDE.local.md` (default, gitignored) or `CLAUDE.md` (shared) / `AGENTS.md` / `GEMINI.md`.
## Operations
-- [Configuration](https://headroom-docs.vercel.app/docs/configuration): Env vars, config file, per-call overrides.
-- [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks): Token-savings numbers across content types.
-- [Troubleshooting](https://headroom-docs.vercel.app/docs/troubleshooting): Common failure modes and fixes.
-- [Limitations](https://headroom-docs.vercel.app/docs/limitations): What Headroom won't do well today.
+- [Configuration](https://docs.headroomlabs.ai/docs/configuration): Env vars, config file, per-call overrides.
+- [Benchmarks](https://docs.headroomlabs.ai/docs/benchmarks): Token-savings numbers across content types.
+- [Troubleshooting](https://docs.headroomlabs.ai/docs/troubleshooting): Common failure modes and fixes.
+- [Limitations](https://docs.headroomlabs.ai/docs/limitations): What Headroom won't do well today.
## Licensing
diff --git a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
index 60ee59fcc..77d5b0f0e 100644
--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
@@ -4,10 +4,10 @@
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"author": {
"name": "Headroom Contributors",
- "url": "https://github.com/chopratejas/headroom"
+ "url": "https://github.com/headroomlabs-ai/headroom"
},
- "homepage": "https://github.com/chopratejas/headroom",
- "repository": "https://github.com/chopratejas/headroom",
+ "homepage": "https://github.com/headroomlabs-ai/headroom",
+ "repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
diff --git a/plugins/headroom-agent-hooks/.github/plugin/plugin.json b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
index 556945b17..b31a0b436 100644
--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
@@ -4,10 +4,10 @@
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"author": {
"name": "Headroom Contributors",
- "url": "https://github.com/chopratejas/headroom"
+ "url": "https://github.com/headroomlabs-ai/headroom"
},
- "homepage": "https://github.com/chopratejas/headroom",
- "repository": "https://github.com/chopratejas/headroom",
+ "homepage": "https://github.com/headroomlabs-ai/headroom",
+ "repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
diff --git a/plugins/headroom-oauth2/README.md b/plugins/headroom-oauth2/README.md
index 7cd14dcdb..cd24752fd 100644
--- a/plugins/headroom-oauth2/README.md
+++ b/plugins/headroom-oauth2/README.md
@@ -1,7 +1,7 @@
# headroom-oauth2
Generic **OAuth2 client-credentials** upstream-auth extension for the
-[Headroom](https://github.com/chopratejas/headroom) proxy.
+[Headroom](https://github.com/headroomlabs-ai/headroom) proxy.
When Headroom routes to an OpenAI-compatible backend that is protected by an
OAuth2 client-credentials flow (enterprise AI gateways, Azure AD / Entra, Okta,
diff --git a/plugins/headroom-oauth2/pyproject.toml b/plugins/headroom-oauth2/pyproject.toml
index 023b56af7..cad217119 100644
--- a/plugins/headroom-oauth2/pyproject.toml
+++ b/plugins/headroom-oauth2/pyproject.toml
@@ -32,9 +32,9 @@ dev = ["pytest>=7", "ruff"]
test = ["pytest>=7"]
[project.urls]
-Homepage = "https://github.com/chopratejas/headroom"
-Repository = "https://github.com/chopratejas/headroom"
-Issues = "https://github.com/chopratejas/headroom/issues"
+Homepage = "https://github.com/headroomlabs-ai/headroom"
+Repository = "https://github.com/headroomlabs-ai/headroom"
+Issues = "https://github.com/headroomlabs-ai/headroom/issues"
# Registers with Headroom's opt-in proxy-extension seam (headroom/proxy/extensions.py).
# Enable at runtime with `--proxy-extension oauth2` or HEADROOM_PROXY_EXTENSIONS=oauth2.
diff --git a/plugins/openclaw/src/plugin/index.ts b/plugins/openclaw/src/plugin/index.ts
index ee807de0a..c8dde3887 100644
--- a/plugins/openclaw/src/plugin/index.ts
+++ b/plugins/openclaw/src/plugin/index.ts
@@ -26,7 +26,7 @@ import { createHeadroomRetrieveTool } from "../tools/headroom-retrieve.js";
/**
* OpenClaw 2026.x plugin API requires a `{ register(api) }` object export.
* The previous bare-function default export was silently skipped by the loader.
- * See: https://github.com/chopratejas/headroom/issues/XXX
+ * See: https://github.com/headroomlabs-ai/headroom/issues/XXX
*/
export default {
register: registerHeadroomPlugin,
diff --git a/pyproject.toml b/pyproject.toml
index 09a9cedfa..44d87f5e4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -334,15 +334,15 @@ sandbox = [
headroom = "headroom.cli:main"
[project.urls]
-Homepage = "https://headroom-docs.vercel.app"
-Documentation = "https://headroom-docs.vercel.app/docs"
-Repository = "https://github.com/chopratejas/headroom"
-Issues = "https://github.com/chopratejas/headroom/issues"
-Changelog = "https://github.com/chopratejas/headroom/blob/main/CHANGELOG.md"
+Homepage = "https://docs.headroomlabs.ai"
+Documentation = "https://docs.headroomlabs.ai/docs"
+Repository = "https://github.com/headroomlabs-ai/headroom"
+Issues = "https://github.com/headroomlabs-ai/headroom/issues"
+Changelog = "https://github.com/headroomlabs-ai/headroom/blob/main/CHANGELOG.md"
# llms.txt convention (llmstxt.org) — point AI agents / LLM crawlers
# at the auto-generated docs index so they can resolve install paths
# and entry points without a follow-up fetch.
-"AI / LLM Index" = "https://headroom-docs.vercel.app/llms.txt"
+"AI / LLM Index" = "https://docs.headroomlabs.ai/llms.txt"
# Maturin builds a single wheel containing both the Python source under
# `headroom/` AND the compiled Rust extension `headroom/_core.so` (cdylib
diff --git a/sbom/headroom-python-licenses.csv b/sbom/headroom-python-licenses.csv
index 680c664ef..07a912d31 100644
--- a/sbom/headroom-python-licenses.csv
+++ b/sbom/headroom-python-licenses.csv
@@ -83,7 +83,7 @@
"grpclib","0.4.9","BSD License","https://github.com/vmagamedov/grpclib"
"h11","0.16.0","MIT License","https://github.com/python-hyper/h11"
"h2","4.3.0","MIT License","https://github.com/python-hyper/h2/"
-"headroom-ai","0.27.0","Apache-2.0","https://headroom-docs.vercel.app"
+"headroom-ai","0.27.0","Apache-2.0","https://docs.headroomlabs.ai"
"headroom-security","0.1.0","Proprietary","UNKNOWN"
"hf-xet","1.2.0","Apache-2.0","https://github.com/huggingface/xet-core"
"hnswlib","0.8.0","UNKNOWN","https://github.com/yurymalkov/hnsw"
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 9926690de..a93d7ef5a 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -1803,4 +1803,4 @@ Write-Host ""
Write-Host "Next steps:"
Write-Host " 1. Restart PowerShell"
Write-Host " 2. Try: headroom proxy"
-Write-Host " 3. Docs: https://github.com/chopratejas/headroom/blob/main/docs/docker-install.md"
+Write-Host " 3. Docs: https://docs.headroomlabs.ai/docs/docker-install"
diff --git a/scripts/install.sh b/scripts/install.sh
index d65a6db59..b8125bb45 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1607,7 +1607,7 @@ Installed wrapper:
Next steps:
1. Restart your shell or run: export PATH="${INSTALL_DIR}:\$PATH"
2. Try: headroom proxy
- 3. Docs: https://github.com/chopratejas/headroom/blob/main/docs/docker-install.md
+ 3. Docs: https://docs.headroomlabs.ai/docs/docker-install
EOF
}
diff --git a/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json b/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json
index bbb6df33e..448262585 100644
--- a/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json
+++ b/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
- "$id": "https://github.com/chopratejas/headroom/blob/main/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json",
+ "$id": "https://github.com/headroomlabs-ai/headroom/blob/main/tests/parity/fixtures/codex_openai_contracts/codex-openai-interaction.schema.json",
"title": "Codex <-> OpenAI interaction contracts (PR #794)",
"description": "Enshrines the OpenAI interaction expectations this changeset depends on, so drift is detectable. Header values are transported as strings on the wire; the `x-headroom-parsed-type` annotation on each records the semantic type the parser (headroom/subscription/codex_rate_limits.py) coerces them to. Sources: codex_rate_limits.parse_codex_rate_limits (header family + gating), openai._extract_codex_handshake_headers (WS-101 forward filter), streaming.py (SSE forward filter).",
"$defs": {
diff --git a/tests/test_parser.py b/tests/test_parser.py
index bfd1908ac..8342f249e 100644
--- a/tests/test_parser.py
+++ b/tests/test_parser.py
@@ -920,7 +920,7 @@ def sample_messages_with_tools():
]
-# --- Anthropic tool_result content blocks (chopratejas/headroom#813) ---
+# --- Anthropic tool_result content blocks (headroomlabs-ai/headroom#813) ---
@pytest.fixture
diff --git a/tests/test_plugin_manifests.py b/tests/test_plugin_manifests.py
index 578f4f279..999ceb923 100644
--- a/tests/test_plugin_manifests.py
+++ b/tests/test_plugin_manifests.py
@@ -41,7 +41,7 @@ def test_marketplace_entry_points_to_plugin_root() -> None:
def test_plugin_metadata_points_to_upstream_repo() -> None:
- expected_repo = "https://github.com/chopratejas/headroom"
+ expected_repo = "https://github.com/headroomlabs-ai/headroom"
marketplace = _load_json(".claude-plugin/marketplace.json")
claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
assert isinstance(marketplace, dict)
diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.py
index 732edda23..b5197ae6d 100644
--- a/tests/test_release_workflows.py
+++ b/tests/test_release_workflows.py
@@ -931,7 +931,7 @@ def test_glibc_compat_shim_present_in_headroom_py() -> None:
"""STRUCTURAL INVARIANT: the headroom-py crate ships a glibc-2.38
compatibility shim that defines weak `__isoc23_*` aliases.
- Issue #355 (https://github.com/chopratejas/headroom/issues/355) —
+ Issue #355 (https://github.com/headroomlabs-ai/headroom/issues/355) —
the published wheel's `_core.so` references `__isoc23_strtoll`
(glibc 2.38+) because we statically link prebuilt ONNX Runtime
artifacts compiled with gcc 14. Users with libc < 2.38 (Ubuntu