How to Offset headroom.js on a Page: Reading File Slices with Offset and Limit

Use the headroomRead() helper with the offset parameter in your JavaScript SDK calls, or add --offset flags to CLI commands to read specific portions of large files.

The Headroom proxy by chopratejas/headroom provides intelligent file reading capabilities that help manage AI context windows efficiently. When you need to offset headroom.js to access specific file segments rather than entire documents, you can leverage the offset and limit parameters available in both the JavaScript SDK and command-line interface.

Understanding the Offset Parameter in headroom.js

The offset parameter tells the Headroom Read tool to start reading a file at a specific line or byte number, allowing you to compress only a targeted slice of a large source file instead of processing the entire document.

Where Offset Logic Is Implemented

According to the chopratejas/headroom source code, the offset handling resides in headroom/transforms/read_lifecycle.py. This file extracts the offset and limit fields from every Read tool call and stores them in the tool-metadata map, enabling the proxy to return precisely the file segment you requested.

How to Offset headroom.js Using the JavaScript SDK

When using the headroom-ai JavaScript SDK, you forward requests to the proxy via the HTTP POST /v1/compress endpoint. To implement an offset, construct a Read tool call using the headroomRead() helper function.

The headroomRead() function accepts an object with file_path, offset (zero-based), and an optional limit parameter:

import { compress, headroomRead } from 'headroom-ai';

// Build a Read tool call with offset to start at line 120
const readTool = headroomRead({
  file_path: '/absolute/path/to/large_file.py',
  offset: 120,   // Start at line 120 (zero-based)
  limit: 30,     // Read only 30 lines (optional)
});

// Pass the tool request to the proxy
const result = await compress(
  [{ role: 'assistant', tool_calls: [readTool] }],
  { model: 'gpt-4o' }
);

console.log('File excerpt:', result.messages[0].content);

Key points:

• The offset value is zero-based (the first line or byte is 0)
• If you omit limit, the proxy returns the file from offset to the end
• headroomRead() is a thin wrapper around the generic ToolCall format used by the proxy

How to Offset headroom.js via the Command Line

The headroom CLI exposes the same offset functionality through command flags. The CLI internally builds the same JSON tool call and sends it to the proxy.

headroom read /absolute/path/to/large_file.py \
  --offset 120 \
  --limit 30

This command instructs the Headroom proxy to return only lines 120 through 149 of the specified file, reducing token usage when you only need to examine a specific section of code.

Offset vs Limit: Controlling File Slices

When you offset headroom.js, you combine two distinct parameters to control file reading:

• Offset: The starting position (zero-based line or byte number) where reading begins
• Limit: The maximum number of lines or bytes to read from the starting position

Used together, these parameters create a sliding window that lets you process large files in manageable chunks without loading the entire document into your AI context.

Summary

• Offset definition: A zero-based parameter in headroom/transforms/read_lifecycle.py that specifies where to start reading a file
• JavaScript SDK: Use headroomRead({ file_path, offset, limit }) to create offset tool calls for the compress() function
• CLI usage: Append --offset and --limit flags to the headroom read command
• Default behavior: Omitting limit returns content from the offset position to the end of the file
• Source location: The offset extraction logic is implemented in the Read lifecycle transformer at headroom/transforms/read_lifecycle.py

Frequently Asked Questions

Is the offset parameter zero-based in headroom.js?

Yes, the offset parameter is zero-based, meaning the first line or byte of a file is position 0. To start reading from line 120, you would set offset: 119 in JavaScript or --offset 119 in the CLI.

What happens if I specify offset without limit in headroom.js?

If you provide an offset but omit the limit parameter, the Headroom proxy returns the file content from the specified starting position through the end of the file. This is useful when you need to read from a specific point to the conclusion without knowing the total file length.

Can I use offset with relative file paths?

While the examples show absolute paths (/absolute/path/to/file), the headroomRead() function and CLI accept relative paths depending on your execution context. The proxy resolves the path and applies the offset to the resolved file location.

Where is the offset logic processed in the Headroom proxy?

The offset extraction and processing occurs in headroom/transforms/read_lifecycle.py within the chopratejas/headroom repository. This Python module extracts the offset and limit fields from incoming Read tool calls and stores them in the tool-metadata map for the compression engine to use.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}