pi-read

The Pi coding agent /read tool, but with lower (and configurable) default max values (e.g. 2000 lines -> 100 lines).

A plugin for Pi that overrides the built-in read tool with configurable truncation limits.

Features

• Configurable defaults: Set default max lines and bytes for file reads
• Configurable hard caps: Clamp agent-requested limitLines / limitBytes
• Global and project config: Different limits per project or global defaults
• Sensible defaults: 100 lines / 5KB (much smaller than built-in 2000 lines / 50KB)
• Delegates image reads to Pi core read tool (MIME sniffing + resize safeguards)

Installation

From GitHub (Recommended)

pi install git:github.com/arcanemachine/pi-read

To update to the latest version:

pi update git:github.com/arcanemachine/pi-read

From Local Clone

git clone https://github.com/arcanemachine/pi-read.git
cd pi-read
pi install /path/to/pi-read

No local npm install is required for normal usage.

Development

For local development and verification:

npm install
npm run typecheck
npm run test
npm run build

Configuration

Add a readTool key to your pi settings.json.

Configuration File Locations

Pi-read merges readTool settings from these locations (project overrides global):

1. .pi/settings.json (project-specific)
2. ~/.pi/agent/settings.json (global)

You can also edit settings via the /settings command in pi.

Example Configuration

Add to your .pi/settings.json or ~/.pi/agent/settings.json:

{
  "readTool": {
    "maxLines": 100,
    "maxBytes": 5120,
    "maxLimitLines": 2000,
    "maxLimitBytes": 51200
  }
}

Configuration Options

| Option | Type | Default | Description | | --------------- | ------ | ------- | -------------------------------------------------- | | maxLines | number | 100 | Default maximum lines when limitLines is omitted | | maxBytes | number | 5120 | Default maximum bytes when limitBytes is omitted | | maxLimitLines | number | 2000 | Hard cap for agent-requested limitLines | | maxLimitBytes | number | 51200 | Hard cap for agent-requested limitBytes (50KB) |

Project-Specific Example

Set conservative defaults globally, but allow more for specific projects:

~/.pi/agent/settings.json

{
  "readTool": {
    "maxLines": 50,
    "maxBytes": 512,
    "maxLimitLines": 500,
    "maxLimitBytes": 8192
  }
}

.pi/settings.json (in a documentation project):

{
  "readTool": {
    "maxLines": 500,
    "maxBytes": 51200,
    "maxLimitLines": 2000,
    "maxLimitBytes": 51200
  }
}

Usage

Once installed, the read tool automatically uses your configured limits. No changes needed to your workflow.

Tool Parameters

• offsetLines (1-indexed) and limitLines
• offsetBytes (0-indexed) and limitBytes
• If both offsets are provided, offsetBytes takes precedence.
• Byte limits are hard safety limits; line limits are secondary guardrails.
• Agent-requested limits are clamped by maxLimitLines and maxLimitBytes.

Example Session

You: read a large file

[read tool uses your configured defaults, e.g., 100 lines / 5KB]

[Showing lines 1-100 of 500. Use offsetLines=101 to continue or offsetBytes=4970 for byte-based paging.]

You: continue reading from offsetLines 101

Why?

The built-in read tool has generous defaults (2000 lines / 50KB) which can consume significant context window. This extension lets you:

• Keep more context available for the conversation
• Read files more deliberately in smaller chunks
• Set different limits per project (e.g., larger limits for documentation projects)

How It Works

This extension:

1. Registers a tool named read that overrides the built-in read tool
2. Loads configuration from pi's settings.json files
3. Applies your configured defaults (maxLines / maxBytes)
4. Clamps agent-requested limits with hard caps (maxLimitLines / maxLimitBytes)
5. Delegates image reads to the built-in Pi core read tool for MIME sniffing and image resize safeguards

The truncation logic uses the same truncateHead function as the built-in tool, ensuring consistent behavior.