Token saver: keep long command output out of your coding agent's context

## Token saver
For commands likely to print more than 40 lines (builds, tests, logs, long scripts, find or ls -R), run them through `ts-run '<command>'` and read only the summary. If you need detail, grep the full.log path it prints instead of printing the log.

# Token saver: keep long command output out of your coding agent's context

PaperChase bot template, version 1.0. Two small shell scripts plus one rule line for Claude Code, Codex, Cursor, Gemini CLI, Goose or any agent that runs shell commands. Runs on your own Mac or Linux machine. No accounts, no network calls, nothing installed outside one folder in your home directory.

## The problem

Coding agents read everything a command prints. A test run, a build log or a wide `grep` can dump thousands of lines into the conversation, and in a long session that text is re-read on every turn. You pay for it, the agent gets slower, and the one line that mattered (the error) is buried.

When we audited our own recent sessions across several agent CLIs, shell output and wide file searches were the two largest sources of tool output by count. Long sessions re-reading cached context were the largest cost overall.

## What it does

- **`ts-run '<command>'`** runs any command, saves the full output to a log file and prints a one-page summary: exit code, line and byte count, error and warning lines, the most repeated lines, the first 20 and last 20 lines. The exit code passes through unchanged, so scripts and agents still see failures.
- **`ts-find <query> [folder]`** searches a large folder and prints a grouped summary: match count, top folders, file types, the 20 most recently changed matches and the first hit lines from 10 files. Uses Spotlight on macOS and ripgrep or grep elsewhere.
- **One rule line** tells your agent to use them for noisy commands and wide searches, and to search the saved log instead of printing it again.

Example from our own test: `seq 1 3000` prints about 13,900 bytes. Through `ts-run` the agent reads a 496-byte summary.

## Contents

1. What it changes and what it never does
2. Install (5 minutes)
3. Source: ts-run
4. Source: ts-find
5. Add the rule to your agents
6. Verify
7. Other habits that cut more than this tool does
8. Uninstall