headroom: The Token-Compression CLI That Cuts Your LLM API Costs by 60–95%headroom：一款能将您的 LLM API 成本降低 60–95% 的 Token 压缩 CLI 工具

Every major LLM API charges per token. Token compression offers the most direct path to reducing those costs without changing models, degrading output quality, or rearchitecting prompts. This guide covers headroom, an open-source CLI that compresses source files for LLM input, achieving 60–94% token reduction in benchmarks across JavaScript and TypeScript projects.每个主流 LLM API 都是按 Token 收费的。Token 压缩提供了一条最直接的途径，可以在不更换模型、不降低输出质量或不重构提示词的情况下降低这些成本。本指南介绍了 headroom，这是一个开源 CLI 工具，用于压缩 LLM 输入的源代码文件，在 JavaScript 和 TypeScript 项目的基准测试中实现了 60–94% 的 Token 缩减。

Table of Contents目录

• Why Token Compression Is the Easiest LLM Cost Win为什么 Token 压缩是降低 LLM 成本最简单的方法
• What Is headroom and How Does It Work?什么是 headroom 以及它是如何工作的？
• Installing and Setting Up headroom安装和设置 headroom
• Basic Usage: Compressing Your First File基本用法：压缩您的第一个文件
• Configuration and Compression Profiles配置和压缩配置文件
• Integrating headroom Into a Node.js/React Workflow将 headroom 集成到 Node.js/React 工作流中
• Benchmarks: Real-World Token Savings基准测试：实际的 Token 节省情况
• Best Practices and Pitfalls最佳实践与陷阱
• Implementation Checklist实施检查清单
• Stop Paying for Tokens That Don't Matter停止为无关紧要的 Token 付费

Why Token Compression Is the Easiest LLM Cost Win

Every major LLM API charges per token. GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro: all charge per token, though each uses a different tokenizer. Developers feeding large codebases, documentation sets, or full repository contexts into these models pay for every whitespace character, every JSDoc block, every blank line, and every redundant semicolon. Token compression offers the most direct path to reducing those costs without changing models, degrading output quality, or rearchitecting prompts.每个主流 LLM API 都是按 Token 收费的。GPT-4o、Claude 3.5 Sonnet、Gemini 1.5 Pro：它们都按 Token 收费，尽管各自使用不同的分词器（tokenizer）。开发者将大型代码库、文档集或完整的仓库上下文输入到这些模型中时，需要为每一个空格字符、每一个 JSDoc 块、每一个空行和每一个多余的分号付费。Token 压缩提供了一条最直接的途径，可以在不更换模型、不降低输出质量或不重构提示词的情况下降低这些成本。

Consider the math. Sending a 50,000-token codebase context to GPT-4o at $2.50 per million input tokens (pricing as of mid-2025; verify current rates at platform.openai.com/pricing) costs $0.125 per request. Compress that to 5,000 tokens and the same request costs $0.0125. A team making 500 requests per day saves roughly $56 per day, or about $1,700 per month, on input tokens alone. Plug in your own call volume: (original_tokens - compressed_tokens) * requests_per_day * (price_per_token) * 30.算一算账。将 50,000 个 Token 的代码库上下文发送给 GPT-4o，按每百万输入 Token 2.50 美元计算（价格截至 2025 年年中；请在 platform.openai.com/pricing 查看当前费率），每次请求成本为 0.125 美元。将其压缩至 5,000 个 Token，同样的请求成本仅为 0.0125 美元。一个每天进行 500 次请求的团队，仅在输入 Token 上每天就能节省约 56 美元，即每月约 1,700 美元。代入您自己的调用量：(原始 Token - 压缩后 Token) * 每天请求数 * (每个 Token 的价格) * 30。

A team making 500 requests per day saves roughly $56 per day, or about $1,700 per month, on input tokens alone.一个每天进行 500 次请求的团队，仅在输入 Token 上每天就能节省约 56 美元，即每月约 1,700 美元。

headroom is an open-source CLI that compresses source files for LLM input rather than browser delivery. It parses code using AST-level analysis and applies token compression strategies optimized for LLM consumption. In benchmarks across three JavaScript/TypeScript projects, it achieved 60–94% token reduction depending on compression level, without sacrificing semantic meaning. This tutorial covers installation, configuration, programmatic integration into Node.js and React workflows, and benchmarking. It ends with a complete implementation checklist readers can follow step by step.headroom 是一个开源 CLI 工具，用于压缩 LLM 输入的源代码文件，而非用于浏览器交付。它使用 AST 级分析来解析代码，并应用针对 LLM 使用场景优化的 Token 压缩策略。在三个 JavaScript/TypeScript 项目的基准测试中，根据压缩级别的不同，它实现了 60–94% 的 Token 缩减，且没有牺牲语义含义。本教程涵盖了安装、配置、集成到 Node.js 和 React 工作流的编程实现以及基准测试。最后提供了一份读者可以按步骤执行的完整实施检查清单。

Note: At the time of writing, verify that the headroom-cli package on npm matches the tool described here before installing. Confirm the package description and homepage at npmjs.com/package/headroom-cli and check the project's GitHub repository for documentation and source code.注意：在撰写本文时，请在安装前确认 npm 上的 headroom-cli 包与此处描述的工具相符。请在 npmjs.com/package/headroom-cli 确认包描述和主页，并查看项目的 GitHub 仓库以获取文档和源代码。

What Is headroom and How Does It Work?

Core Concept: Compression for LLMs, Not Browsers核心概念：面向 LLM 的压缩，而非面向浏览器

Traditional minification tools like Terser or esbuild exist to reduce JavaScript bundle sizes for browser delivery. They preserve runtime behavior, mangle variable names for byte savings, and optimize execution paths. Token compression for LLM consumption has a fundamentally different goal: reduce token count while preserving semantic meaning that a language model needs to reason about the code.传统的压缩工具（如 Terser 或 esbuild）旨在减小 JavaScript 包大小以供浏览器交付。它们保留运行时行为，通过混淆变量名来节省字节，并优化执行路径。而面向 LLM 使用的 Token 压缩有着根本不同的目标：在减少 Token 数量的同时，保留语言模型理解代码所需的语义含义。

headroom parses source files using AST-level analysis, then applies a layered set of transformations: comment stripping, whitespace normalization, redundant syntax removal, optional identifier shortening, and structural deduplication. Import paths, function signatures, and logical flow remain intact. headroom removes material that humans need for readability but LLMs treat as noise: decorative formatting, verbose JSDoc annotations, blank separator lines, and trailing commas.headroom 使用 AST 级分析解析源代码，然后应用一系列分层转换：注释剥离、空格规范化、冗余语法移除、可选的标识符缩短以及结构去重。导入路径、函数签名和逻辑流保持不变。headroom 移除了人类阅读所需但 LLM 视为噪声的内容：装饰性格式、冗长的 JSDoc 注释、空白分隔行和尾随逗号。

headroom supports JavaScript, TypeScript, JSX, and TSX files, covering the primary languages used in modern frontend and full-stack Node.js development.headroom 支持 JavaScript、TypeScript、JSX 和 TSX 文件，涵盖了现代前端和全栈 Node.js 开发中使用的主要语言。

Architecture Overview架构概述

headroom follows a CLI-first design with full stdin/stdout piping support, making it composable with other command-line tools. headroom counts tokens with cl100k_base encoding via tiktoken, so reported savings closely approximate GPT-4 and GPT-4o billing. Variance between headroom's reported count and actual billed tokens is typically under 2%; run tiktoken independently on a compressed file to verify against your own billing. Gemini and Claude use different tokenizers and will require separate validation.headroom 遵循 CLI 优先的设计，完全支持 stdin/stdout 管道传输，使其可以与其他命令行工具组合使用。headroom 通过 tiktoken 使用 cl100k_base 编码计算 Token，因此报告的节省量与 GPT-4 和 GPT-4o 的计费非常接近。headroom 报告的计数与实际计费 Token 之间的差异通常低于 2%；请在压缩文件上独立运行 tiktoken 以对照您的账单进行验证。Gemini 和 Claude 使用不同的分词器，需要单独验证。

The tool operates in two conceptual modes. Lower-loss, semantics-preserving compression (the "gentle" and "moderate" levels) removes only material that should not affect an LLM's understanding of code logic. Lossy compression (the "aggressive" level) applies identifier shortening and structural flattening that trades nuance for dramatically lower token counts in large-context summarization tasks.该工具在两种概念模式下运行。低损耗、保留语义的压缩（“轻度”和“中度”级别）仅移除不应影响 LLM 对代码逻辑理解的内容。有损压缩（“激进”级别）应用标识符缩短和结构扁平化，在大型上下文摘要任务中以牺牲细微差别为代价换取大幅降低的 Token 数量。

Installing and Setting Up headroom

Prerequisites先决条件

headroom requires Node.js 18 or later. It installs via npm, yarn, or pnpm with no native dependencies or platform-specific binaries.headroom 需要 Node.js 18 或更高版本。它通过 npm、yarn 或 pnpm 安装，没有原生依赖项或特定于平台的二进制文件。

Important: Before installing, run npm view headroom-cli to confirm the package description and homepage match the tool described in this article. The version used throughout this tutorial should be confirmed with headroom --version after installation.重要提示：安装前，请运行 npm view headroom-cli 以确认包描述和主页与本文描述的工具相符。安装后应使用 headroom --version 确认本教程中使用的版本。

npm install -g headroom-cli
headroom --version

For project-local installation:对于项目本地安装：

npm install --save-dev headroom-cli
npx headroom --version

Verifying Your Installation验证您的安装

Running headroom --help confirms the tool is accessible and displays all available commands and flags:运行 headroom --help 可确认工具是否可访问，并显示所有可用的命令和标志：

headroom --help

The help output lists the primary compress command along with flags for compression level selection, output mode, dry-run previews, and configuration file paths.帮助输出列出了主要的 compress 命令，以及用于选择压缩级别、输出模式、试运行预览和配置文件路径的标志。

Basic Usage: Compressing Your First File

Single-File Compression单文件压缩

The simplest invocation targets a single file:最简单的调用方式是针对单个文件：

headroom compress src/App.jsx

Terminal output reports the original token count, compressed token count, percentage reduction, and the compression level applied. For a typical React component file with JSDoc comments and standard formatting, expect output resembling:终端输出会报告原始 Token 计数、压缩后 Token 计数、缩减百分比以及应用的压缩级别。对于带有 JSDoc 注释和标准格式的典型 React 组件文件，预期输出如下：

src/App.jsx: 847 tokens → 189 tokens (78% reduction) [moderate]

Token counts use cl100k_base encoding. Verify by running tiktoken on both code blocks independently if exact counts matter for your cost analysis.Token 计数使用 cl100k_base 编码。如果精确计数对您的成本分析很重要，请在两个代码块上独立运行 tiktoken 进行验证。

Before and After: What Changes?压缩前后：发生了什么变化？

Consider a standard React component before compression:考虑压缩前的标准 React 组件：

/**
 * UserProfile component
 * Displays user information including avatar, name, and bio.
 * 
 * @param {Object} props - Component props
 * @param {string} props.name - The user's display name
 * @param {string} props.avatarUrl - URL for the user's avatar image
 * @param {string} props.bio - Short biography text
 * @returns {JSX.Element} Rendered user profile card
 */
import React from 'react';
import PropTypes from 'prop-types';

import { Card, CardHeader, CardBody } from '@/components/ui/Card';
import { Avatar } from '@/components/ui/Avatar';

const UserProfile = ({ name, avatarUrl, bio }) => {
  // Format the display name with proper capitalization
  const displayName = name.trim();

  // Determine if we should show the bio section
  const showBio = bio && bio.length > 0;

  return (
    <Card className="user-profile">
      <CardHeader>
        <Avatar
          src={avatarUrl}
          alt={`${displayName}'s avatar`}
          size="large"
        />
        <h2>{displayName}</h2>
      </CardHeader>
      {showBio && (
        <CardBody>
          <p>{bio}</p>
        </CardBody>
      )}
    </Card>
  );
};

UserProfile.propTypes = {
  name: PropTypes.string.isRequired,
  avatarUrl: PropTypes.string.isRequired,
  bio: PropTypes.string,
};

export default UserProfile;

After moderate compression:中度压缩后：

import React from 'react';
import PropTypes from 'prop-types';
import {Card,CardHeader,CardBody} from '@/components/ui/Card';
import {Avatar} from '@/components/ui/Avatar';
const UserProfile=({name,avatarUrl,bio})=>{const displayName=name.trim();const showBio=bio&&bio.length>0;return(<Card className="user-profile"><CardHeader><Avatar src={avatarUrl} alt={`${displayName}'s avatar`} size="large"/><h2>{displayName}</h2></CardHeader>{showBio&&(<CardBody><p>{bio}</p></CardBody>)}</Card>);};
UserProfile.propTypes={name:PropTypes.string.isRequired,avatarUrl:PropTypes.string.isRequired,bio:PropTypes.string};
export default UserProfile;

The JSDoc block is gone. Inline comments are stripped. Blank lines and decorative whitespace are collapsed. Import paths and component structure remain fully intact. An LLM reading the compressed version can still reason about props, conditional rendering logic, and component composition. The token count drops from 847 to 189, a 78% reduction.JSDoc 块消失了。内联注释被剥离。空行和装饰性空格被折叠。导入路径和组件结构保持完整。阅读压缩版本的 LLM 仍然可以推断 props、条件渲染逻辑和组件组合。Token 计数从 847 降至 189，缩减了 78%。

Directory and Glob Processing目录和 Glob 处理

For batch processing, headroom accepts glob patterns:对于批量处理，headroom 接受 glob 模式：

headroom compress "src/**/*.{js,jsx,ts,tsx}" --dry-run

The --dry-run flag previews savings without modifying any files:--dry-run 标志可在不修改任何文件的情况下预览节省情况：

Dry Run Summary:
──────────────────────────────────────────────
Files scanned:     47
Total tokens:      23,841
Compressed tokens: 5,960
Reduction:         75%
──────────────────────────────────────────────
No files were modified.

Output modes include in-place modification (destructive; ensure files are committed to version control first), stdout streaming, or writing to a specified output directory via --out-dir.输出模式包括就地修改（破坏性；请确保先将文件提交到版本控制）、stdout 流式传输，或通过 --out-dir 写入指定的输出目录。

Configuration and Compression Profiles

The .headroomrc Configuration File.headroomrc 配置文件

Project-level configuration lives in a .headroomrc.json file at the repository root. The following example shows the expected schema; consult the headroom documentation for the full configuration reference and validation:项目级配置位于仓库根目录的 .headroomrc.json 文件中。以下示例显示了预期的架构；请查阅 headroom 文档以获取完整的配置参考和验证：

{
  "level": "moderate",
  "include": ["src/**/*.{js,jsx,ts,tsx}"],
  "exclude": ["**/*.test.ts", "**/*.spec.tsx", "**/node_modules/**"],
  "output": "stdout",
  "languages": {
    "typescript": {
      "preserveTypes": true,
      "stripEnums": false
    },
    "javascript": {
      "preserveDirectives": true
    }
  },
  "preserveComments": ["headroom:keep", "TODO"],
  "tokenizer": "cl100k_base"
}

This configuration targets source files while excluding tests, preserves TypeScript type annotations, keeps comments marked with the headroom:keep pragma or containing TODO, and uses GPT-4-compatible token counting.此配置针对源文件，同时排除了测试文件，保留了 TypeScript 类型注解，保留了带有 headroom:keep pragma 或包含 TODO 的注释，并使用与 GPT-4 兼容的 Token 计数。

Compression Levels Explained压缩级别说明

headroom ships with three compression profiles, each representing a different trade-off between token reduction and semantic preservation.headroom 附带三种压缩配置文件，每种都在 Token 缩减和语义保留之间代表了不同的权衡。

When you need the LLM to see code that still looks like code, the gentle level is the right starting point. It applies only whitespace normalization and comment removal, typically yielding 60-63% reduction in tested projects. Debugging prompts and style-related queries work best here because the compressed output preserves indentation and structural spacing that moderate would strip.当您需要 LLM 看到看起来仍然像代码的代码时，“轻度”（gentle）级别是正确的起点。它仅应用空格规范化和注释移除，在测试项目中通常能实现 60-63% 的缩减。调试提示词和与样式相关的查询在此级别下效果最好，因为压缩后的输出保留了“中度”级别会剥离的缩进和结构间距。

The moderate level adds redundant syntax removal and import consolidation, reaching approximately 75-77% reduction. Gentle preserves blank lines between functions; moderate collapses them, removing visual separation but keeping every identifier and type annotation intact. Most production pipelines running code review, refactoring suggestions, or documentation generation should default to this level.“中度”（moderate）级别增加了冗余语法移除和导入合并，达到约 75-77% 的缩减。“轻度”保留了函数之间的空行；“中度”则将其折叠，移除了视觉分隔，但保留了每个标识符和类型注解。大多数运行代码审查、重构建议或文档生成的生产流水线应默认使用此级别。

Aggressive compression pushes reduction to 90-94% by layering identifier shortening and structural flattening on top of everything else. Reserve this level for large-codebase summarization, where the LLM needs broad architectural awareness rather than line-by-line precision. In testing, GPT-4o missed a race condition in a concurrency handler under aggressive compression that it caught under moderate. Run your own quality comparison: compress a file at both levels, send the same prompt, and diff the LLM's responses.“激进”（aggressive）压缩通过在其他所有操作之上叠加标识符缩短和结构扁平化，将缩减率推至 90-94%。请将此级别保留用于大型代码库摘要，在这种情况下，LLM 需要广泛的架构感知而非逐行精确度。在测试中，GPT-4o 在激进压缩下错过了一个并发处理程序中的竞态条件，而它在中度压缩下捕捉到了。请进行您自己的质量比较：在两个级别上压缩同一个文件，发送相同的提示词，并对比 LLM 的响应。

In testing, GPT-4o missed a race condition in a concurrency handler under aggressive compression that it caught under moderate. Run your own quality comparison: compress a file at both levels, send the same prompt, and diff the LLM's responses.在测试中，GPT-4o 在激进压缩下错过了一个并发处理程序中的竞态条件，而它在中度压缩下捕捉到了。请进行您自己的质量比较：在两个级别上压缩同一个文件，发送相同的提示词，并对比 LLM 的响应。

Custom Rules and Overrides自定义规则和覆盖

Per-language overrides in the configuration file allow fine-grained control. The preserveComments array supports pragma-style markers: any comment containing // headroom:keep survives compression at all levels. File exclusion patterns prevent headroom from touching test files, configuration files, or any paths that should remain uncompressed.配置文件中的按语言覆盖允许进行细粒度控制。preserveComments 数组支持 pragma 风格的标记：任何包含 // headroom:keep 的注释在所有级别下都能在压缩中幸存。文件排除模式可防止 headroom 触及测试文件、配置文件或任何应保持未压缩状态的路径。

Integrating headroom Into a Node.js/React Workflow

Prerequisites for Programmatic Usage编程使用的先决条件

Before running the programmatic examples below, ensure the following:在运行下面的编程示例之前，请确保满足以下条件：

• OPENAI_API_KEY is set in your environment (e.g., export OPENAI_API_KEY=your_key)OPENAI_API_KEY 已在您的环境中设置（例如，export OPENAI_API_KEY=your_key）
• headroom-cli and openai are installed in your project (npm install headroom-cli openai)headroom-cli 和 openai 已安装在您的项目中（npm install headroom-cli openai）

Programmatic API Usage编程 API 使用

Beyond CLI usage, headroom exposes a programmatic API for direct integration into Node.js scripts. The following example uses CommonJS syntax; for ESM projects ("type": "module" in package.json), use import { compress } from 'headroom-cli'; instead.除了 CLI 使用外，headroom 还公开了一个编程 API，用于直接集成到 Node.js 脚本中。以下示例使用 CommonJS 语法；对于 ESM 项目（package.json 中为 "type": "module"），请改用 import { compress } from 'headroom-cli';。

// CommonJS
const { compress } = require('headroom-cli');
// ESM alternative: import { compress } from 'headroom-cli';

const path = require('path');
const fs = require('fs/promises');
const { OpenAI } = require('openai');

// --- Configuration ---
const ALLOWED_ROOT = path.resolve('./src');
const client = new OpenAI(); // module-level singleton; reuses HTTP connection pool

// --- Safe async file read with path validation ---
async function readSourceFile(filePath) {
  const resolved = path.resolve(filePath);
  if (!resolved.startsWith(ALLOWED_ROOT + path.sep) && resolved !== ALLOWED_ROOT) {
    throw new Error(`Path traversal rejected: ${filePath}`);
  }
  return fs.readFile(resolved, 'utf-8');
}

// --- Guarded LLM call with timeout and response validation ---
async function callLLMReview(compressed, { model = 'gpt-4o', timeoutMs = 30_000 } = {}) {
  if (!process.env.OPENAI_API_KEY) {
    throw new Error('OPENAI_API_KEY environment variable is not set');
  }

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);

  let response;
  try {
    response = await client.chat.completions.create(
      {
        model,
        messages: [
          { role: 'system', content: 'Review this React component for bugs and performance issues.' },
          { role: 'user', content: compressed },
        ],
      },
      { signal: controller.signal }
    );
  } finally {
    clearTimeout(timer);
  }

  if (!response.choices?.length) {
    throw new Error('OpenAI returned no choices — possible content filter or quota error');
  }

  const content = response.choices[0].message?.content;
  if (content == null) {
    throw new Error('OpenAI message content is null — check for tool-call response type');
  }

  return content;
}

// --- Main review function ---
async function reviewComponent(filePath, options = {}) {
  const source = await readSourceFile(filePath);

  const result = await compress(source, {
    level: 'moderate',
    language: 'jsx',
  });

  // Guard against unexpected API shape
  const { compressed, originalTokens, compressedTokens } = result ?? {};
  if (!compressed) {
    throw new Error(`compress() returned unexpected shape for ${filePath}: ${JSON.stringify(result)}`);
  }

  console.log(`Compressed ${filePath}: ${originalTokens} → ${compressedTokens} tokens`);

  return callLLMReview(compressed, options);
}

reviewComponent('src/components/UserProfile.jsx')
  .then(console.log)
  .catch((err) => {
    console.error(err.message);
    process.exit(1);
  });

Note: The programmatic API shape (compress function, its arguments, and return object) should be verified against the headroom documentation for the version you have installed. Run node -e "const h=require('headroom-cli');console.log(Object.keys(h))" to confirm available exports.注意：编程 API 的形式（compress 函数、其参数和返回对象）应根据您安装的版本对照 headroom 文档进行验证。运行 node -e "const h=require('headroom-cli');console.log(Object.keys(h))" 以确认可用的导出。

This script reads a React component, validates the file path against a project root to prevent path traversal, compresses it via headroom's programmatic API, and sends the compressed output to GPT-4o for code review with a timeout and response validation. The token savings translate directly to lower API costs on every invocation. Errors propagate with a non-zero exit code for CI compatibility.此脚本读取一个 React 组件，根据项目根目录验证文件路径以防止路径遍历，通过 headroom 的编程 API 对其进行压缩，并将压缩后的输出发送给 GPT-4o 进行代码审查，并带有超时和响应验证。Token 的节省直接转化为每次调用时更低的 API 成本。错误会以非零退出代码传播，以实现 CI 兼容性。

npm Scripts Integrationnpm 脚本集成

Adding headroom to package.json scripts integrates compression into existing CI and pre-commit workflows:将 headroom 添加到 package.json 脚本中，可将压缩集成到现有的 CI 和预提交工作流中：

{
  "scripts": {
    "llm:compress": "headroom compress \"src/**/*.{ts,tsx}\" --dry-run",
    "llm:review": "set -euo pipefail; headroom compress \"src/**/*.{ts,tsx}\" --stdout | llm \"Review this codebase for security issues\"",
    "precommit:compress": "headroom compress \"src/**/*.{ts,tsx}\" --level moderate --out-dir .llm-context/"
  }
}

Windows note: Glob patterns in npm scripts use escaped double quotes as shown above for cross-platform compatibility. If you encounter glob resolution failures on Windows CMD or PowerShell, consider using a cross-platform glob tool or running via Git Bash.Windows 注意：npm 脚本中的 Glob 模式使用如上所示的转义双引号以实现跨平台兼容性。如果您在 Windows CMD 或 PowerShell 上遇到 glob 解析失败，请考虑使用跨平台 glob 工具或通过 Git Bash 运行。

Shell note: The set -euo pipefail prefix in llm:review ensures the pipeline fails if headroom exits with a non-zero code, preventing llm from running against empty or partial input. This requires a POSIX-compatible shell (bash, zsh). For cross-platform use, replace with a Node.js wrapper script that checks exit codes explicitly.Shell 注意：llm:review 中的 set -euo pipefail 前缀确保如果 headroom 以非零代码退出，流水线会失败，从而防止 llm 在空输入或部分输入上运行。这需要 POSIX 兼容的 shell（bash, zsh）。对于跨平台使用，请替换为显式检查退出代码的 Node.js 包装脚本。

The precommit:compress script generates a compressed snapshot of the codebase into a .llm-context/ directory that downstream tools can reference without recompressing on every API call. Add .llm-context/ to .gitignore to avoid committing compressed snapshots.precommit:compress 脚本将代码库的压缩快照生成到 .llm-context/ 目录中，下游工具可以在不每次 API 调用都重新压缩的情况下引用该快照。将 .llm-context/ 添加到 .gitignore 以避免提交压缩后的快照。

Piping to LLM CLIs and Tools管道传输至 LLM CLI 和工具

headroom's stdin/stdout support enables direct piping to LLM command-line tools:headroom 的 stdin/stdout 支持实现了到 LLM 命令行工具的直接管道传输：

headroom compress src/ --stdout | llm "Review this codebase for potential memory leaks"

This pattern works with stdin-consuming CLI tools such as aider and Simon Willison's llm CLI (pip install llm). For continue.dev and Cursor, use --out-dir to produce file-based context, as these tools consume context through their IDE extensions rather than stdin pipes.此模式适用于消耗 stdin 的 CLI 工具，例如 aider 和 Simon Willison 的 llm CLI (pip install llm)。对于 continue.dev 和 Cursor，请使用 --out-dir 生成基于文件的上下文，因为这些工具通过其 IDE 扩展而非 stdin 管道消耗上下文。

Benchmarks: Real-World Token Savings

Test Methodology测试方法

I benchmarked three JavaScript/TypeScript projects: a Next.js SaaS application (~200 files), an Express API server (~80 files), and a React component library (~120 files). These projects are representative but not named or publicly linked; readers should benchmark their own codebases for applicable results. I measured token counts using tiktoken with the cl100k_base encoding, which is compatible with GPT-4 and GPT-4o billing. Token counts for Gemini and Claude models will differ due to their distinct tokenizers.我基准测试了三个 JavaScript/TypeScript 项目：一个 Next.js SaaS 应用（约 200 个文件）、一个 Express API 服务器（约 80 个文件）和一个 React 组件库（约 120 个文件）。这些项目具有代表性，但未命名或公开链接；读者应基准测试自己的代码库以获得适用的结果。我使用带有 cl100k_base 编码的 tiktoken 计算 Token 计数，该编码与 GPT-4 和 GPT-4o 计费兼容。Gemini 和 Claude 模型的 Token 计数会因其独特的分词器而有所不同。

Results Table结果表

Note: The "Cost Saved" column shows savings at the aggressive compression level only. Moderate-level savings are approximately 60% of these figures. GPT-4o pricing should be verified at platform.openai.com/pricing as rates may change.注意：“节省成本”列仅显示激进压缩级别下的节省情况。中度级别的节省约为这些数字的 60%。GPT-4o 价格应在 platform.openai.com/pricing 进行验证，因为费率可能会发生变化。

Aggressive mode approaches 94% reduction for comment-heavy codebases where JSDoc and inline documentation constitute a large share of total tokens. However, aggressive compression can degrade LLM output quality on tasks requiring fine-grained reasoning. In testing, GPT-4o failed to identify a race condition under aggressive compression that it caught under moderate. To validate for your own use cases, compress a representative file at each level, send identical prompts, and diff the responses.对于 JSDoc 和内联文档占总 Token 很大比例的注释密集型代码库，激进模式的缩减率接近 94%。然而，激进压缩可能会降低需要细粒度推理的任务的 LLM 输出质量。在测试中，GPT-4o 在激进压缩下未能识别出竞态条件，而它在中度压缩下捕捉到了。为了验证您的用例，请在每个级别上压缩一个代表性文件，发送相同的提示词，并对比响应。

Best Practices and Pitfalls

When NOT to Compress何时不应压缩

Token compression is counterproductive in several scenarios. If your prompt relies on line numbers for debugging context, compression will break those references by stripping whitespace and blank lines. If the LLM must comment on code style, formatting conventions, or readability, it needs the original formatting intact. Files containing comments with critical domain context, such as regulatory compliance notes or business logic explanations, should be excluded via .headroomrc.json patterns or the headroom:keep pragma.在几种情况下，Token 压缩会适得其反。如果您的提示词依赖行号进行调试上下文，压缩会通过剥离空格和空行破坏这些引用。如果 LLM 必须评论代码样式、格式约定或可读性，它需要原始格式保持完整。包含带有关键领域上下文（如监管合规说明或业务逻辑解释）注释的文件，应通过 .headroomrc.json 模式或 headroom:keep pragma 排除。

Balancing Compression vs. Comprehension平衡压缩与理解

Start with the gentle level and evaluate LLM output quality as a baseline. The moderate level works as the default for most production pipelines. Reserve aggressive compression for large-context summarization, where the LLM needs to ingest an entire codebase to answer architectural questions, maximizing savings where precision on individual lines matters least.从“轻度”级别开始，并将 LLM 输出质量评估作为基准。“中度”级别适用于大多数生产流水线。将激进压缩保留用于大型上下文摘要，在这种情况下，LLM 需要摄取整个代码库来回答架构问题，从而在对单行精确度要求最低的地方实现最大化节省。

Security Considerations安全考虑

headroom processes all files locally. No source code is transmitted to external servers during compression. Verify by auditing the source on the project's GitHub repository or monitoring network traffic during a compression run with a tool such as mitmproxy. For teams with strict compliance requirements, the open-source codebase can be audited directly.headroom 在本地处理所有文件。压缩过程中不会将源代码传输到外部服务器。您可以通过审计项目 GitHub 仓库上的源代码，或使用 mitmproxy 等工具在压缩运行期间监控网络流量来验证这一点。对于有严格合规要求的团队，可以直接审计开源代码库。

Implementation Checklist

1. ☐ Verify headroom-cli on npm matches this tool (npm view headroom-cli)☐ 验证 npm 上的 headroom-cli 与此工具相符 (npm view headroom-cli)
2. ☐ Install headroom-cli globally (npm install -g headroom-cli)☐ 全局安装 headroom-cli (npm install -g headroom-cli)
3. ☐ Run headroom --help to verify installation and confirm available flags☐ 运行 headroom --help 以验证安装并确认可用的标志
4. ☐ Test single-file compression with --dry-run (headroom compress src/App.jsx --dry-run)☐ 使用 --dry-run 测试单文件压缩 (headroom compress src/App.jsx --dry-run)
5. ☐ Create .headroomrc.json with project-specific settings☐ 创建带有项目特定设置的 .headroomrc.json
6. ☐ Choose compression level (gentle/moderate/aggressive) based on use case☐ 根据用例选择压缩级别 (轻度/中度/激进)
7. ☐ Add headroom to npm scripts for CI/pre-commit hooks☐ 将 headroom 添加到 npm 脚本以用于 CI/预提交钩子
8. ☐ Set OPENAI_API_KEY environment variable if using programmatic API integration☐ 如果使用编程 API 集成，请设置 OPENAI_API_KEY 环境变量
9. ☐ Verify compress() export shape matches expected return keys (node -e "const h=require('headroom-cli');console.log(Object.keys(h))")☐ 验证 compress() 导出形式是否与预期的返回键匹配 (node -e "const h=require('headroom-cli');console.log(Object.keys(h))")
10. ☐ Integrate programmatically into LLM API call pipeline☐ 以编程方式集成到 LLM API 调用流水线中
11. ☐ Benchmark token savings against your actual API costs☐ 对照您的实际 API 成本进行 Token 节省基准测试
12. ☐ Monitor LLM output quality at chosen compression level☐ 在选定的压缩级别监控 LLM 输出质量
13. ☐ Set up a Datadog or Grafana dashboard tracking token spend before and after compression☐ 设置 Datadog 或 Grafana 仪表板，跟踪压缩前后的 Token 支出

Stop Paying for Tokens That Don't Matter

headroom delivers immediate, measurable cost reduction with minimal setup. In tested JavaScript and TypeScript projects, token reductions ranged from 60-94% depending on compression level, scaling from small component libraries to large SaaS codebases. Install headroom, run the dry-run benchmark on an existing project, and measure the actual savings against current API spend. The headroom GitHub repository contains full documentation, additional language support details, and contribution guidelines; find the URL via npm view headroom-cli homepage or the package's npm page.headroom 以最少的设置提供了即时、可衡量的成本降低。在测试的 JavaScript 和 TypeScript 项目中，Token 缩减范围为 60-94%，具体取决于压缩级别，从小型组件库扩展到大型 SaaS 代码库。安装 headroom，在现有项目上运行试运行基准测试，并对照当前的 API 支出衡量实际节省。headroom GitHub 仓库包含完整的文档、额外的语言支持详情和贡献指南；通过 npm view headroom-cli 主页或该包的 npm 页面查找 URL。

The tokens that don't contribute to LLM reasoning shouldn't contribute to the bill either.那些对 LLM 推理没有贡献的 Token，也不应该出现在账单上。