# Pi Quiet Tools

A [Pi](https://github.com/nichochar/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:

```bash
pi install npm:pi-quiet-tools
```

For local development:

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

Or load for a single session:

```bash
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:

```text
/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`:

```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](LICENSE).