agy-fast
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
agy-fast
Latency, Token-Quota & Tool-Call Accelerator Plugin for Google Antigravity
English · 简体中文 · Quick Start · Benchmarks · MCP Tools · Analysis Report · Changelog
agy-fast is a zero-dependency, policy-compliant local MCP plugin for Google Antigravity (CLI agy, Desktop 2.0, and IDE). It cuts agent wall-clock latency, billable token quota, and upload traffic by consolidating high-frequency searches, multi-language symbol outlines, atomic multi-file edits, and build/test checks into batched local calls—and injecting a sub-50 ms workspace snapshot once per session—without altering Antigravity's native UI, diff viewer, modified-files list, checkpoints, or safety checks.
LLM Turns / 10 Actions | Est. Billable Quota | Tool-Return Upload | Spills & Native UI Impact |
-33.7% | -31.5% | -39.7% | 0 |
Quick Start
Requirements: Node.js >= 20 (no npm install needed — pre-built, unminified zero-dependency ESM bundles are included in dist/). Optional: ripgrep (rg) for faster code search (automatically falls back to pure Node.js when absent).
One-Command Install (Recommended)
Installs runtime files to ~/.gemini/config/plugins/agy-fast, runs agy plugin validate --strict and agy plugin enable agy-fast when agy is installed, and verifies both the MCP server and SessionStart hook live:
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/INK-Q/agy-fast/main/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/INK-Q/agy-fast/main/install.ps1 | iexActivating in Desktop 2.0 / IDE: Open Customizations → Installed in Antigravity, confirm agy-fast is enabled, and start a new session to load the SessionStart hook and MCP tools.
Local Clone (Any OS)
git clone https://github.com/INK-Q/agy-fast.git
cd agy-fast
node scripts/install.mjs installDirect Clone into Antigravity Plugins Directory (No Script Needed)
Antigravity automatically discovers plugins placed in ~/.gemini/config/plugins/:
# macOS / Linux
git clone https://github.com/INK-Q/agy-fast.git ~/.gemini/config/plugins/agy-fast# Windows (PowerShell)
git clone https://github.com/INK-Q/agy-fast.git "$env:USERPROFILE\.gemini\config\plugins\agy-fast"Native Antigravity CLI (agy)
agy plugin install /path/to/agy-fast
agy plugin enable agy-fastPer-Repository Installation (Team Sharing)
Install only for a single repository (writes to <repo>/.agents/plugins/agy-fast):
node scripts/install.mjs install --project /path/to/your-repoAsk Antigravity Directly
Paste this prompt into Antigravity:
Clone https://github.com/INK-Q/agy-fast.git to ~/.gemini/config/plugins/agy-fast, run `node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs doctor`, and enable the agy-fast plugin.Related MCP server: Delta-MCP
How It Works
Empirical analysis of 55 real Antigravity sessions (8,446 LLM turns, 17,302 tool calls, 55.25 hours of single-agent active time; see docs/ANALYSIS_REPORT.md) revealed that slow tasks are rarely limited by token generation speed. Instead, four structural bottlenecks dominate wall-clock time:
Measured Bottleneck | Empirical Cost | How |
Per-turn TTFT floor |
| Batches an average of 4.89 logical actions per MCP call ( |
Serial checks & fragmented ops |
| Consolidates up to 20 searches, 50 file edits + |
Cold-start exploration | First 3 turns average 49.2 seconds inspecting directory layout, git state, and scripts |
|
Context bloat & cache decay |
| Symbol outlines first + parallel targeted |
Hybrid Execution Architecture
agy-fast never replaces fast native reads. It combines batched local MCP tools with Antigravity's locally allowlisted read_file (~7 ms, 46 KB/call inline, zero remote check):
Plugin Components
Component | Path | Role |
Plugin Manifest | Standard Antigravity manifest; passes | |
Local Stdio MCP Server | Persistent local process exposing 5 eagerly loaded composite tools ( | |
Startup Snapshot Hook | Runs once on | |
Routing & Hygiene Rules | Compact ( | |
Background Auto-Updater | Detached 12 h release checker with staged MCP smoke verification | |
Offline Benchmark CLI | Local |
Real-World Benchmarks
Across 10 days of sanitized real coding transcripts (14 baseline main sessions / 5,771 turns vs. 7 agy-fast main sessions / 901 turns, plus 104 baseline vs. 4 agy-fast subagent sessions; all repository names, paths, and identifiers stripped), each agy-fast call batched an average of 4.89 logical operations (5.95× in subagents):
Metric (normalized per logical action) | Main Sessions (Baseline) | Main Sessions ( | Delta |
| Subagents |
LLM turns / 10 actions | 5.23 | 3.47 | -33.7% | -38.2% | -58.8% |
Upstream requests / 10 actions (LLM + remote checks) | 9.82 | 6.05 | -38.4% | -42.6% | -62.0% |
Prompt Cache hit rate (miss spikes) | 89.6% (7.5%) | 94.0% (4.8%) | +4.4 pp | 95.0% (3.3%) | 92.4% (2.8%) |
Uncached fresh input / action | 10,413 tok | 4,822 tok | -53.7% | -61.5% | -51.3% |
Est. billable quota / action (1 : 0.1 : 5) | 22,458 eq | 15,387 eq | -31.5% | -36.5% | -54.0% |
Tool-return upload / action (actual local bytes) | 5.06 KB | 3.05 KB | -39.7% | -42.6% | -13.3% |
Incremental text upload / action (fresh input est.) | 35.6 KB | 16.5 KB | -53.7% | -61.6% | -51.3% |
Full-context text upload / action (stateless resend est.) | 342.2 KB | 276.2 KB | -19.3% | -21.9% | -58.9% |
Production hardening highlights (v0.2.x):
0 disk spills across 134 consecutive
v0.2.xMCP calls — strict≤8.8 KBUTF-8 inline cap prevents Antigravity'soutput.txtspill-to-disk extra turns.+75% effective throughput (
35.1 → 61.5 tok/s) and>60sstall turns reduced from31.2% → 7.4%in a same-session before/afterv0.2.1comparison (99 vs. 374 turns) once multimodal screenshots were isolated out of>180k-token main sessions (0screenshots loaded in main coding sessions post-upgrade).0 lazy-load schema-read turns — compact schemas are inlined directly in
rules/AGENTS.md.
Logical action normalization: One
batch_searchwith 5 queries counts as 5 actions, oneapply_editstouching 6 hunks +verifycounts as 7 actions, and one built-inread_file/edit_file/run_commandcounts as 1 action—ensuring apples-to-apples comparison per unit of work rather than raw tool-call counts.Quota weighting sensitivity: Standard weighting (
1.0×uncached input,0.1×cache read,5.0×output) yields -31.5% on main sessions (-36.5% on≥150ksessions). Results hold under conservative cache discounts (1 : 0.25 : 4→ -25.8%) and high-output weighting (1 : 0.1 : 8→ -29.4%).Fixed prompt overhead:
rules/AGENTS.md+SessionStartsnapshot add ~1.7k tokens once per session (cached from turn 2 onward,~170eq tokens/turn). Avoiding a single redundant turn (~44keq tokens) or blind full-file read pays back this overhead >20×.
Verify on Your Own Transcripts (100% Offline)
Measure your own Antigravity sessions locally — nothing ever leaves your machine:
# Summarize all local Antigravity transcripts
node dist/benchmark.mjs analyze --local
# Analyze only the 10 most recently modified local transcripts
node dist/benchmark.mjs analyze --local --recent 10
# Slice sessions since install time and compare With vs. Without agy-fast
node dist/benchmark.mjs analyze --local --since 2026-11-19T12:51:00+08:00 --split-usage
# Compare two task runs (before vs. after)
node dist/benchmark.mjs compare --before ./run-before/transcript.jsonl --after ./run-after/transcript.jsonlThe 5 MCP Tools
Scenario | Preferred Tool | Why |
Run ≥2 text, regex, glob, fuzzy, or read-only git queries |
| 1 call for up to 20 concurrent queries ( |
Map unknown large files ( |
| Flat |
Read small files ( | Built-in | Locally allowlisted ( |
Edit ≥2 hunks/files in one turn, or edit + verify |
| Atomic or |
Run ≥2 independent build, lint, test, or diagnostic commands |
| Concurrent execution with head-tail folded error-focused output |
1. batch_search — Concurrent Code, Path & Read-Only Git Search
Up to 20 mixed queries per call:
text,regex,glob,fuzzy, and read-onlygit(status,diff,log,show,branch,rev-parse,ls-files,blame,shortlog,describe,tag --list,remote -v), including cross-repo lookups via per-querypath.Precision controls: Filter by
fileType(e.g.,typescript,python,gdscript) orglob, switchoutputMode(content|files_with_matches|count), enable cross-linemultiline: true(wherecountreports occurrences per file), usetype: "fuzzy"for case-insensitive path matching, or passsortBy: "mtime"onglobqueries for newest-first results.Resilient & inline-safe: Uses
rgwhen installed with automatic Node.js fallback, auto-recovers common LLMglobmistakes (|alternation and bare keywords), and enforces the≤8.8 KBUTF-8 cap.
2. apply_edits — Atomic Multi-Hunk & Multi-File Edits + Verify
Up to 50 files per call: Validates every hunk and overlap in memory before touching disk (
0files modified on error), or passbestEffort: trueon larger batches so valid files commit atomically per file while failed files return closest-line / drifted-line snippets for targeted retry.Faithful file handling: Preserves CRLF line endings, file permissions, and symlinks; supports
startLine/endLine,replaceAll,create/overwrite, anddryRun.Inline
verify: Optionally runs a build/typecheck/test command right after writing, stripping noisy logs (e.g., Pino/Bunyan info JSON, Maven footers) so root causes stay within budget.
3. quick_outline — Flat Multi-Language Symbol Outlines
Up to 40 files per call (10–20 recommended per batch): Takes a flat
paths: string[]array to extract exact[startLine, endLine]symbol/section maps for TypeScript / JavaScript (incl. Fastify/Express routes & test blocks), HTML / Vue / Svelte, CSS / SCSS / Less, Python, Godot GDScript (.gd), Go, Rust, Java / Kotlin / C# / Swift / C / C++, Shell, Markdown, and JSON / YAML—making outline-first exploration effortless before parallel built-inread_file.
4. read_slices — Symbol Outlines + Targeted Line Slices
Outlines + piggybacked slices: Supports the same 15-format outlines (with breadth-first water-filling per file) plus optional tiny
[startLine, endLine]slices in one call under the≤8.8 KBUTF-8 budget, while steering bulk range reads (>150lines) to parallel built-inread_file.
5. run_checks — Concurrent Build, Lint, Test & Diagnostic Runner
Up to 12 commands per call: Executes independent non-interactive shell commands in a bounded worker pool (
concurrency: 1..8) with per-command timeouts (1..170 s, sharing a170 scall budget under Antigravity's180 sMCP limit), ANSI escape stripping, and transparent Windows unwrapping of trivialpowershell -Command "..."wrappers around allowlisted binaries (git,npm,node,rg,pytest,cargo, etc.) to skip PowerShell cold-start overhead while leaving PowerShell cmdlets/aliases untouched.Head-Tail adaptive output modes:
compact(default) collapses passing commands to 1-line summaries and uses Head-Tail folding on large failures so both initial root-cause errors and final summary/stack tails survive the≤8.8 KBinline cap;fullpreserves stdout for diagnostic or audit scripts with Head-Tail folding when capped.
batch_search — 3 heterogeneous queries in one call:
{
"queries": [
{ "type": "regex", "pattern": "export (async )?function", "fileType": "typescript", "outputMode": "files_with_matches" },
{ "type": "fuzzy", "pattern": "mcp server" },
{ "type": "git", "pattern": "status --short" }
]
}apply_edits — Multi-file edit + inline typecheck in one call:
{
"edits": [
{ "path": "src/a.ts", "hunks": [{ "target": "oldCall()", "replacement": "newCall()" }] },
{ "path": "src/b.ts", "hunks": [{ "target": "v1", "replacement": "v2", "startLine": 10, "endLine": 25 }] }
],
"bestEffort": true,
"verify": "npm run typecheck"
}Updates, Diagnostics, and Uninstall
Day-to-Day CLI Reference
Task | Command |
Health check (Node, |
|
Check for updates (read-only) |
|
Update now (stages & runs MCP smoke test before swapping) |
|
Configure auto-update ( |
|
Uninstall cleanly |
|
From a local repository clone,
./install.sh <command>(macOS/Linux) and.\install.ps1 <command>(Windows) accept the same subcommands (doctor,update,config,uninstall).
Zero-Latency Background Auto-Updater
0 ms session startup cost: Every 12 hours,
SessionStartspawns a detached background process (dist/updater.mjs) after emitting the workspace snapshot.Verified before swap: Checks GitHub release tags (
git ls-remote --tagswith GitHub Releases API fallback), clones into an isolated staging directory, runs a live MCP smoke test, and atomically replaces runtime files—automatically rejecting broken releases while preserving any user-createdrules/AGENTS.local.md(add---\ntrigger: always_on\n---YAML frontmatter so Antigravity loads it; gitignored forgit cloneinstalls).Safe by design: Standard copied installs and clean direct
git cloneinstalls auto-update automatically;--linkdev symlinks and dirty git repos are never overwritten (notify-only). A one-time notice appears in the next new session when an update is applied or available.
Environment Variable | Values / Default | Purpose |
|
| Overrides saved auto-update mode |
|
| Background check interval in hours |
|
| Track stable semver release tags or |
| Git URL | Use a custom mirror or fork |
|
| Controls |
| e.g. | Overrides auto-detected Antigravity host surface & version |
Applying updates: Updated rules/AGENTS.md and dist/session-start.mjs take effect automatically on the next new session. In Antigravity Desktop 2.0 / IDE, reload or restart the window once to refresh the resident MCP server process.
Policy Compliance and Safety
Official interfaces only: Built exclusively on documented Antigravity extension APIs (
plugin.json,mcp_config.json,hooks.json,rules/AGENTS.md).Non-invasive by design: Never alters or interferes with Antigravity's native UI, diff viewer/window, modified-files list, checkpoints, or built-in tools.
No safety or binary tampering: Does not patch client binaries, alter authentication, or bypass Antigravity's built-in safety evaluations.
Zero per-step blocking hooks: Registers no
PreToolUse,PostToolUse,PreInvocation,PostInvocation, orStophooks.Fail-open startup hook: On unreadable directories or malformed stdin,
SessionStartreturns{}and exits cleanly—never blocking a session.Local-first & auditable: All 5 MCP tools and the benchmark CLI run 100% locally with zero code or transcript uploads; shipped
dist/*.mjsbundles are unminified ESM so every executed line is directly auditable.
FAQ
Does agy-fast affect Antigravity's native UI, diff viewer, or modified-files list?
No. agy-fast runs strictly as a standard local Stdio MCP plugin with a SessionStart hook. It never patches the Antigravity client or interferes with the native diff viewer/window, modified-files list, checkpoints, built-in tools, or safety checks.
Does agy-fast save token quota and upload bandwidth in addition to reducing latency?
Yes. Across 10 days of sanitized real coding transcripts, batching ~4.9 operations per MCP call reduced LLM turns by 33.7%, estimated billable token quota by 31.5% (36.5% in ≥150k-token sessions; 54.0% in subagents), tool-return upload bytes by 39.7%, and >60s stall turns from 31.2% → 7.4%.
Does agy-fast replace Antigravity's built-in read_file or edit_file tools?
No — it complements them in a hybrid workflow. Built-in read_file is locally allowlisted (~7 ms, 46 KB/call, zero remote check), so agy-fast routes small files and known line ranges straight to parallel built-in read_file, while handling multi-query searches, symbol outlines, multi-hunk/multi-file edits with inline verify, and concurrent checks via MCP.
Which Antigravity editions and operating systems are supported?
agy-fast supports Antigravity CLI (agy), Antigravity Desktop 2.0, and Antigravity IDE across macOS, Linux, and Windows. It requires Node.js >= 20 with zero runtime dependencies (optional ripgrep/rg with automatic pure-Node.js fallback).
Does agy-fast send any code or transcript data to external servers?
No. All MCP tools, the SessionStart snapshot hook, and the transcript benchmark CLI operate 100% locally. The only optional network request is the background update checker checking public GitHub release tags once every 12 hours, which can be switched to notify or disabled completely via config --auto-update off or AGY_FAST_AUTO_UPDATE=off.
How do I verify the speedup or uninstall agy-fast cleanly?
Run node dist/benchmark.mjs analyze --local --split-usage to benchmark your own local transcripts completely offline. To remove agy-fast at any time, run node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs uninstall.
Development
npm install
npm run typecheck # Strict TypeScript check
npm run build # Bundle src/*.ts -> dist/*.mjs with esbuild
npm test # Run unit, MCP protocol, hook, benchmark, and installer tests
npm run bench:stress # Run 12-scenario end-to-end stress & performance benchmark
npm run validate # Run `agy plugin validate --strict .`Star History
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Multiple MCP tools, persistent graph memory, token-saving data pointers, and more.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
Related MCP Servers
- AlicenseBqualityBmaintenanceAgent-optimized MCP server that replaces built-in file, search, exec, and git tools with compact, structured JSON equivalents. Benchmarked 20–45% token savings for AI coding agents.203MIT
- AlicenseNot gradedqualityCmaintenanceToken-efficient MCP reimplementation with progressive tool discovery, result handling, and compact wire encoding, reducing token usage by up to 89% on tool definitions.1MIT
- AlicenseNot gradedqualityDmaintenanceToken-optimized MCP server that reduces context window usage by 59.5% by grouping 12 tools into 5 semantic operations, preserving all original functionality for AI assistants.14 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables local AI agents to generate code and interact with Google Antigravity (Gemini Pro) via MCP, consuming zero API tokens.-