Pi Quiet Tools

A Pi extension that automatically compacts large tool outputs before they enter the model's context window, saving tokens without losing information.

The Problem

When Pi's agent calls tools like bash, read, or subagents, the full output becomes part of the conversation context. A single find command or verbose log dump can add thousands of tokens that the model pays for on every subsequent turn — even if only a few lines matter.

Hiding output in the UI doesn't help: the model still sees (and pays for) the full text in its context window. Quiet Tools intercepts tool results before they reach the model, replacing large outputs with a head/tail preview and saving the full text to a local artifact file the agent can read on demand.

Install

From npm:

pi install npm:pi-quiet-tools

For local development:

pi install /path/to/pi-quiet-tools

Or load for a single session:

pi -e /path/to/pi-quiet-tools

How It Works

1. Every tool result passes through the extension's tool_result handler.
2. If the output is below the threshold, it passes through unchanged.
3. If it exceeds the threshold (default: 12,000 chars or 240 lines):
   • The full text is saved to a timestamped artifact file.
   • The model receives a compact preview: the first 100 lines, the last 60 lines, and an omission marker in between.
   • The preview includes the artifact path so the agent can read the full output if it needs a detail from the omitted middle.
4. Error outputs get a larger preview budget (160 head + 120 tail lines) since diagnostic context matters more.

The extension also caps read tool calls to 120 lines by default (when no explicit limit is set), preventing accidental full-file reads from flooding context.

Commands

Control the extension during a Pi session:

| Command | Effect | |---------|--------| | /quiet-tools status | Show current state: enabled, thresholds, artifact directory | | /quiet-tools on | Enable compaction | | /quiet-tools off | Disable compaction | | /quiet-tools bypass-next | Skip compaction for the next tool result only | | /quiet-tools last [n] | List the last n artifact paths (default: 5) |

Prompt Template

The included /quiet prompt template encourages focused, low-noise workflows:

/quiet <task>

This guides the agent to skip narration, use targeted reads, and give concise final answers. The prompt is guidance only — the extension enforces compaction regardless of prompt.

Configuration

All settings are controlled via environment variables. Defaults work well for most projects.

Thresholds

| Variable | Default | Description | |----------|---------|-------------| | QUIET_TOOLS_ENABLED | true | Master switch | | QUIET_TOOLS_MAX_CHARS | 12000 | Compact if output exceeds this character count | | QUIET_TOOLS_MAX_LINES | 240 | Compact if output exceeds this line count |

Preview Size

| Variable | Default | Description | |----------|---------|-------------| | QUIET_TOOLS_HEAD_LINES | 100 | Lines to keep from the start of output | | QUIET_TOOLS_TAIL_LINES | 60 | Lines to keep from the end of output | | QUIET_TOOLS_ERROR_HEAD_LINES | 160 | Head lines for error output | | QUIET_TOOLS_ERROR_TAIL_LINES | 120 | Tail lines for error output |

Per-Tool Toggles

| Variable | Default | Description | |----------|---------|-------------| | QUIET_TOOLS_COMPACT_READ | true | Compact read tool results | | QUIET_TOOLS_COMPACT_BASH | true | Compact bash tool results | | QUIET_TOOLS_COMPACT_SUBAGENT | true | Compact subagent results | | QUIET_TOOLS_READ_DEFAULT_LIMIT | 120 | Default line limit injected into read calls that don't specify one (0 to disable) |

Artifact Storage

| Variable | Default | Description | |----------|---------|-------------| | QUIET_TOOLS_ARTIFACT_DIR | .pi/quiet-tools/outputs | Directory for full output files | | QUIET_TOOLS_INDEX | .pi/quiet-tools/index.jsonl | JSONL index of all saved artifacts |

Artifacts

Full outputs are saved as timestamped text files under .pi/quiet-tools/outputs/. A JSONL index at .pi/quiet-tools/index.jsonl tracks every artifact with metadata (timestamp, tool name, path, line/char counts).

The agent can recover any compacted detail by reading the artifact path included in every compacted preview.

Security note: Artifacts contain the raw tool output. If a command prints secrets or credentials, those will be in the artifact files. Add the artifact directory to .gitignore:

.pi/quiet-tools/

Tuning Guide

If the agent misses details from compacted output:

• Raise QUIET_TOOLS_HEAD_LINES and QUIET_TOOLS_TAIL_LINES
• Raise QUIET_TOOLS_MAX_CHARS or QUIET_TOOLS_MAX_LINES
• Disable compaction for specific tools (e.g., QUIET_TOOLS_COMPACT_READ=false)
• Use /quiet-tools bypass-next before a specific command

If output is still too noisy:

• Lower the thresholds
• Lower QUIET_TOOLS_READ_DEFAULT_LIMIT
• Enable subagent compaction if not already on

Design Notes

• Deterministic compaction. No AI summarization — the preview is always the literal first and last lines of output. This makes behavior predictable and debuggable.
• Fail-open. If artifact writing or compaction throws an error, the original output passes through unchanged. The extension notifies once and stays out of the way.
• Non-text content preserved. Image blocks, tool-use blocks, and other non-text content in tool results are never modified.
• Additive metadata. The extension adds a details.quietTools object to tool results without replacing existing detail fields.

License

MIT — see LICENSE.