How to Set the Offset for headroom.js: Complete Guide to Partial File Reading

Use the offset parameter in a Read tool call via headroomRead({file_path, offset, limit}) or the --offset CLI flag to read specific sections of large files instead of processing the entire content.

The headroom.js JavaScript SDK (package headroom-ai) enables efficient processing of large source files by allowing you to read only specific portions rather than complete documents. When integrating with the chopratejas/headroom proxy, setting an offset tells the Headroom Read tool exactly where to begin reading, which significantly reduces token usage when compressing large codebases.

What the offset Parameter Does in headroom.js

The offset parameter (used with an optional limit) instructs the Headroom Read tool to start reading a file at a specific line or byte number and optionally stop after a certain number of lines. This functionality allows you to compress only a slice of a large source file instead of the entire document. According to the source code in headroom/transforms/read_lifecycle.py, the fields offset and limit are extracted from every Read tool call and stored in the tool-metadata map.

Setting the Offset in JavaScript (headroom-ai SDK)

When using the JavaScript SDK, you construct a Read tool call using the headroomRead() helper function and pass it to the compress() method. The SDK forwards the request to the proxy via the HTTP POST /v1/compress endpoint.

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

// Build a Read tool call with offset and limit
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('Excerpt returned by the proxy:', result.messages[0].content);

Key Implementation Details

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

Setting the Offset via the Command Line

For command-line usage, the headroom executable exposes the same functionality through flags. The CLI internally constructs the identical 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 proxy to return 30 lines starting from line 120 (zero-based) of the specified file.

How the Offset is Processed Internally

According to the chopratejas/headroom source code, the offset handling is implemented in the Read lifecycle transformer at headroom/transforms/read_lifecycle.py. This component extracts the offset and limit fields from incoming Read tool calls and stores them in the tool-metadata map, which the proxy uses to determine which portion of the file to read and compress.

Summary

• Use headroomRead({file_path, offset, limit}) in the JavaScript SDK to specify where to begin reading a file.
• The offset parameter is zero-based, meaning the first line or byte is indexed as 0.
• Omitting the limit parameter returns content from the offset to the end of the file.
• In the CLI, use the --offset and --limit flags with the headroom read command.
• The underlying logic resides in headroom/transforms/read_lifecycle.py within the Read lifecycle transformer.

Frequently Asked Questions

Is the offset zero-based or one-based in headroom.js?

The offset is zero-based. Whether referring to line numbers or byte positions (depending on your proxy configuration), the first position is indexed as 0, not 1. Therefore, setting offset: 120 starts reading from the 121st line or byte.

What happens if I omit the limit parameter when setting an offset?

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

Can I use offset with byte positions instead of line numbers?

Yes, the offset parameter supports both line and byte positions, depending on your proxy configuration. The headroom/transforms/read_lifecycle.py implementation handles both modes, though the specific interpretation depends on how the Read tool is configured in your Headroom deployment.

Where is the offset validation logic implemented in the source code?

The offset extraction and validation logic is implemented in the Read lifecycle transformer at headroom/transforms/read_lifecycle.py. This file processes every Read tool call, extracting the offset and limit fields and storing them in the tool-metadata map for the proxy to use when reading file contents.

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