Zero Token

Universal token firewall & compact-context optimizer for AI coding agents (Google Antigravity 2.0 & ZCode).

Stops an AI coding session from flooding its own context window with whole-file reads, unbounded grep/rg, and raw multi-megabyte build logs — without lossy history truncation or rewriting tool outputs.

Tiếng Việt · MIT · Node 18+

before   Read / read_file OrderService.cs (136 KB)       ~38,700 tokens
after    outline OrderService.cs                          ~1,470 tokens
         read_file StartLine=412 EndLine=452 (or Read offset=412 limit=40)

Why

An AI coding session pays for every single character a tool returns, and pays repeatedly on every subsequent turn because the transcript retains it. The most expensive calls are predictable:

• Opening a 3,000-line file just to inspect one method;

• Running an unconstrained recursive search that returns 9,000 matches;

• Dumping a build log with 1,800 warning lines, where only 3 error codes matter.

None of these need model judgement to fix — they need a strict, automated cap at the gateway. That is what Zero Token enforces.

Related MCP server: ctxkit

Measured Results

Token estimates use 3.6 chars/token for code and 4 chars/token for logs. Rows marked real were measured on actual enterprise solutions; the rest use synthetic fixtures sized like standard enterprise files.

The last row is the honest floor: when the build already runs with -v:q and fails early, there is little to compress. The plugin earns its keep on large files, repo-wide searches, and warning-heavy builds.

Its own permanent overhead is only about 780 tokens per session (5 MCP tool schemas ≈ 626, skill and agent descriptions ≈ 154). One blocked 38k-token read pays for months of usage.

See bench/RESULTS.md for the generated benchmark report.

Platform Support

Zero Token natively supports both Google Antigravity 2.0 and ZCode through a unified adapter layer:

Components

Installation

Option 1: Fast Universal Install (PowerShell)

Clone the repository and run the installer script:

git clone https://github.com/kzxl/zero-token.git
cd zero-token
./install.ps1

The script automatically sets up NTFS Junctions pointing to plugins/zero-token for both environments:

• Antigravity 2.0: ~/.gemini/config/plugins/zero-token

• ZCode: ~/.zcode/plugins/zero-token

Option 2: ZCode Plugin Marketplace

In ZCode:

/plugin marketplace add kzxl/zero-token
/plugin install zero-token@zero-token

Or navigate to Plugin Marketplace → + → Add Plugin Marketplace, paste kzxl/zero-token, then install Zero Token.

Option 3: Antigravity 2.0 Manual MCP Registration

If you prefer registering Zero Token strictly as an MCP server in Antigravity:

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "zero-token": {
      "command": "node",
      "args": [
        "C:/Users/<Username>/source/repos/zero-token/plugins/zero-token/scripts/mcp-server.mjs"
      ],
      "env": {
        "ZERO_TOKEN_WORKSPACE": "C:/path/to/your/workspace"
      }
    }
  }
}

Language Support

Configuration

Zero Token supports a 3-tier configuration hierarchy:

1. Repository Overrides: <repo>/.zero-token.json (highest priority)

2. User Global Overrides: ~/.zero-token/config.json (or path in ZERO_TOKEN_CONFIG)

3. Plugin Defaults: plugins/zero-token/scripts/config.json

Savings Ledger & Real-Time Dashboard

Every blocked call, preserved token count, and MCP execution is recorded in:

• ~/.zero-token/ledger.jsonl (customizable via ZERO_TOKEN_DATA).

To inspect savings:

• In chat: Run /zero-token status or /saved [days] for a concise summary.

• In ZCode / MCP App hosts: Open ui://zero-token/panel.html in the sidebar for live metrics, visual gauges, and zero-token consumption.

Benchmarks & Verification

Run the test suite locally:

npm test                          # Full test suite: guard, languages, build parser, gitignore, runner, panel
npm run smoke                     # MCP protocol handshake and tool verification
npm run bench                     # Synthetic scenario benchmark (writes bench/RESULTS.md)
node bench/repo-bench.mjs         # Benchmark against real multi-language repositories
node bench/hook-bench.mjs         # Measure hook spawn overhead and ledger append latency

Hook latency on Windows is ~70 ms per guarded call (Node process spawn overhead); ledger appends take only 0.35 ms. A typical session with 50 tool calls incurs ~3.5 seconds of total hook latency while saving tens of thousands of tokens.

Safety & Security

• Zero Token runs entirely locally. Nothing leaves your machine.

• The guard denies dangerous calls; it never auto-approves permissions. Your host environment's permission boundaries remain in full control.

• MCP tools are read-only inspection tools, except build and run which execute existing local build scripts with bounded timeouts.

License

MIT © kzxl