headroom.walls.sh · install
Claude Code is a CLI tool published by Anthropic. It installs via npm and requires a Claude Pro or Max subscription (or an Anthropic API key). This guide covers installation on macOS, Linux, and Windows, plus how to verify everything is working.
node --version. Install from nodejs.org or via Homebrew: brew install nodenpm install -g @anthropic-ai/claude-code
The -g flag installs globally so the claude command is available everywhere. This downloads ~50 MB.
claude --version
You should see a version number like 1.x.x. If you get "command not found," your npm global bin directory isn't in your PATH — see troubleshooting below.
claude
On first run, Claude Code opens a browser window to authenticate with your Anthropic account. Sign in with the account that has your Claude Pro or Max subscription. After auth, the CLI stores a credential in your system keychain (macOS) or ~/.anthropic (Linux/Windows).
claude "Say hello in one sentence"
If you see a response, Claude Code is fully installed and authenticated. If you see an auth error, re-run claude to re-trigger the login flow.
The recommended install path on macOS. Credentials are stored in the macOS Keychain. The statusLineHook (which Headroom reads) is written to ~/.claude/settings.json on first launch.
If you use Homebrew's Node and get a permissions error, use npm install -g @anthropic-ai/claude-code without sudo — Homebrew Node is user-owned.
Works on any Linux with Node 18+. Credentials are stored in ~/.anthropic/. The claude binary goes to your npm global bin, typically ~/.npm-global/bin/ or /usr/local/bin/ depending on your npm config.
To check where npm installs globals: npm config get prefix — ensure that path's bin/ subdirectory is in your PATH.
Claude Code works on Windows via WSL2 (Windows Subsystem for Linux) or PowerShell. WSL2 is the recommended path — you get a full Linux environment and the behavior matches macOS/Linux exactly. Install Node in WSL2 and follow the Linux steps.
In native PowerShell, the install command is the same, but some shell integration features (statusLineHook, prompt integration) require a bash-compatible shell.
npm's global bin directory isn't in your PATH. Find it with:
npm config get prefix
Then add the bin/ subdirectory to your shell profile. For macOS/Linux with zsh:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
Try clearing the stored credentials and re-authenticating:
claude auth logout claude
If you're using an API key instead of OAuth, set it as an environment variable:
export ANTHROPIC_API_KEY="sk-ant-..." claude
→ Environment variables reference
Never use sudo npm install -g — it can break your npm permissions. Instead, configure npm to install globals to a user-owned directory:
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc npm install -g @anthropic-ai/claude-code
This means the statusLineHook hasn't written data yet. Run at least one Claude Code command (e.g., claude "hello") to trigger the hook and populate ~/.claude/headroom-usage.json.
Once Claude Code is running, it writes your session and weekly usage to ~/.claude/headroom-usage.json via its statusLineHook. Headroom reads that file and shows both meters in your menu bar — so you always know where you stand before starting a session:
Free, zero config, ~267 KB. macOS 13+, signed and notarized. Works alongside Claude Code immediately after install.
Claude Code has a 5-hour session window and a 7-day weekly cap — both rolling, both invisible unless you run /usage manually. Headroom shows both in your menu bar from the moment you start a session.
→ Claude Code settings.json reference
→ Environment variables
→ Homebrew install guide
→ Frequently asked questions
→ Rate limits explained