Community

Token Reduction with Squeeze Tool

The squeeze tool reduces text size by retaining essential changes, failures, or decisions, significantly cutting token usage for coding agents.

AI-generated editorial illustration of the article topic; not a photograph, product screenshot or measured result.

Token Reduction with Squeeze

Token Reduction with Squeeze offers a practical solution for reducing the computational load on coding agents by minimizing the text they process. The tool, called squeeze, reads a tool's output on stdin and prints the smallest text that still carries every change, failure, or decision in it. For example, a plan JSON of 3,774 bytes was reduced to just 485 bytes by squeeze, significantly cutting the number of tokens required for processing. This reduction is particularly valuable for models with limited token budgets, as demonstrated by a diagnostics call that returned about 580,700 tokens and filled an agent's context window (anthropics/claude-code#12054). The output from squeeze is designed for human readability or for use by other programs, not for models constrained by token limits.

Usage and Integration with Tools

The squeeze tool integrates seamlessly with various command-line tools, particularly those that output structured data in formats like JSON. By piping tool output through squeeze, users can significantly reduce the volume of data processed by their coding agents, improving efficiency without losing essential information. For example, when using Terraform, commands such as terraform plan -json | squeeze compress the output while retaining critical details about resource changes. This approach is especially useful for agents that analyze or act on tool outputs, as it minimizes the computational load. The tool supports multiple formats and allows users to specify format-specific flags for further customization. Installation is straightforward via go install, and usage instructions are provided in project documentation like AGENTS.md or CLAUDE.md. This integration highlights how lightweight utilities can enhance the performance of larger systems without requiring changes to the underlying tools.

Output Format and Compression

The output format guarantees that all results are delivered as plain text, free from control characters or color codes, ensuring consistency across identical inputs and ending with a newline. This standardization simplifies parsing and integration with other tools. Additionally, names and addresses from the input are printed on a single line without control characters, preventing forged output lines. The tool supports various flags, such as --output for specifying text or JSON format, and --raw-dir for saving unmodified input with a SHA256 hash prefix. The --fail-on flag allows defining exit conditions based on input characteristics, with details available via squeeze <format> -h or the format's documentation. When using --output json, the output includes metadata like schema_version, input_bytes, and text_bytes, along with a compression ratio and conditions met.

Error Handling and Exit Codes

When working with coding agents, managing the output from tools is crucial for effective error handling. Exit codes provide a structured way to interpret the success or failure of a process. For example, an exit code of 0 indicates that output was written successfully, while a code of 1 signals a read, parse, or write error with empty stdout. Code 2 means the input does not match any known format, and code 3 occurs when the --fail-on flag is used, with stdout containing the full output and stderr listing the conditions that triggered the failure. Code 64 indicates invalid flags or arguments, including unknown --fail-on conditions. Without --fail-on, the input content does not influence the exit code. These exit codes help developers pinpoint issues quickly and efficiently.

Development and Testing

In the development and testing phase of the project, the team emphasizes automated checks and validation through a series of tools. These include gofmt, go vet, staticcheck, and exhaustive, which ensure code quality and consistency. Test coverage is enforced across packages, with a minimum threshold of 85 percent. Golden files are updated intentionally after expected output changes, and fuzz testing is applied to tfplan for 30 seconds. Benchmarks are run for every format, and conformance tests are executed against Terraform's command testdata at a pinned commit. The project requires Go 1.26 or later, and linters are integrated via the go tool, with dependencies pinned in go.mod. No additional installations are needed beyond Go and the just tool.