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

> Learn how to set the offset for headroom.js to read partial files. Use the offset parameter or CLI flag for efficient large file processing.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-17

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.

```typescript
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.

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.