sqz Documentation

sqz prioritizes faithfulness over raw compression. It uses a two-pass verifier that checks 6 invariants (such as preserving error lines, file paths, and diff hunk headers). If confidence is low, it triggers a safe mode to ensure reliability.

What sqz compresses well:

• Repeated Log Output: Uses condense to collapse identical lines (e.g., ~53% reduction).
• JSON API Responses: Uses strip_nulls, flatten, and TOON encoding (e.g., ~7.8% reduction).
• Git Diffs: Uses git_diff_fold to keep context lines around changes (e.g., ~2% reduction).
• Command Outputs: Specialized formatters for commands like npm install, cargo test, cargo build, grep, terraform plan, cargo clippy, and git status provide high savings (up to 99%).

What sqz does NOT compress (Safe Mode):

To prevent data corruption, the following are typically preserved verbatim:

• Stack traces
• Database migrations
• Short messages (< 100 chars)
• Binary/base64 content (replaced with [blob:Nb] markers)

sqz is a pre-injection compression layer designed for LLM coding agents. Unlike prompt compression (which modifies instructions) or context pruning (which removes old history), sqz operates at the tool execution boundary. It intercepts tool outputs (shell commands, file reads, logs, etc.) and compresses them before they are injected into the LLM's context window.

Core Mechanisms

• Domain-Specific Structural Formatters: Recognizes 90+ CLI patterns (e.g., stripping passing tests from cargo test, compacting git status, or null-stripping JSON) to reduce bloat while preserving semantic meaning.
• Content-Addressed Deduplication: Uses a persistent SHA-256 cache to identify repeated content (like reading the same file multiple times). Repeated content is replaced with a 13-token reference marker: §ref:HASH§. This can achieve up to 92% savings on repeated reads.
• Adaptive Pressure-Aware Compression: Dynamically adjusts compression intensity based on how much of the session's token budget has been consumed:
  • Low pressure (<50% budget): Preserves maximum detail.
  • High pressure (>80%): Uses aggressive compression.
  • Critical (>90%): Maximum compression + proactive deduplication.
• Entropy-Based Safety Routing: Uses Shannon entropy and pattern detection to ensure critical data is not corrupted. Content is classified into risk tiers:
  • Safe mode (0% compression): Stack traces, private keys, credentials, and database migrations.
  • Default mode (20-40% compression): Normal code, git output, build logs.
  • Aggressive mode (40-60% compression): Repetitive logs, verbose JSON, boilerplate.
• N-gram Abbreviation: Replaces frequently co-occurring multi-token phrases with shorter representations.

Unlike tools that compress individual command outputs in isolation, sqz compresses entire sessions. It maintains a compaction-aware dedup cache across the whole session, allowing it to recognize repeated content, file dependencies, and context from previous turns. This session awareness enables several advanced features that significantly reduce token consumption in iterative AI coding workflows.

Key mechanisms include:

• Session-level Dedup: Repeated file reads or identical API responses return a tiny (e.g., 13-token) reference instead of re-sending the content.
• Delta Encoding: When a file is modified slightly, sqz sends only the diff (using SimHash for detection and LCS for computation) rather than the whole file.
• Predictive Pre-caching: sqz parses imports (e.g., use statements in Rust) when a file is read and pre-caches its dependencies to ensure instant dedup hits when those dependencies are subsequently accessed.
• Cross-command Context Refs: If an error message references a file already in the dedup cache, sqz annotates it with [in context] to prevent unnecessary re-reads.
• Session Continuity: Using sqz resume provides a ~200-token summary of the previous session's state, allowing an LLM to regain context without re-processing all previous history.

sqz intercepts command output before it reaches your LLM using a PreToolUse hook (or similar mechanism depending on the tool). The output is compressed transparently, so the AI tool receives a smaller context without needing manual configuration.

Compression Types

• Per-command compression: Reduces size of single outputs (e.g., logs, JSON, Git diffs).
• Session-level dedup: When the same file is read multiple times in a session, sqz sends the full content once and uses a 13-token reference for all subsequent reads.

What is compressed

• Shell output: Formatter-aware compression for git, cargo, npm/pnpm/yarn, pytest, ruff, go test, docker, kubectl, aws, terraform, gradle, gh, grep/rg, tree, curl, etc.
• JSON: Strips nulls, uses compact encoding, and TOON format.
• Logs: Collapses repeated lines.
• Test output: Uses state-machine parsers for Rust, Go, Python, JS, and JVM to show only failures.

What is NOT compressed

• Stack traces, error messages, and secrets: These are routed to safe mode, which results in 0% compression to ensure accuracy and security.
• Prompts and AI responses: These are managed by the AI tool itself, not sqz.

After installation, you must initialize sqz to set up hooks for your AI tools.

Global vs Project Scope

• Global: sqz init --global writes to ~/.claude/settings.json. This applies the sqz hook to every Claude Code session on your machine. It merges entries into your existing config without overwriting permissions, env, or statusLine.
• Project: sqz init applies hooks only to the current project (writes to .claude/settings.local.json).

Limiting Configuration

You can use --only or --skip to control which tool configurations are written. You cannot use both flags at once.

Accepted tool names: claude, cursor, windsurf, cline, gemini, kiro, opencode, codex.

Aliases: claude-code, gemini-cli, roo, kiro-cli.

# Global installation (recommended for Claude Code)
sqz init --global

# Project-specific installation
sqz init

# Limit to specific tools
sqz init --only opencode,codex

# Skip specific tools
sqz init --skip cursor,windsurf