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.