⚡ Aevum Kyber (@lugubo/aevum-kyber)

The Ultimate AI Coding Agent Governance & Rate-Limit Harness
Sub-millisecond AST Knowledge Graph MCP Server (99.98% token reduction), sliding-window rate-limit quota guard, deterministic TDD quality gates, and cross-ecosystem agent governance.

---

---

💡 Why Aevum Kyber?

Autonomous AI coding agents (Claude Code, Cursor, Windsurf, Gemini CLI, Copilot Workspace) are transforming software engineering. However, in real-world production repositories, unmanaged agents suffer from four major points of failure:

1. Context Window Bloat & High Token Costs: Blind file reading and greedy recursive grep scans burn hundreds of thousands of tokens per prompt, diluting LLM attention and racking up large API bills.
2. HTTP 429 Rate-Limit Crashes: Agentic loops sending rapid bursts of complex requests quickly exhaust provider RPM/RPD limits (e.g. Gemini 3.1 Pro 2 RPM / 50 RPD limit), crashing the session.
3. Untested Hallucinations & Regressions: Agents frequently modify production code without writing tests, introducing regressions into the codebase.
4. Context Amnesia & Vendor Lock-in: Ephemeral chat sessions lose memory, while proprietary agent databases lock you into closed platforms.

Aevum Kyber solves all four challenges in a single, high-performance, modular harness.

---

📊 Empirical Head-to-Head Benchmark Results

In rigorous A/B stress testing (scripts/benchmark_head_to_head.js), Aevum Kyber demonstrated overwhelming superiority over standard unmanaged agents:

Metric	Without Kyber (Baseline)	With Aevum Kyber v2.2	Advantage
Context Payload Size	1,129.38 KB	0.21 KB	99.98% payload reduction
Prompt Tokens Consumed	289,121 tokens	55 tokens	5,256.7x token savings
AST Query IPC Latency	15 - 80 ms (Disk I/O)	0.189 ms	Sub-millisecond Stdio IPC
API 429 Rate-Limit Rate	Frequent (~80% in bursts)	0% (Zero 429 errors)	Sliding window auto-routing & fallback
TDD Code Verification	Unverified / Blind Commits	100% Deterministic Gate	Pre-commit test-pairing enforcement

Reproduce the benchmark anytime on your machine:

node scripts/benchmark_head_to_head.js

---

🧩 The 4 Modular Pillars (Opt-in Architecture)

Aevum Kyber is completely modular. Install only what your project needs:

                                  ┌────────────────────────┐
                                  │      AEVUM KYBER       │
                                  └───────────┬────────────┘
         ┌──────────────────┬─────────────────┼──────────────────┬──────────────────┐
         ▼                  ▼                 ▼                  ▼                  ▼
┌──────────────────┐ ┌──────────────┐ ┌───────────────┐ ┌──────────────────┐ ┌──────────────────┐
│   PILLAR 1:      │ │  PILLAR 2:   │ │  PILLAR 3:    │ │   PILLAR 4:      │ │   CROSS-BRIDGE:  │
│   AST MCP SERVER │ │  QUOTA GUARD │ │  TDD GATES    │ │   BMAD MEMORY    │ │   GEMINI ↔ CLAUDE│
│ (0.2ms Stdio IPC)│ │ (0% 429 24h) │ │ (100% Tested) │ │ (Markdown State) │ │ (Universal IDE)│
└──────────────────┘ └──────────────┘ └───────────────┘ └──────────────────┘ └──────────────────┘

1. ⚡ AST Knowledge Graph MCP Server

Standard Model Context Protocol (MCP) server providing 19 high-performance Stdio tools (graphify_get_deps, graphify_get_subgraph, graphify_get_god_nodes, hardware_status, secrets_scan). Lets AI agents query AST dependency trees in 0.18 ms instead of scanning thousands of lines of raw code.

2. 🛡️ Sliding-Window Quota Guard & Telemetry Dashboard

Continuous rate-limit protection for Google Gemini and frontier models. Features a 1-10 Task Weight Classifier with dynamic fallback routing (routes lightweight tasks to Gemini 3.1 Flash Lite with 500 RPD budget, reserving Gemini 3.1 Pro Thinking for heavy architectural work). Includes a sleek dark-mode local web dashboard (kyber quota dashboard).

3. 🧪 Deterministic TDD Quality Gates

A pre-commit verification engine (tdd-gate.js) that blocks untested commits at the Git level. Enforces test pairing across Python (test_*.py), TypeScript/JavaScript (*.test.ts, *.spec.js), Go, and Rust.

4. 🧠 BMAD Subagents Governance & Persistent Memory

Clean-room persona handoffs (PM, Architect, Developer, QA Engineer) operating on disk-persisted Markdown state contracts (PLAN.md, SPEC.md, walkthrough.md, 00_docs/). Eliminates context drift and sycophancy.

---

🌉 The Cross-Ecosystem Bridge (Gemini ↔ Claude ↔ Cursor)

Born and battle-tested in the Google Gemini & Antigravity IDE ecosystem and built on Anthropic's open Model Context Protocol (MCP), Aevum Kyber bridges high-throughput Gemini rate-limits with standard agentic IDEs:

• Google Gemini & Antigravity IDE: Ultra-low token pricing (Gemini 3.1 Flash Lite), massive context caching alignment (GEMINI.md static layout), and local GCP project quota tracking.
• Anthropic Claude Code & Cursor: Universal Stdio JSON-RPC 2.0 protocol, .cursor/mcp.json, and autonomous terminal workflows.
• Open Ecosystem: 100% portable on Windows, Linux, and macOS.

---

📝 Markdown-Driven Architecture (Executable Agent Memory)

In Aevum Kyber, Markdown is not just documentation — it is executable agent memory and deterministic state coordination:

• Zero Vendor Lock-in: No proprietary binary databases or hidden cloud lock-in. Everything resides in human-readable .md files.
• Context Caching Optimized: Structured rules (GEMINI.md, AGENTS.md) use fixed layouts to maximize prompt cache hits.
• Single Source of Truth: Specifications (00_docs/01_prd/), ADRs (00_docs/04_adrs/), and delivery reports (walkthrough.md) form verifiable contracts between humans and AI agents.

---

🚀 1-Minute Quickstart

Initialize with Modular Presets (Choose what you need)

# Option A: Quota Guard & Local Dashboard only
npx -y @lugubo/aevum-kyber init --preset=quota

# Option B: AST Knowledge Graph MCP Server only (Cursor / Claude / VSCode)
npx -y @lugubo/aevum-kyber init --preset=mcp

# Option C: Deterministic TDD Pre-Commit Gate only
npx -y @lugubo/aevum-kyber init --preset=tdd

# Option D: Full BMAD Agent Governance Suite
npx -y @lugubo/aevum-kyber init --preset=full

---

IDE Integrations

🟣 Cursor & Windsurf

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "aevum-kyber": {
      "command": "npx",
      "args": ["-y", "@lugubo/aevum-kyber", "mcp"]
    }
  }
}

🟠 Claude Code (Anthropic CLI)

Run in your terminal:

claude mcp add aevum-kyber -- npx -y @lugubo/aevum-kyber mcp

🔵 VS Code / Copilot

Add to .vscode/mcp.json:

{
  "mcpServers": {
    "aevum-kyber": {
      "command": "npx",
      "args": ["-y", "@lugubo/aevum-kyber", "mcp"]
    }
  }
}

---

💻 CLI Commands Reference

Once installed, use the global kyber command:

# Quota & Telemetry
kyber quota dashboard      # Launch real-time telemetry HTML dashboard in browser
kyber quota status         # Inspect active 60-second and 24-hour sliding windows
kyber quota estimate       # Estimate task weight (1-10) and recommended model tier

# MCP & Codebase Knowledge
kyber mcp                  # Start Stdio MCP Server (JSON-RPC 2.0)
kyber graphify             # Generate/update AST knowledge graph in background

# Governance & Quality Gates
kyber tdd                  # Execute pre-commit TDD code verification
kyber status               # Check BMAD persona states and validation flags
kyber doctor               # Run autodiagnostic environment health check

---

📄 License & Attribution

Distributed under the MIT License. See LICENSE for details.

MIT License

Copyright (c) 2026 LuGuBo (Aevum Dev Team)