<a id="top"></a>

<div align="center">

T-Zero

High-performance AST context pruner & MCP server for AI coding assistants.
Reduces codebase prompt tokens by up to 94.9% while preserving complete class contracts, typed signatures, and cross-file dependencies.

<br> <p align="center"> <a href="https://github.com/toprakahmetaydogmus/TZeroAlgorithm/raw/main/assets/brag.mp4"> <img src="assets/brag-preview.gif" alt="T-Zero 20s Launch Demo Video" width="100%" style="max-width: 850px; border-radius: 12px; box-shadow: 0 12px 36px rgba(0, 0, 0, 0.6);"> </a> </p> <p align="center"> <a href="https://huggingface.co/spaces/toprakke4/tzero-token-reducer"> <img src="assets/live-demo-button.svg" alt="Try Live Interactive Demo" height="38"> </a> </p>

Why T-Zero • Quickstart • Benchmarks • Tools Reference • Architecture • Türkçe

</div>

---

Why T-Zero?

When an AI coding assistant (Cursor, Claude Code, Antigravity IDE, Windsurf, Cline) reads your codebase, feeding full source files wastes 80% to 95% of your context window on internal loop bodies, routine calculations, and local variables. The model needs to know what your modules expose and call, not 100 lines of boilerplate implementation inside each method.

T-Zero acts like an on-the-fly .pyi / .d.ts declaration generator for your AI context window:

┌─────────────────────────────────┐
│     Full Source Codebase        │  (166,996 raw tokens — $0.50/query, 18s latency)
└────────────────┬────────────────┘
                 │
                 ▼  [ T-Zero Native AST Parser ]
                 │  Strips routine bodies, preserves signatures, types & docs
                 ▼
┌─────────────────────────────────┐
│     T-Zero AST Skeleton Tree    │  (8,465 tokens — $0.025/query, 2.1s latency)
└─────────────────────────────────┘

Before vs. After AST Pruning

# BEFORE: Raw source file (1,240 tokens)
class PaymentGateway:
    def __init__(self, api_key: str, timeout: int = 30):
        # 30 lines of connection pooling, socket configuration, SSL contexts...
        self.session = requests.Session()
        self.timeout = timeout
        ...

    def process_charge(self, user_id: str, amount_cents: int, currency: str = "USD") -> TransactionResult:
        """Charges a customer card with automated retry and idempotency."""
        # 60 lines of payload hashing, error handling, database locking, telemetry...
        if not user_id:
            raise ValueError("user_id required")
        ...

# AFTER: T-Zero AST Skeleton (64 tokens — 94.8% reduction)
class PaymentGateway:
    def __init__(self, api_key: str, timeout: int = 30): ...

    def process_charge(self, user_id: str, amount_cents: int, currency: str = "USD") -> TransactionResult:
        """Charges a customer card with automated retry and idempotency."""
        ...

The AI assistant retains full access to class names, typed parameters, docstrings, and return types — with zero semantic loss, at a fraction of the token cost, and with drastically faster Time-To-First-Token (TTFT).

---

Quickstart

1. ⚡ One-Click Auto-Install (Zero Configuration)

Automatically detect and configure Cursor, Claude Desktop, Antigravity IDE, Windsurf, Cline, and VS Code in 5 seconds with zero manual JSON editing:

uvx tzero-mcp --add-mcp
# or using pipx
pipx run tzero-mcp --add-mcp

2. Instant Run via uvx or pipx (Zero Installation)

# Launch MCP server stdio transport instantly:
uvx tzero-mcp
# or:
pipx run tzero-mcp

3. Install via pip

pip install tzero-mcp

4. Manual Configuration for Cursor / Claude Desktop / Antigravity / Windsurf

Add the following to your claude_desktop_config.json or Cursor Settings (Features → MCP):

{
  "mcpServers": {
    "tzero": {
      "command": "uvx",
      "args": ["tzero-mcp"]
    }
  }
}

Or using local python:

{
  "mcpServers": {
    "tzero": {
      "command": "python",
      "args": ["-m", "tzero_mcp"]
    }
  }
}

5. Claude Code CLI Integration

claude mcp add --scope user tzero uvx tzero-mcp

6. Launch Local Web Dashboard

tzero --dashboard

Opens the local browser dashboard on http://localhost:8421 featuring interactive dependency graphs and the live AST pruner sandbox.

7. 🛡️ Pre-Commit Hook (Auto Zero-Leak & Token Guard)

Prevent accidental credential leaks and token bloat before code ever leaves developer machines. Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/toprakahmetaydogmus/TZeroAlgorithm
    rev: v8.0.1
    hooks:
      - id: tzero-guard
      - id: tzero-audit

8. ⚡ GitHub Actions CI/CD Integration

Automatically audit repositories for zero hardcoded secrets and generate token optimization summaries on every commit and PR:

# .github/workflows/tzero.yml
name: T-Zero Codebase Guard
on: [push, pull_request]

jobs:
  tzero-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: toprakahmetaydogmus/TZeroAlgorithm@main
        with:
          workspace-dir: '.'
          audit-level: 'strict'

9. 🏅 Badge of Honor: Show Your Repo is Context-Optimized

If your repository, library, or framework is optimized for AI coding assistants using T-Zero, embed our official badge in your README.md. This signals to developers and AI coding agents that your repository can be ingested with 90%+ less token overhead:

[![Context Optimized with T-Zero](https://img.shields.io/badge/Context-T--Zero%20Optimized%20(-90%25)-blue?style=flat-square&logo=python)](https://github.com/toprakahmetaydogmus/TZeroAlgorithm)

Live Preview:

Dark Mode / Slate variant:

[![Context Optimized with T-Zero](https://img.shields.io/badge/Context-T--Zero%20Optimized%20(-90%25)-38bdf8?style=flat-square&logo=python&labelColor=0f172a)](https://github.com/toprakahmetaydogmus/TZeroAlgorithm)

---

Reproducible Benchmarks

<p align="center"> <img src="assets/benchmark-demo.svg" alt="T-Zero Live AST Context Pruning Benchmark" width="100%"> </p>

⚡ Head-to-Head Comparison: Raw Code vs. T-Zero AST Engine

| Dimension | Raw Codebase Ingestion | T-Zero AST Context Architecture | Impact / Developer Advantage | |:---|:---|:---|:---:| | Context Window Consumption | 166,996 tokens (90%+ routine bodies) | 8,465 tokens (pure typed signatures) | 🔥 94.9% Token Reduction | | API Cost per Pass (Claude 3.7 / GPT-4o) | $0.501 per query | $0.025 per query | 💰 20x Cost Savings | | Response Latency (TTFT) | 18.4s slow time-to-first-token | 2.1s instant response | ⚡ 8.7x Faster Generation | | Hallucination Risk (Ghost Imports/Params) | High (phantom packages & invented args) | 0% (Blocked by 5-Tier AST Guard) | 🛡️ 100% Deterministic | | Helper Function Reusability | Poor (AI constantly reinvents wheels) | Auto-Surfaced (suggest_reusable_helpers) | ♻️ Zero Logic Duplication | | Security Leak Vulnerability | High (.env secrets & tokens leaked to API) | 0 Leaks (100% Offline Zero-Leak AST) | 🔒 100% Zero-Leak Certified | | Tool Definition Quality (TDQS) | Untested / Ad-hoc | Anchor-5 Certified (Grade A 5.0/5.0) | ⭐ 0 Notes / 0 Warnings |

<br>

| Analysis Target | Raw Codebase Tokens | T-Zero AST Payload | Token Savings | Cost per Query (Claude 3.7 / GPT-4o) | Latency (TTFT) | |:---|:---:|:---:|:---:|:---:|:---:| | Full Repository Scan (38K LOC) | 166,996 tokens | 8,465 tokens | -94.9% | $0.501 → $0.025 | 18.4s → 2.1s | | Large Backend Service | 42,180 tokens | 2,410 tokens | -94.3% | $0.126 → $0.007 | 6.2s → 0.9s | | Git PR Diff Stream | 18,450 tokens | 1,120 tokens | -93.9% | $0.055 → $0.003 | 2.8s → 0.4s |

Verify locally on your machine with zero cloud cost:

python tzero.py --savings

---

Core Capabilities

1. AST Skeleton Pruning

Strips internal routine execution bodies while preserving every class definition, typed signature, docstring, and return type. Zero heuristic line cutting — 100% deterministic language parsing.

2. Polyglot Language Support

Zero external compiler dependencies. Supports:

• Python (via native ast parser)
• TypeScript & JavaScript (interfaces, exports, type annotations)
• Go, Rust, Java, C#, C++, PHP, and Ruby (structural signature extractors)

3. Change Blast Radius Analysis

Before refactoring a class or function, T-Zero calculates its exact downstream dependency impact (0–100 score), identifying every file, import, and symbol that could break.

4. Zero-Leak Security Guard

Guaranteed 100% offline execution. Includes pre-commit hooks and real-time scanners that block .env secrets, private tokens, and credentials from ever being sent to LLM APIs.

5. Embedded Superdesign Engine

Natively integrates the Superdesign UI methodology into Claude Code and Cursor with 5 tools to generate design systems, component specifications, and interactive browser preview galleries.

6. 5-Tier Zero-Hallucination Guard

Eliminates AI coding hallucinations before changes touch files. Statically intercepts ghost dependencies, validates workspace symbol tables and keyword arguments, enforces class schema fields, and checks return type contracts, backed by an automated self-healing AST transformer (repair_code) and immutable grounding contract generation.

7. Anti-Reinvention Engine

Automatically surfaces reusable existing utility helpers across the repository AST (suggest_reusable_helpers / --helpers), injecting ready-to-use imports into focus skeletons so AI models never duplicate code already written in your project.

---

MCP Tools Reference

🚀 Flagship Omni-Tool: execute_codebase_workflow

Execute any codebase workflow, multi-stage audit, or specific T-Zero engine in a single unified MCP command:

// Full autonomous pipeline: Security Audit + Architecture Blueprint + Token ROI + Code Quality
{
  "name": "execute_codebase_workflow",
  "arguments": {
    "action": "auto",
    "target": "."
  }
}

Or execute targeted operations on demand:

• "action": "security" — 100% Zero-Leak secret scan across workspace
• "action": "context" — Hierarchical AST context tree generation