GravityGuard

GravityGuard checks supported structured file operations before execution, including secret leaks, test tampering and silent exception handlers. Deterministic guardrails for Claude Code and Antigravity IDE. No LLM in the rule engine, ~0.1 ms core evaluation in development benchmarks; external hook startup adds host-dependent latency.

Animated demo · Security boundaries and hardening status

English | Türkçe

git clone https://github.com/halilogia/GravityGuard.git

Add the hook from plugin/claude-code/settings.example.json to your Claude Code settings.json (replace <GRAVITYGUARD> with the clone path). Requires only Python 3.10+. Details: plugin/claude-code/README.md.

What it blocks: leaked secrets (OpenAI, Anthropic, Gemini, Slack, GitHub, private keys) · silenced or deleted tests · silent except: pass · layer-boundary violations · god-files. Full list in the rule matrix.

GravityGuard is an ultra-lightweight, deterministic architectural gatekeeper, secret airbag, and prompt engineering companion built specifically for Antigravity IDE and modern autonomous AI coding agents. In development benchmarks, it intercepts AI agent tool-calls with an average in-memory logic execution of ~0.1ms (p95 < 0.5ms), preventing codebase degradation, accidental credential leaks, architectural violations, and silent error masking without adding synchronous developer friction. Absolute latency is host- and load-dependent; the number that is held stable is the ratio against the previous release, measured interleaved in the same time slice.

Design philosophy — trust the mechanism, not the model. GravityGuard exists because an AI agent's goodwill cannot be relied upon: a rule that lives only as prose is a wish. Every obligation is therefore backed either by an artifact the agent must actually write to disk, or — wherever it can be made deterministic — by an airbag, linter or hook that refuses the operation outright. No initiative, no "trust me"; the gate stays shut until the artifact exists.

GravityGuard operates an ordered, zero-overhead pipeline before any file modification tool call is executed:

• High-Confidence Airbags: Pure in-memory diff evaluation: avg ~0.1ms, p95 <0.5ms (zero subprocess). Running the engine as a Windows subprocess costs a real python.exe spawn — measured at a median of ~340–370 ms on this host, and host-dependent — which is why all linting and compiling happens in a hidden background worker (CREATE_NO_WINDOW + SW_HIDE, so no console window ever flashes on screen) and the synchronous path stays in-memory.
• Intelligent Scale Heuristics: Distinguishes cohesive single-responsibility files from unmaintainable god-files without relying on arbitrary mechanical line-count blocking.
• Zero Heavy Dependencies: Pure standard-library Python validator operating via shallow AST and regex heuristics. Zero compilation overhead.

• Interactive Status Bar Item: Click $(sparkle) Prompt Geliştir on the bottom right or press Ctrl + Alt + E (Cmd + Alt + E on macOS) anywhere in the IDE.
• Active Selection Aware: Automatically detects text highlighted in your active editor or prompts via a clean modal input box.
• Local Intent Classifier (no LLM): Every request is classified locally, in under a millisecond, into İSTİŞARE (brainstorm), UYGULAMA (build) or DENETİM / REFACTOR (audit). Only the selected mode's directive is sent, so the model no longer has to guess what was asked. Override the decision with a #denetle:, #danış: or #kodla: prefix. When the classifier is not confident it asks instead of guessing, and a 32-prompt hand-labelled corpus keeps the signals honest across every change.
• Local AI Accelerated: Talks to any OpenAI-compatible local gateway (9Router, Ollama, LM Studio, llama.cpp) over http://127.0.0.1:20128, with a configurable model cascade and automatic failover. A gateway that is not running is detected immediately instead of being retried per model, and the enhancer then falls back to a deterministic offline brief — the command never fails because a local service is down.
• Direct Clipboard Integration: The enhanced prompt is automatically copied to your system clipboard. Simply press Ctrl + V in the chat panel to instruct the AI with a defensive, production-ready specification.
• Review in Document: Includes an optional "Yeni Belgede Aç" (Open in New Document) button to inspect or tweak the enhanced prompt before execution.

• Dedicated Sidebar Panel: Access the GravityGuard dashboard directly from the Activity Bar using the custom shield icon.
• Live Event Stream: Real-time visual cards displaying file paths, actions, verdicts, timestamps, and actionable architectural reasons.
• Live Statistics: Visual badges tracking Engellenen (Blocked) vs. Onaylanan (Approved) operations.
• Dual-Mode Auto Sync: Seamlessly blends OS filesystem events (fs.watch) with a 1.5-second polling heartbeat to ensure zero dropped logs.
• One-Click Maintenance: Instant "Yenile" (Refresh) and "Temizle" (Purge Logs) controls.

• Prefer staying in the chat window? Simply type /enhance <your instruction> directly into the Antigravity chat box.
• The built-in GravityGuard skill immediately processes your request without opening external windows.

1. Clone or copy the repository into your Antigravity / VS Code extensions directory:

   git clone https://github.com/halilogia/GravityGuard.git "C:\Users\<User>\.antigravity-ide\extensions\gravityguard"

2. Open the directory in a terminal and install build dependencies:

   cd "C:\Users\<User>\.antigravity-ide\extensions\gravityguard"
   npm install
   npm run build

3. In Antigravity IDE, press Ctrl + Shift + P and select Developer: Reload Window.

1. Press Ctrl + Alt + E (or click ✨ Prompt Geliştir on the Status Bar).
2. Enter your raw instruction (e.g. "Add player inventory websocket sync").
   Prefix it with #denetle: / #danış: / #kodla: to pin the mode yourself.
3. The request is classified locally (no network) and the enhanced defensive
   specification is copied to your clipboard — in seconds with a local gateway,
   instantly in offline template mode.
4. Go to Antigravity Chat, press Ctrl + V, and submit!

The same engine guards Claude Code through a thin adapter in plugin/claude-code/: Write / Edit / MultiEdit go through the file rules, and the Stop hook holds a session until its own test/doc obligations are met. Each session is tracked separately, so parallel sessions never block each other. Bash writes are not inspected. Setup is one settings.json snippet.

Agents cannot write .claude/settings.json or .agents/hooks.json. When you complain about a repeating mistake, the agent writes a proposal to .gravityguard/proposals/hooks/<id>.json; you review the diff in the Hooks tab and click Approve (or run gravityguard hooks approve <id> in your own terminal). Every decision is receipted and gravityguard hooks revert <id> undoes an install. Details: docs/operations/hook-proposals.md.

Hooks stay fast (<5 ms, no LLM, no network). Deep checks live in a separate on-demand command that emits evidence-backed findings as SARIF v2.1.0:

python engine/governance_control.py scan                # changed files, writes .gravityguard/reports/security-scan.sarif
python engine/governance_control.py scan --all --format text

Flags: --diff (default) / --all, --format sarif|json|text, --output <path>. Exit code 1 when findings exist. Details: docs/architecture/04-dual-speed-security.md.

Tasarım felsefesi — modele değil, mekanizmaya güven. GravityGuard, bir yapay zeka ajanının iyi niyetine güvenilemeyeceği için vardır: yalnızca metin olarak yaşayan bir kural, bir dilektir. Bu yüzden her yükümlülük ya ajanın gerçekten diske yazmak zorunda olduğu bir artefakta, ya da — deterministik kılınabildiği her yerde — işlemi doğrudan reddeden bir hava yastığına, linter'a veya kancaya (hook) dayanır. İnisiyatif yok, "bana güven" yok; artefakt oluşana kadar kapı kapalı kalır.

GravityGuard, herhangi bir dosya değiştirme aracı çalıştırılmadan önce sıfır gecikmeli sıralı bir denetim hattı işletir:

• Yüksek Güvenilirlikli Hava Yastığı: Saf bellek içi mantık denetimlerini ortalama ~0.1 ms (p95 < 0.5 ms) sürede tamamlar (alt süreç yok). Motoru Windows alt süreç olarak çalıştırmak gerçek bir python.exe doğurma maliyeti demek — bu makinede medyan ~340–370 ms ölçüldü ve makineye bağlıdır — bu yüzden tüm lint/derleme işi gizli bir arka plan işçisinde çalışır (CREATE_NO_WINDOW + SW_HIDE, ekranda hiç konsol penceresi açılmaz) ve senkron yol bellek içi kalır.
• Akıllı Ölçek Analizi: Yapay zekanın tek dosyaya aşırı sorumluluk yığarak devasa "god-file" oluşturmasını önler. Mekanik satır sınırı koymak yerine semantik sorumluluk dağılımına bakar.
• Sıfır Harici Bağımlılık: Saf Python ile yazılmış, AST ve regex tabanlı hafif analiz motoru. Ağır kütüphane veya derleme gerektirmez.

• Status Bar Erişimi: Sağ alttaki ✨ Prompt Geliştir butonuna tıklayın veya dilediğiniz an Ctrl + Alt + E kısayolunu kullanın.
• Seçili Metin Algılama: Editörde fareyle seçtiğiniz kodu/yorumu otomatik olarak algılar; seçim yoksa şık bir girdi kutusu açar.
• Yerel Niyet Sınıflandırıcı (LLM'siz): Her istek yerelde, 1 milisaniyenin altında İSTİŞARE, UYGULAMA veya DENETİM / REFACTOR modlarından birine sınıflandırılır. Modele yalnızca seçilen modun direktifi gönderilir; böylece model ne istendiğini kendisi tahmin etmez. Kararı #denetle:, #danış: veya #kodla: önekiyle siz geçersiz kılabilirsiniz. Sınıflandırıcı emin değilse tahmin etmez, soruyor (tek tıkla seçim, tahmin varsayılan); 32 maddelik elle etiketlenmiş korpus ise her değişiklikte sinyallerin doğru kaldığını garanti eder.
• Yerel Yapay Zeka Hızı: 9Router, Ollama, LM Studio veya llama.cpp gibi herhangi bir OpenAI uyumlu yerel ağ geçidiyle (127.0.0.1:20128) çalışır; model kademeleri ayarlanabilir, hata durumunda otomatik yedek modele geçilir. Geçid kapalıysa bu durum model modeline kadar yeniden denemeden anlaşılır ve geliştirici, yerel hizmet kapalıyken de komutun çalışmaya devam etmesini sağlayan belirlenimci (deterministik) çevrimdışı şablon moduna düşer.
• Doğrudan Panoya Kopyalama: Geliştirilen mimari şartname doğrudan Windows/macOS panonuza kopyalanır (Ctrl+C yapılmış gibi). Chat kutusuna gidip Ctrl + V yapmanız yeterlidir.
• Ayrı Belgede İnceleme: İsterseniz gelen bildirimdeki "Yeni Belgede Aç" butonuna basarak oluşturulan promptu ayrı bir sekmede düzenleyebilirsiniz.

• Özel Kenar Çubuğu Paneli: Sol Activity Bar üzerindeki kalkan simgesine tıklayarak canlı denetim paneline erişin.
• Gerçek Zamanlı Günlük Akışı: Engellenen ve onaylanan tüm dosya hareketleri, gerekçeleri ve zaman damgalarıyla anlık listelenir.
• Canlı İstatistikler: Engellenen ve onaylanan işlemleri sayan görsel sayaç kartları.
• Çift Modlu Canlı Senkronizasyon: Dosya izleyici (fs.watch) ile 1.5 saniyelik aktif heartbeat mekanizmasını birleştirerek hiçbir günlüğü kaçırmaz.
• Tek Tıkla Temizleme: "Yenile" ve "Temizle" butonlarıyla günlükleri anında sıfırlayabilme.

• Harici kutucuk açmak istemeyenler için: Doğrudan Antigravity Chat kutusuna /enhance <isteğiniz> yazarak sohbet penceresi içinden de prompt geliştirebilirsiniz.

• Aynı motor, plugin/claude-code/ altındaki ince bir adaptörle Claude Code'u da korur: Write / Edit / MultiEdit dosya kurallarından geçer, Stop kancası oturumu kendi test/doküman yükümlülükleri bitene kadar tutar. Her oturum ayrı izlenir; paralel oturumlar birbirini engellemez. Bash ile yazılan dosyalar denetlenmez. Kurulum tek bir settings.json parçasıdır.

Ajan .claude/settings.json ya da .agents/hooks.json dosyasına yazamaz. Tekrarlayan bir hatadan yakındığınızda ajan .gravityguard/proposals/hooks/<id>.json önerisi yazar; Kancalar sekmesinde farkı görüp Onayla ve kur'a basarsınız (ya da kendi terminalinizde gravityguard hooks approve <id>). Her karar kayda geçer; gravityguard hooks revert <id> kurulumu geri alır. Ayrıntı: docs/operations/hook-proposals.md.

Hook'lar hızlı kalır (<5 ms, LLM/ağ yok). Derin kontroller ayrı, isteğe bağlı bir komuttadır ve kanıtlı bulguları SARIF v2.1.0 olarak üretir:

python engine/governance_control.py scan                # değişen dosyalar -> .gravityguard/reports/security-scan.sarif
python engine/governance_control.py scan --all --format text

Bayraklar: --diff (varsayılan) / --all, --format sarif|json|text, --output <yol>. Bulgu varsa çıkış kodu 1. Ayrıntı: docs/architecture/04-dual-speed-security.md.

Bu depo, standart mühendislik prensiplerine tam uyumlu dokümantasyon seti içerir:

Bu proje GNU General Public License v3.0 kapsamında lisanslanmıştır.

• DESIGN.md — Görsel tasarım sistemi ve bileşen spesifikasyonu