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

> Offset headroom.js easily using the headroomRead helper with the offset parameter or CLI flags. Read specific file slices on your page efficiently.

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

---

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

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

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