T Zero Context Architect README

# 📦 Option A: Node.js / npx (Zero-Config Instant MCP Runner):
# Run directly in Claude Desktop, Cursor, Antigravity, Copilot:
npx -y tzero-mcp@latest

# Global CLI installation via npm:
npm install -g tzero-mcp

# 🐍 Option B: Python PyPI Package:
pip install --upgrade tzero-mcp

# 🌟 Option C: 1-Line Native Shell Installers:
# Linux / macOS / WSL:
curl -fsSL https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.sh | bash
# Windows (PowerShell):
irm https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.ps1 | iex

# 🚀 1-Click Configure MCP in Cursor, Claude, Antigravity, Windsurf:
tzero init

# 🧩 Install VS Code / Cursor Extension (.vsix):
code --install-extension dist/tzero-vscode-10.8.0.vsix

⚡ Executive Summary: What is T-Zero?

T-Zero is an open-source deterministic code context compression engine and Model Context Protocol (MCP) server for Cursor, Claude Code, Google Antigravity IDE, Windsurf, Cline, Zed, and VS Code.

It solves the Context Token Crisis: when AI coding models ingest entire codebases as flat text, 80% to 95% of prompt tokens are spent on repetitive internal function bodies, routine loops, local math, and implementation boilerplate.

🥊 Context Architecture Comparison Matrix

🧪 Empirical Task-Completion & BPE Tokenizer Benchmark

Key Architectural Question: Does signature-only context allow an AI coding agent to complete real-world tasks correctly, or does it cause hallucination?

The T-Zero Smart Skeleton (Tier-2) Design:

When an agent works on a target file, T-Zero does NOT prune the active file. Instead:

1. Target Focus File: Delivered at 100% full implementation (all logic, loops, and statements).
2. Surrounding 1st-Degree Dependencies: Pruned to AST Interface Skeletons (classes, exported functions, parameter types, return annotations, and docstrings).

This gives the LLM complete visibility into how to call surrounding modules without blowing up token budgets on internal dependency details.

Empirical Evaluation (Measured with official tiktoken BPE Tokenizer: cl100k_base):

==============================================================================
  T-ZERO TASK-COMPLETION & BPE TOKENIZER BENCHMARK REPORT (v9.9.0)
  Tokenizer: tiktoken (cl100k_base) | Benchmark Script: tzero_task_benchmark.py
==============================================================================
Task ID    | Scope                                 | Raw BPE | T-Zero | Token Savings | Contract Integrity | Task Success
------------------------------------------------------------------------------------------------------------------
TASK-01    | Cross-Module Redis Rate Limiter       | 502     | 375    | -25.3%        | 100.0%             | PASS (0 Halluc)
TASK-02    | Crypto Vault Key Rotation             | 322     | 239    | -25.8%        | 100.0%             | PASS (0 Halluc)
TASK-03    | AST Slicer & Blast Radius Evaluator   | 332     | 283    | -14.8%        | 100.0%             | PASS (0 Halluc)
------------------------------------------------------------------------------------------------------------------
FULL REPO  | Enterprise Repository (51,000 LOC)    | 1,168k  | 64.2k  | -94.5%        | 100.0%             | PASS (0 Regress)
==============================================================================
OVERALL TASK SUCCESS RATE: 100.0% (Zero Hallucinated Methods, 100% Valid Syntax)
AVERAGE REPOSITORY TOKEN REDUCTION: -94.5% (BPE Exact Tokens)
==============================================================================

To reproduce these numbers locally:

python tzero_task_benchmark.py

🌐 Language Support Breakdown: AST vs. Heuristic Extraction

We believe in radical engineering transparency:

🚀 Universal 1-Click IDE Setup (All Editors)

T-Zero automatically configures your editor in 1 second using native Model Context Protocol (MCP) standards:

# 1-Click auto-detect and configure all installed editors:
tzero init

# Or target your preferred editor directly:
tzero init --cursor        # Cursor IDE
tzero init --claude        # Claude Desktop & Claude Code
tzero init --antigravity   # Google Antigravity IDE
tzero init --windsurf      # Windsurf Editor
tzero init --cline         # Cline / Roo Code
tzero init --vscode        # VS Code (Continue / Copilot)
tzero init --zed           # Zed Editor

# Install official VS Code / Cursor Extension (.vsix):
code --install-extension dist/tzero-vscode-10.0.0.vsix

Manual Configuration Snippets (Any MCP Client)

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

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

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

🛠️ The 20 Canonical MCP Tools

All 20 canonical tools (and 52 full tools) are audited and verified against the Model Context Protocol specifications (tested by tests.test_mcp):

⚡🔥 Turbo Overdrive Burst Accelerator ("Kamçılama Modu")

When scanning large codebases or generating deep AST context trees, disk latency or large file volumes can introduce processing delays. T-Zero features Turbo Overdrive — an adaptive latency sensor that detects slowdowns (>150ms or $\ge 15$ source files) and automatically engages burst acceleration:

• 🚀 Dynamic Multi-Core Parallelism: Automatically spawns up to 32 worker threads matching available CPU cores.
• ⚡ Sub-Millisecond In-Memory Fast-Path Cache: Validates st_mtime and file size to return pruned ASTs in under 2ms without re-parsing.
• 🛡️ Zero-Leak & Zero-Regression: 100% thread-safe memory lock (RLock), $0 cloud cost, completely local.

# View live Turbo Overdrive status & cache telemetry:
tzero turbo

# Run live benchmark comparing sequential processing vs Turbo Overdrive:
tzero turbo bench

# Clear accelerator in-memory cache:
tzero turbo clear

🐝 Autonomous Dynamic Subagent Decomposer & Swarm

When given a complex mission (e.g. "Audit secrets, verify architectural boundaries, optimize database queries, and generate unit tests"), T-Zero automatically:

1. Decomposes Composite Goals: Identifies independent subtasks across security, architecture, performance, testing, and custom domains.
2. On-The-Fly Subagent Synthesis: Spawns specialized ad-hoc subagents dynamically via AgentForge when custom domain expertise is required.
3. Multi-Core Parallel Burst: Dispatches non-conflicting subagents concurrently using the Turbo Overdrive thread pool.
4. PBFT Consensus & Executive Dossier: Aggregates verdicts into an audited executive dossier with an interactive Mermaid DAG topology.

# Decompose and execute composite mission across dynamic subagents:
tzero subagent "Audit security, check AST architecture, and run test coverage"

# Run swarm with custom domain requirements (auto-synthesizes ad-hoc agents):
tzero swarm "Migrate database schema and optimize websocket streaming"

🏆 100% TDQS 5.0 / 5.0 Anchor Certification Standard

T-Zero is officially certified at TDQS 5.0 / 5.0 (Anchor Standard) across all 52 registered Model Context Protocol tools.

What is TDQS (Tool Documentation Quality Score)?

Frontier LLMs (Claude 3.5 Sonnet, GPT-4o, Gemini 1.5/2.0 Pro) rely exclusively on tool docstrings and parameter schemas to decide:

1. Which tool to call among dozens of registered capabilities.
2. How to invoke it without argument hallucinations.
3. Whether the tool is safe (read-only vs destructive, local vs open-world network).

When tool descriptions are vague or contradictory, AI models suffer from Tool Hallucination, calling the wrong tool or inventing arguments.

The 6 Audited Mathematical Dimensions:

Automated Verification Pipeline:

Every single tool is continuously audited in CI via:

# Automated TDQS 5.0/5.0 unit test:
python -m unittest tests/test_tdqs_anchor5.py -v

# Full 52-tool audit runner:
python scripts/comprehensive_tdqs_audit.py
# Output: ✅ PERFECT 5/5! No issues detected across all 52 tools!

🤗 Hugging Face Spaces Live Web Application

Test T-Zero directly in your browser without installing anything locally via our official Gradio application:

• Live URL: https://huggingface.co/spaces/toprakke4/tzero-token-reducer
• Features: Live AST Skeletonizer, Token Reduction Calculator, Secret Scrubber, and Reality-Lock Playground.

Running the App Locally:

tzero space
# or: python huggingface-space/app.py (opens at http://localhost:7860)

⚖️ Pre-Flight Reality-Lock (Static AST Verification)

AI coding assistants frequently hallucinate non-existent methods (e.g., math.quantum_fast_inverse_sqrt) or phantom library imports.

T-Zero's HallucinationGuard statically validates candidate method calls and imports against the verified project AST symbol table and Python standard library:

# Test code snippet:
tzero --hallucination-check "import math; x = math.sqrt(25)"
# Output: [REALITY-LOCK PASS] All imported symbols and method calls physically exist in AST.

tzero --hallucination-check "import math; x = math.non_existent_fake_method()"
# Output: [HALLUCINATION DETECTED] Found 1 hallucinated symbol:
#   - Line 1: Method `non_existent_fake_method` does not exist in module `math`.

(Note: Pre-Flight Reality-Lock performs static AST analysis. It catches static signature mismatches and non-existent symbols; it does not emulate runtime dynamic reflection or monkey-patching).

🔒 Security Architecture: Deterministic Secret Scanner

OS-Native Credential Storage:

T-Zero uses platform-native secret vaults:

• Windows: Windows Credential Manager
• macOS: macOS Keychain
• Linux: Secret Service API / libsecret

High-Entropy Secret Scanner ($H \ge 4.75$):

• Analyzes candidate strings using Shannon entropy: $$H(X) = -\sum_{i=1}^{n} P(x_i) \log_2 P(x_i)$$
• Strings with entropy $H \ge 4.75$ combined with credential prefixes (sk-, ghp_, AKIA, postgres://) are automatically flagged and masked to prevent leakage.
• Air-Gapped Environments: Automatic dependency checks can be strictly disabled by setting TZERO_NO_AUTO_INSTALL=1.
• Zero Cloud Transmission: Code parsing, AST pruning, and search run 100% locally on your machine with zero external network telemetry.

📊 Multi-Model Financial ROI Benchmarks

Empirical measurements conducted across real software repositories comparing raw prompt context injection against T-Zero AST-pruned context:

Calculation based on a 10-developer team executing 25 agent prompt turns/day (5,500 queries/month).

🌐 Global Ecosystem & Multilingual Architecture

T-Zero is engineered from the ground up for global software engineering teams, supporting cross-platform operating systems and international coding standards.

Dedicated Language Guides

• English (Primary & Canonical): You are viewing the official English reference documentation.
• Turkish Translation: For native Turkish documentation and setup guides, see README.tr.md.

30-Second Turnkey Quickstart

# 1. Install via PyPI:
pip install tzero-mcp

# 2. One-click auto-configure Cursor, Claude Desktop, Antigravity, and Windsurf:
tzero init

# 3. Compress target codebase AST into an ultra-dense context payload:
tzero --tree . --out context.txt

# 4. Launch local Zero-GPU Web Studio:
tzero space

🩺 T-Zero PC-Fixer & Codebase Doctor: The 12,600+ Line Autonomous Self-Healing Monolith

T-Zero PC-Fixer is an autonomous, zero-dependency operating system doctor and static AST self-healing engine compiled into a single 12,600+ line Python monolith (tzero_pc_fixer.py). It diagnoses and surgically cures broken developer workstations, memory leaks, orphaned zombie processes, contaminated environments, and static codebase defects with $0.00 cloud cost.

🚀 1-Click Zero-Dependency Installers

Windows (PowerShell 5.1+ / 7+):

irm https://raw.githubusercontent.com/toprakahmetaydogmus/tzero-pc-fixer/main/install.ps1 | iex

macOS / Linux (Bash):

curl -fsSL https://raw.githubusercontent.com/toprakahmetaydogmus/tzero-pc-fixer/main/install.sh | bash

🧰 Autonomous Healing Capabilities:

• 🖥️ Hardware & Process Surgeon: Hunts runaway compiler/Node.js zombie processes, clears swap memory, verifies disk partition health, and unblocks port collisions (e.g. 8000, 3000, 5000, 8080).
• 🐍 Python & Virtual Environment Doctor: Detects broken symlinks, repairing contaminated sys.path, corrupted wheel caches, and Microsoft Store Python PATH hijacking.
• 🛡️ CWE-78 & CWE-327 Static AST Remediator: Rewrites dangerous subprocess.Popen(shell=True) into safe array invocations and retrofits legacy md5 calls with usedforsecurity=False.
• ✂️ Dead Code & Zombie Function Eliminator: Uses AST reachability analysis to purge unreachable code after return/raise statements and private orphaned functions.
• ⚡ Async/IO Event Loop Modernizer: Detects blocking time.sleep() calls inside async def routines and transplants them with non-blocking await asyncio.sleep().

⭐ Support Open-Source Innovation!

Hi! I'm Toprak Ahmet Aydoğmuş from Siber Akademi. I built T-Zero from scratch to solve context window bloat, token bills, and AI hallucinations for developers worldwide with 100% free, offline, local tools ($0.00 cloud cost).

If T-Zero helped you cut prompt tokens or saved your daily coding workflow, please consider giving us a star! Every star helps open-source developers worldwide. 🚀

📈 Star History

Join the revolution in context engineering and deterministic token pruning!

📜 License & Siberian Academy

• Author & Architect: Toprak Ahmet Aydoğmuş (Lead Software Engineer & Architect, Siber Akademi)
• LinkedIn: Toprak Ahmet Aydoğmuş
• Bio & Hub: hopp.bio/siberegitim
• License: MIT Open Source License