What's TZRO v2.1 STABLE

An ultra-lightweight, compiled native Go token shield and context optimization engine (<50 MB RAM, zero ML dependencies). It eliminates cloud API rate limits, locks KV-cache prompt prefixes (benchmarked at 70–99% cache read hit rates across 8 models), and provides sub-millisecond local codebase discovery.

The 12.5x Cache Miss Penalty & Context Explosion

Autonomous AI coding agents (Claude Code, Cursor, Antigravity, Aider, Cline) consume massive volumes of tokens during multi-turn developer interactions. In standard workflows:

• Transient Tool Bloat: Directory listings, raw source files dumped for inspection, verbose build logs, repetitive stack traces, and JSON API payloads account for 60% to 90% of all tokens consumed.
• Context Rot & Degradation: As contexts exceed 100k+ tokens, model reasoning degrades (~2% instruction-following loss per 100k tokens), leading to hallucinated APIs and lost system constraints.
• The 12.5x KV-Cache Penalty: Major providers (Anthropic, OpenAI) offer a 90% discount on cached prompt prefixes (\(P_{\\text{read}} = 0.10 \\times P_{\\text{base}}\)), but penalize cache misses by charging a 25% surcharge for cache writes (\(P_{\\text{write}} = 1.25 \\times P_{\\text{base}}\)). A single unaligned byte or reordered tool schema invalidates the cache, making subsequent turns 12.5× more expensive ($1.25 vs $0.10).
• Heavy ML Sidecar Bloat: Traditional context compression tools (e.g. Headroom) rely on Python runtimes and PyTorch models consuming 4.8 GB+ RAM with 60-second cold starts, rendering them unusable on standard developer laptops and CI runners.

Two-Plane Native Architecture

TZRO v2 operates across two synchronized planes that sit between your coding agent and upstream cloud providers:

┌─────────────────────────────────────────────────────────────┐
│  Developer / Agent (Cursor, Claude Code, Antigravity, CLI)  │
└──────────────────────────────┬──────────────────────────────┘
                               │ (Transparent Loopback Proxy / CLI)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 TZRO v2 LOCAL TOKEN SHIELD                  │
│                                                             │
│  1. KV-Cache Prefix Lock Guard (70-99% Cache Read Hit Rate)  │
│  2. Tree-Sitter AST Skeletonizer (70-90% Token Reduction)   │
│  3. Sub-Millisecond Local Discovery (`tzro probe`)          │
│  4. Local SQLite FTS5 Content-Hash Store (`tzro expand`)    │
│  5. Smart JSON Crusher & Stack Trace Elider                 │
│  6. Zero-Cloud DLP / Secret Masking                         │
│  7. Tabular Data Engine (`tzro ingest` / `tzro query`)      │
└──────────────────────────────┬──────────────────────────────┘
                               │ (Dense, High-Signal, Cache-Locked Payload)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│           Cloud LLM Provider (Anthropic / OpenAI)           │
│           ~80% Token Reduction / Zero Rate Limits           │
└─────────────────────────────────────────────────────────────┘

Performance & Footprint Comparison

Unlike Python-based compression proxies that consume gigabytes of VRAM and minutes to start, TZRO v2 is a single static Go binary with zero external runtime dependencies:

Quickstart & Agent Integration

TZRO connects seamlessly into your existing developer environment without changing your habits.

curl -fsSL https://get.tzro.ai | sh

CGO_ENABLED=1 go install ./cmd/tzro

# Start proxy daemon on port 7878:
tzro start --port 7878

# Inspect live status, shielded tokens, and memory footprint:
tzro status

export ANTHROPIC_BASE_URL=http://localhost:7878

export OPENAI_BASE_URL=http://localhost:7878/v1

{
  "tzro-token-shield": {
    "enabled": true,
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [{ "type": "command", "command": "tzro hook compact" }]
      }
    ]
  }
}

Core Token Shield Subsystems

1. KV-Cache Prefix Lock Guard

Modern frontier LLMs (Claude 3.5/3.7, GPT-4o, DeepSeek-V3) support prompt caching. However, cache hit rates are fragile: even a 1-byte difference in timestamp formatting, an reordered tool schema, or reordered system prompt invalidates the entire cache prefix, resulting in a 12.5x price increase for the turn.

The KV-Cache Prefix Lock Guard intercepts outgoing request payloads and enforces byte-for-byte prefix reproducibility:

• Top-pins static system instructions, repository context (AGENTS.md), and tool declarations in deterministic byte order at the head of the payload.
• Isolates dynamic turn variables (timestamps, ephemeral session tokens) to trailing user messages.
• Benchmarked at 70%–85% cache hit rates in real agent workflows and up to 99% under controlled multi-turn evaluation across 8 models via OpenRouter.

2. Tree-Sitter AST Skeletonizer

When an agent reads a 2,000-line source file just to understand an interface or signature, sending the full file burns cloud tokens needlessly. TZRO's native C Tree-sitter parsers support 10 languages: Go, TypeScript, JavaScript, Python, Rust, Java, C/C++, Ruby, PHP, and C#.

The skeletonizer parses the AST, preserves package headers, imports, structs, interfaces, exported method signatures, and docstrings, while replacing function bodies with cryptographic hashes:

package auth

// TokenClaims represents the JWT payload metadata.
type TokenClaims struct {
    UserID    string   `json:"sub"`
    Roles     []string `json:"roles"`
    ExpiresAt int64    `json:"exp"`
}

// ValidateToken verifies signature and expiry against current time.
func ValidateToken(raw string) (*TokenClaims, error) {
    // [body elided: #8f2a1c]
}

The full body is indexed in local SQLite FTS5. The agent can expand only the specific function body it needs to edit using tzro expand #8f2a1c, achieving a 70%–90% token reduction on file inspections.

3. Smart JSON Crusher & Stack Trace Elider

Smart JSON Crusher: Detects repetitive JSON objects (e.g. database query results or API lists) and flattens them into compact Markdown tables. Repeated keys that waste thousands of tokens are collapsed into table headers, slashing token consumption by up to 80%.

Stack Trace Elider: Strips internal framework and standard library stack frames from test failures and panics, preserving the root-cause assertion and user-code lines without context waste.

4. Zero-Cloud Data Loss Prevention (DLP)

Configured in .tzro/privacy.json, TZRO's on-device DLP policy engine protects sensitive credentials:

Local Codebase Discovery & Retrieval

Sub-Millisecond Symbol Discovery (tzro probe)

Standard agents burn 5–10 turns and 250k+ cloud tokens scanning directories, reading files, and running greps to locate symbols. tzro probe replaces this with a single on-device call using embedded ripgrep and Tree-sitter AST queries in <5ms:

# Locate symbols, methods, and line ranges in <5ms:
tzro probe "jwt token validation"

Output returns exact line coordinates, symbol kinds, and body hashes:

Found 1 match for "jwt token validation":
- ValidateToken (function in auth/jwt.go:45-78) [Hash: #8f2a1c]

Body Expansion & Line Slicing (tzro expand)

Retrieve only the specific function body or stored artifact lines needed:

# Expand an elided function body by hash:
tzro expand 8f2a1c

# Slice specific line ranges from stored artifacts:
tzro expand art_9503e3ba620ad4bf --lines 10-40

Unified Local Evidence Search (tzro search)

Search across code, architectural decision records (ADRs), product specs, design documents, logs, and stored artifacts in a single query with content-hash deduplication:

tzro search "rate limit token bucket"

Tabular Data & SQL Engine (tzro ingest / tzro query)

Dumping full CSV, TSV, or JSON data files into prompt context is an anti-pattern that burns tens of thousands of tokens. Import data into embedded SQLite and run targeted SQL queries:

# Import CSV file or pipe stdin:
tzro ingest metrics.csv --name daily_metrics
cat report.json | tzro ingest -

# Query data with read-only SQL:
tzro query daily_metrics "SELECT endpoint, COUNT(*), AVG(CAST(latency_ms AS REAL)) FROM daily_metrics GROUP BY endpoint"

Delivers 97%+ token reduction on tabular workloads by returning only computed query results.

Task Context & Change Impact

Task Context Assembly (tzro context)

Assembles a ranked, token-budgeted context pack containing relevant symbol definitions, AST call graphs, TypeScript path alias resolutions (tsconfig.json), and nearby test coverage in a single turn:

tzro context "implement rate limiting middleware" --budget 2000

Pre-Edit Change Impact Graph (tzro impact)

Before modifying shared utilities, interfaces, or types, analyze the structural blast radius:

# Analyze blast radius of specific files before editing:
tzro impact pkg/kvlock/kvlock.go

# Or analyze uncommitted git changes automatically:
tzro impact

Outputs direct callers, downstream dependent modules, and existing test suites that cover the affected call paths.

Agent Session Continuity (tzro session)

Eliminates transcript re-reading when handing off tasks across agents or resuming work after interruptions. Saves state to a portable, git-aware Schema v2 manifest:

# Save current agent task state:
tzro session save --objective "refactor proxy" --constraints "zero external deps"

# Check session freshness against git tree:
tzro session status

# Load session manifest in a new turn:
tzro session load .tzro/session.json

Evidence Contract Compactor (tzro compact --run)

Execute test and build commands through the compactor to enforce strict evidence contracts:

# Direct command execution with verified exit-code capture and 10-line inline cap:
tzro compact --run "go test -v ./..."

# Or pipe stdout directly:
go test ./... 2>&1 | tzro compact

Guarantees exit-code confidence, surfaces root-cause diagnostics within a 10-line inline cap, and stores complete failure logs in SQLite with an expansion hash.

Diagnostics & CLI Reference

System Doctor (tzro doctor)

Runs synthetic health checks across the proxy, upstream provider latency, SQLite FTS5 capability, and agent lifecycle hooks:

tzro doctor

Signal Density Benchmarking (tzro bench signal-density)

Empirically benchmark task signal density per token across optimization strategies with hard spend limit circuit breakers:

tzro bench signal-density --max-cost 1.50

CLI Command Matrix