Repository navigation
docs: clarify the headroom CLI is pip-only; npm headroom-ai is the TS SDK - #1585
Merged
chopratejas merged 1 commit intoJun 30, 2026
Merged
Conversation
The Get started and Install blocks listed 'npm install headroom-ai' next to the pip install and immediately followed with 'headroom wrap claude', implying the npm package provides the CLI. It doesn't — npm headroom-ai is the TypeScript SDK (a library, no bin), and the headroom CLI ships only via the PyPI package. Spell out the split so Windows/Node users don't hit 'headroom is not recognized' after an npm-only install. Closes headroomlabs-ai#1470
Contributor
PR governanceThis PR follows the template and is marked ready for human review. |
JerrettDavis
pushed a commit
to peterlodri-sec/headroom
that referenced
this pull request
Jul 14, 2026
… SDK (headroomlabs-ai#1585) ## Description `npm install headroom-ai` doesn't give you the `headroom` CLI — it's the TypeScript SDK (a library, no `bin`). The README's "Get started" and "Install" blocks listed the npm install next to the pip install and then immediately ran `headroom wrap claude`, so Node/Windows users reasonably expected npm to provide the CLI and hit `'headroom' is not recognized`. This spells out the split: CLI = pip, SDK = npm. The hnswlib/MSVC half of the report was already fixed on main in headroomlabs-ai#1499 (moved hnswlib to the optional `[vector]` extra), so this PR only addresses the npm-CLI confusion. Closes headroomlabs-ai#1470 ## Type of Change - [x] Documentation update ## Changes Made - README "Get started" + "Install" blocks: annotate that pip ships the `headroom` CLI and npm `headroom-ai` is the TS SDK with no CLI; note the `headroom` commands come from the pip install. - `docs/content/docs/installation.mdx`: state the TS SDK does not install the `headroom` CLI. ## Testing - [x] Manual testing performed ### Test Output ```text Docs-only change. Verified against the source of truth: - pyproject.toml: [project.scripts] headroom = "headroom.cli:main" (CLI entry point is Python-only) - sdk/typescript/package.json: name "headroom-ai", no "bin" field (SDK, no CLI) ``` ## Real Behavior Proof - Environment: repo main @ HEAD - Exact command / steps: read `[project.scripts]` in pyproject.toml and the `bin` field in sdk/typescript/package.json - Observed result: `headroom` console script is defined only by the Python package; the npm package has no `bin`, so `npm install headroom-ai` provides no `headroom` command — matching the issue. - Not tested: n/a (no code paths changed) ## 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 made corresponding changes to the documentation - [x] My changes generate no new warnings
1 of 6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
npm install headroom-aidoesn't give you theheadroomCLI — it's the TypeScript SDK (a library, nobin). The README's "Get started" and "Install" blocks listed the npm install next to the pip install and then immediately ranheadroom wrap claude, so Node/Windows users reasonably expected npm to provide the CLI and hit'headroom' is not recognized. This spells out the split: CLI = pip, SDK = npm.The hnswlib/MSVC half of the report was already fixed on main in #1499 (moved hnswlib to the optional
[vector]extra), so this PR only addresses the npm-CLI confusion.Closes #1470
Type of Change
Changes Made
headroomCLI and npmheadroom-aiis the TS SDK with no CLI; note theheadroomcommands come from the pip install.docs/content/docs/installation.mdx: state the TS SDK does not install theheadroomCLI.Testing
Test Output
Real Behavior Proof
[project.scripts]in pyproject.toml and thebinfield in sdk/typescript/package.jsonheadroomconsole script is defined only by the Python package; the npm package has nobin, sonpm install headroom-aiprovides noheadroomcommand — matching the issue.Review Readiness
Checklist