ZeroCTX v0.3

A Rust-based agent team that reduces AI coding assistant token usage by 40-60% and saves 15-25% of session time.

ZeroCTX intercepts the deterministic work that AI assistants like Claude Code spend 60-70% of their context on — running commands, reading files, fetching URLs — and handles it locally with zero token cost. Only genuine reasoning reaches the LLM.

How It Works

You: "run pytest and fix failures"

Without ZeroCTX (120K tokens, 12 min):
  Claude → run pytest → read 300 lines output → read 3 files (1500 lines)
  → think → output 200-line file → you test → repeat

With ZeroCTX (50K tokens, 8 min):
  Router    → detects: RUN + DEBUG intent           (0 tokens, <1ms)
  Build     → runs pytest, filters to 30 lines      (0 tokens, 60% saved)
  Analyzer  → extracts 20 relevant lines from files  (0 tokens, 95% saved)
  Reasoning → Claude sees minimal context, outputs diff (THE token spend)
  Validator → checks syntax, applies patch           (0 tokens)

The 6 Agents

Agent	What It Does	Token Cost
Router	Regex-based intent detection + task decomposition	0
Fetch	Web fetch, git clone, file read (parallel)	0
Build	Shell execution + output filtering (30+ filters)	0
Analyzer	Error auto-fix, AST compression, context caching	0
Reasoning	Single focused Claude API call	THE spend
Validator	Lint, typecheck, apply diff patches	0

Installation

From Source (recommended for now)

# Prerequisites: Rust toolchain (https://rustup.rs)
git clone https://github.com/user/zeroctx.git
cd zeroctx/zero
cargo build --release

# Binary is at target/release/zero (or zero.exe on Windows)
# Add to PATH or copy to a directory in your PATH

From Cargo (once published)

cargo install zeroctx

Pre-built Binaries (coming soon)

Download from the Releases page for your platform:

zero-x86_64-unknown-linux-gnu (Linux)
zero-x86_64-pc-windows-msvc.exe (Windows)
zero-x86_64-apple-darwin (macOS Intel)
zero-aarch64-apple-darwin (macOS Apple Silicon)

Quick Start

1. Install the Claude Code hook (one time)

zero install

This writes a PreToolUse hook to ~/.claude/settings.json that automatically intercepts Claude Code's Bash and Read tool calls, routing them through ZeroCTX for compression.

That's it. Your next Claude Code session will use 40-60% fewer tokens automatically.

2. Or use standalone

Interactive REPL:

zero
> run pytest and fix failures
> fetch https://docs.rs/tokio and summarize
> read src/auth.rs and explain the login flow

One-shot mode:

zero "run pytest and fix failures"
zero "dotnet test and fix CS0246 errors"
zero "npm run build and fix type errors"

What Gets Optimized

Output Filters (30+ commands, 60-90% savings)

Every command output is compressed before reaching the LLM:

Category	Commands	Typical Savings
Git	status, diff, log, show, branch, gh	60-80% (large diffs: bar-chart stat view, see below)
Python	pytest, ruff, mypy, pip	70-90%
JavaScript	eslint, tsc, jest, vitest, npm, next, playwright	70-90%
.NET	dotnet build, dotnet test, nuget, format	60-85%
Rust	cargo build, cargo test, cargo clippy	80-90%
System	ls, tree, grep, find, cat, wc, env, logs	50-75%
Network	curl, wget	60-70%
Glob + Grep	Claude Code Glob/Grep tool calls	80-95%

Smart Large-Diff Auto-Stat (v0.3): When a git diff produces more than 300 changed lines (lines starting with + or -), ZeroCTX switches to a stat bar-chart view and includes full content only for the 3 most-changed files:

 src/filters/git.rs        | ████████████████  87 ++/31 --
 src/analyzer/context.rs   | ████████████  61 ++/14 --
 src/agents/build.rs       | ████████  44 ++/9 --
 tests/integration_test.rs | ██  12 ++/3 --
 ... 7 more files (142 ++/38 -- total)

[Full diff shown for: src/filters/git.rs, src/analyzer/context.rs, src/agents/build.rs]

Error Auto-Fix (60+ patterns, 100% savings when matched)

Common errors are fixed instantly without calling the LLM:

ModuleNotFoundError: No module named 'requests'
  → auto-runs: pip install requests (0 tokens, <2 sec)

Cannot find module 'lodash'
  → auto-runs: npm install lodash (0 tokens, <3 sec)

CS0246: The type or namespace 'Newtonsoft' could not be found
  → auto-runs: dotnet add package Newtonsoft.Json (0 tokens, <3 sec)

E0433: unresolved import `serde`
  → auto-runs: cargo add serde (0 tokens, <2 sec)

Supported languages: Python (15+ patterns), JavaScript/TypeScript (15+), C#/.NET (20+), Rust (10+)

AST Compression (60-98% savings per file)

When Claude needs to read a file, ZeroCTX extracts only the relevant functions:

Without: Claude reads all 500 lines of auth.rs
With:    Error mentions verify_token → extract only that function (12 lines)
Savings: 98%

Uses tree-sitter for accurate AST parsing across Python, JavaScript/TypeScript, C#, and Rust.

Error-line-aware extraction (v0.3): When an error references a specific line (e.g. src/auth.py line 42), ZeroCTX extracts the full body of the function containing that line. All other functions remain as signatures only. This is more targeted than uniform signature extraction — you get full context exactly where the error is, and nothing else.

Context Caching (70%+ savings on round 2+, cross-session)

Files are MD5-hashed and the cache is persisted to SQLite (%APPDATA%\zeroctx\cache.db on Windows, ~/.zeroctx/cache.db elsewhere). On subsequent rounds — including across sessions — unchanged files become one-line summaries. Deduplication is mtime-based: if a file's modification time hasn't changed since the last session, the compressed version is returned instantly without re-reading. Cache entries expire after 30 days.

Round 1: auth.rs (500 lines, full content)       → 1250 tokens
Round 2: auth.rs (unchanged, summary only)        → 15 tokens  (same session or new session)
Savings: 99%

Glob + Grep Output (80-95% savings)

PostToolUse hooks compress the output of Claude Code's Glob and Grep tool calls before they reach the context window.

Glob — groups file paths by directory instead of listing each path separately:

Before (8 lines):
  src/filters/git.rs
  src/filters/python.rs
  src/filters/javascript.rs
  ...

After (1 line):
  src/filters/ (8 files: git.rs, python.rs, javascript.rs, ...)

Grep — groups matches by file with inline previews:

Before (12 lines of raw matches):
  src/auth.rs:14:  let token = ...
  src/auth.rs:27:  let token = ...
  ...

After (1 line):
  src/auth.rs (12 matches) > let token = ...

Diff-Only Output (90% fewer output tokens)

Claude generates unified diffs instead of full files:

Without: Claude outputs entire 200-line file     → 2000 output tokens (5x pricing)
With:    Claude outputs 5-line diff patch         → 100 output tokens
Savings: 95% on output tokens (which cost 5x input tokens)

Project Brief

ZeroCTX can inject a compressed project summary at the start of each Claude Code session, saving Claude from re-reading your README, Cargo.toml, or package.json every time.

Create .zeroctx/brief.md (≤200 lines) in your project root. ZeroCTX automatically prepends a compressed version once per day when a Claude Code session starts.

# Show the current brief
zero brief

# Auto-generate a brief from README.md, Cargo.toml, or package.json
zero brief --generate

The generated brief is a concise summary of project name, purpose, key dependencies, and entry points. Edit it freely — ZeroCTX compresses it further before injection so even a 200-line brief costs very few tokens.

Configuration

ZeroCTX uses TOML configuration with three levels of precedence:

Project:  .zeroctx/config.toml     (highest priority, committed with repo)
Global:   ~/.zeroctx/config.toml   (user-wide defaults)
Built-in: defaults.toml            (shipped with binary)

Example `.zeroctx/config.toml`

[general]
# Claude API model for reasoning agent
model = "claude-sonnet-4-20250514"
# Maximum tokens for Claude API calls
max_tokens = 4096
# Context budget in characters (~4 chars = 1 token)
context_budget = 12000

[limits]
# Output filter limits
grep_max_results = 200
grep_max_per_file = 25
git_status_max_files = 30
git_diff_max_hunk_lines = 100
max_output_size = "100MB"

[filters]
# Directories to ignore in tree/find
ignore_dirs = [".git", "node_modules", "target", "bin", "obj", "__pycache__", ".venv"]
ignore_files = ["*.lock", "*.min.js", "*.min.css"]

[session]
# Enable context caching across rounds
cache_enabled = true
# Session database location (default: ~/.zeroctx/sessions.db)
# database_path = "/custom/path/sessions.db"
# How long to keep session data
history_days = 90

[autofix]
# Enable automatic error fixing
enabled = true
# Auto-run fix commands without confirmation
auto_run = true
# Package name mappings (Python: import name → pip package)
[autofix.python_mappings]
cv2 = "opencv-python"
PIL = "Pillow"
sklearn = "scikit-learn"
yaml = "PyYAML"
bs4 = "beautifulsoup4"

[hooks]
# Commands to never intercept (pass through unchanged)
exclude_commands = ["ssh", "vim", "nano", "less"]

[export]
# Default export format
default_format = "json"
# Output directory for exports
output_dir = ".zeroctx/reports"

[logging]
# Log level: error, warn, info, debug, trace
level = "info"

Environment Variables

All config values can be overridden via environment variables:

ZEROCTX_MODEL=claude-sonnet-4-20250514
ZEROCTX_MAX_TOKENS=4096
ZEROCTX_CONTEXT_BUDGET=12000
ZEROCTX_LOG_LEVEL=debug
ANTHROPIC_API_KEY=sk-ant-...    # Required for reasoning agent

Adapting ZeroCTX to Your Project

Custom Output Filters

Add project-specific filters in .zeroctx/filters.toml:

[filters.my-build-tool]
description = "Compact my-build-tool output"
match_command = "^my-build-tool\\s+"
strip_ansi = true
strip_lines_matching = ["^\\s*$", "^Downloading", "^\\s+Compiling"]
keep_lines_matching = ["^ERROR", "^WARNING", "^FAILED"]
max_lines = 50
on_empty = "my-build-tool: ok"

[[tests.my-build-tool]]
name = "filters build noise"
input = "Downloading dep1...\nDownloading dep2...\nCompiling...\nERROR: missing field"
expected = "ERROR: missing field"

Custom Error Patterns

Add project-specific auto-fix patterns in .zeroctx/patterns.toml:

[[patterns]]
regex = "DOCKER_ERROR: image '(.+)' not found"
category = "docker_missing_image"
fixable = true
command = "docker pull {1}"
explanation = "Docker image not found locally, pulling from registry"

[[patterns]]
regex = "MIGRATION_ERROR: pending migrations"
category = "db_migration"
fixable = true
command = "dotnet ef database update"
explanation = "Database has pending Entity Framework migrations"

Custom Intent Signals

Extend the router with project-specific keywords in .zeroctx/intents.toml:

[[signals]]
keywords = ["deploy", "release", "publish"]
intent = "RUN_AND_DEBUG"
default_command = "make deploy"

[[signals]]
keywords = ["migrate", "seed", "schema"]
intent = "RUN_AND_DEBUG"
default_command = "dotnet ef database update"

CLI Reference

USAGE:
    zero [OPTIONS] [REQUEST]
    zero <COMMAND>

ARGUMENTS:
    [REQUEST]    Natural language request (one-shot mode)

COMMANDS:
    install      Install Claude Code PreToolUse hook
    uninstall    Remove Claude Code hook
    rewrite      Rewrite a command (used by hooks internally)
    compress     Compress a file for context (used by hooks internally)
    stats        Show token savings dashboard
    export       Export tracking data (--format json|csv|html|pdf)
    config       Show current configuration
    brief        Show current project brief (--generate to auto-create from README/Cargo.toml/package.json)
    session      Show live session cost/savings dashboard (last 24 hours)
    version      Show version information

OPTIONS:
    -c, --config <PATH>    Path to config file
    -v, --verbose          Increase verbosity (-v, -vv, -vvv)
    -q, --quiet            Suppress non-essential output
    --no-cache             Disable context caching for this session
    --no-autofix           Disable error auto-fix for this session
    --dry-run              Show what would be done without executing

Examples

# Interactive REPL
zero

# One-shot commands
zero "run pytest and fix failures"
zero "git diff HEAD~5 --stat"
zero "dotnet test and explain failures"

# Hook management
zero install          # Install Claude Code hook
zero uninstall        # Remove hook

# Analytics
zero stats                              # Token savings dashboard
zero stats --daily                      # Day-by-day breakdown
zero export --format html -o report.html  # HTML report
zero export --format pdf -o report.pdf    # PDF report
zero export --format csv -o data.csv      # CSV export
zero export --format json                 # JSON to stdout

# Session monitoring
zero session                            # Live session cost/savings dashboard

# Project brief
zero brief                              # Show current brief
zero brief --generate                   # Auto-generate from README/Cargo.toml/package.json

# Debugging
zero rewrite "git status"               # Test command rewriting
zero compress src/auth.rs               # Test file compression
zero --dry-run "run pytest"             # Show pipeline without executing

Session Monitoring

zero session shows a live dashboard of the current session's cost and savings, using the last 24 hours of tracking data:

=== ZeroCTX Session (24 hours) ===
  Started:  2026-04-22 14:07:44
  Commands: 77
  Tokens:   ~133K input / ~37K output  ($0.964 est.)
  Saved:    ~96K tokens (42%) via ZeroCTX  ($0.289 saved)
  Without:  ~230K tokens would have been used  ($1.253 est.)
==================================

Token counts are estimated from tracking data. Cost estimates use current Claude Sonnet pricing and update automatically when you upgrade models via ZEROCTX_MODEL.

Architecture

                     ┌─────────────────────────────────┐
                     │         CLI / Hook Entry         │
                     │   REPL | One-shot | PreToolUse   │
                     └──────────────┬──────────────────┘
                                    │
                     ┌──────────────▼──────────────────┐
                     │         Router Agent             │
                     │   Intent classify (regex)        │
                     │   Task decompose (multi-step)    │
                     │   0 tokens                       │
                     └──────────────┬──────────────────┘
                                    │
                  ┌─────────────────┼─────────────────┐
                  ▼                                    ▼
   ┌──────────────────────┐             ┌──────────────────────┐
   │     Fetch Agent       │             │     Build Agent       │
   │  web_fetch, git_clone │             │  shell exec + filter  │
   │  file read, dir list  │             │  30+ OutputFilters    │
   │  0 tokens (parallel)  │             │  0 tokens             │
   └──────────┬───────────┘             └──────────┬───────────┘
              └─────────────────┬──────────────────┘
                                ▼
                 ┌──────────────────────────────┐
                 │       Analyzer Agent          │
                 │  ErrorClassifier (60+ regex)  │
                 │  → auto-fix? DONE (0 tokens)  │
                 │  ASTCompressor (tree-sitter)  │
                 │  ContextCache (SQLite, mtime) │
                 │  ContextBuilder (budget)      │
                 │  0 tokens                     │
                 └──────────────┬───────────────┘
                                │ only if reasoning needed
                                ▼
                 ┌──────────────────────────────┐
                 │      Reasoning Agent          │
                 │  Claude API (diff prompt)     │
                 │  *** THE token spend ***      │
                 └──────────────┬───────────────┘
                                ▼
                 ┌──────────────────────────────┐
                 │      Validator Agent          │
                 │  Syntax check (per-language)  │
                 │  Diff apply (patch)           │
                 │  Auto-retry on failure        │
                 │  0 tokens                     │
                 └──────────────────────────────┘

Realistic Savings

Based on analysis of typical Claude Code sessions:

Scenario	Tokens	Time	Savings
Debug session (test → fix → retest)	50-70% fewer	40% faster	Error auto-fix eliminates round-trips
Feature development (read → write → test)	35-55% fewer	25% faster	AST compression + filtered output
Iterative refactor (same files, 3+ rounds)	45-65% fewer	35% faster	Context cache compounds across rounds
Simple Q&A	10-20% fewer	~same	Most tokens are in Claude's reasoning

Monthly cost impact (solo developer):

Without ZeroCTX: ~$160/month
With ZeroCTX: ~$60-100/month
Savings: $60-100/month per developer

Extending ZeroCTX

Adding a New Output Filter

Implement the OutputFilter trait:

use crate::filters::{OutputFilter, FilterResult};

pub struct MyToolFilter;

impl OutputFilter for MyToolFilter {
    fn name(&self) -> &str { "my-tool" }

    fn matches(&self, command: &str) -> bool {
        command.starts_with("my-tool ")
    }

    fn filter(&self, output: &str, config: &Config) -> FilterResult {
        let filtered = output.lines()
            .filter(|line| line.contains("ERROR") || line.contains("WARNING"))
            .collect::<Vec<_>>()
            .join("\n");

        FilterResult {
            output: filtered,
            original_lines: output.lines().count(),
            filtered_lines: filtered.lines().count(),
        }
    }
}

Adding Error Patterns

Add to src/errors/patterns.rs:

Pattern {
    regex: r"MY_ERROR:\s+(.+)\s+not found in (.+)",
    category: "my_tool_not_found",
    languages: &[Language::All],
    fixable: true,
    fix_command: Some("my-tool install {1}"),
    explanation: "Resource not found, installing automatically",
}

Adding Language Support

Implement the Language trait:

use crate::languages::{LanguageSupport, ValidationResult};

pub struct GoLanguage;

impl LanguageSupport for GoLanguage {
    fn extensions(&self) -> &[&str] { &[".go"] }
    fn name(&self) -> &str { "go" }

    fn validate(&self, code: &str) -> ValidationResult {
        // Run: go vet
    }

    fn compress_ast(&self, source: &str, relevant_names: &[String]) -> String {
        // Use tree-sitter-go to extract relevant functions
    }
}

Comparison with RTK

ZeroCTX was inspired by RTK but addresses its limitations:

Feature	RTK	ZeroCTX
Output filtering	60-90% savings	60-90% (same quality, trait-based)
Error auto-fix	No	60+ patterns, auto-installs packages
AST compression	Partial (body stripping)	Full (tree-sitter, extracts relevant functions)
Context caching	No	MD5 dedup, cross-session SQLite, mtime-based, 70%+ savings on round 2+
Diff-only output	No	90% fewer output tokens
Task decomposition	No	Regex-based multi-step splitting
Output validation	No	Per-language syntax + lint checking
Session state	Stateless	SQLite session persistence
Error handling	65+ unwraps	Zero unwraps (anyhow/thiserror)
Configuration	Hard-coded limits	All configurable via TOML
Architecture	God objects, duplication	Trait-based, modular

License

ZeroCTX is distributed under a Dual-Use License (see LICENSE for the full text).

Non-commercial use is free — personal, academic, and research use are permitted at no cost, subject to retaining the copyright notice. You may use, copy, modify, and distribute ZeroCTX for any non-revenue-generating purpose.

Commercial use requires a paid license. This includes use within for-profit organizations, integration into paid products or services, internal tooling that supports revenue-generating operations, and SaaS/consulting/agency deployments.

Tier	Price	Scope
Builder	$79	1 developer
Studio	$349	Up to 5 developers
Platform	$1,999	Org-wide internal deployment

For commercial licensing, open an issue at the repository.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.claude/commands		.claude/commands
.serena		.serena
hooks		hooks
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation