Agent Guard

⚡ Instant Setup (One Command / One Prompt)

💻 One Terminal Command (Auto-Detects All Installed Coding Apps):

curl -fsSL https://raw.githubusercontent.com/anksarvesh-lgtm/agent-guard/main/install.sh | bash

*Auto-detects and configures Google Antigravity, Claude Code, Cursor, Codex CLI, Gemini CLI, Windsurf, VS Code (Cline/Roo), and Zed.*

🤖 Universal Agent Prompt (Copy & Paste to Any AI Agent):

"Please install and activate the Agent Guard MCP supervisor (https://github.com/anksarvesh-lgtm/agent-guard.git). Run curl -fsSL https://raw.githubusercontent.com/anksarvesh-lgtm/agent-guard/main/install.sh | bash in the terminal, verify with node ~/.agent-guard/dist/cli.js doctor, and adopt the @agent-guard rules to supervise all my development tasks with atomic ledger checkpoints and keep-awake protection."

Related MCP server: MCP GitHub Project Manager

Why Agent Guard?

Autonomous AI coding agents in modern IDEs like Google Antigravity excel at single-turn instructions, but frequently encounter catastrophic failure modes during extended, multi-step work:

1. Premature Abandonment: The agent declares victory and halts before running tests or finishing dependent steps.

2. Context Window Bloat & Cost Spikes: Repeatedly crawling deep file hierarchies and receiving thousands of redundant tokens in status output.

3. Session Amnesia: When a chat hits context limits or crashes, all task memory is lost and the agent restarts from scratch.

4. Unattended Sleep: Complex tasks stall midway because the computer's display or idle sleep kicks in while you step away.

5. Quota Exhaustion Mid-Execution: Automated pairing sessions fail abruptly when model quotas reach 0% or hit rate limit barriers.

Agent Guard (agent-guard) solves all five problems with zero external infrastructure:

• 💾 File-Backed Atomic DAG Ledger: Keeps track of every step in .agent/ledger.json with self-healing recovery and concurrency locking.

• 🛑 Antigravity Stop Hook: Soft-blocks premature termination until all tasks are complete, with an integrated loop breaker.

• ☕ Supervised Keep-Awake Lease: Keeps the computer awake using native OS tools (caffeinate / SetThreadExecutionState / systemd-inhibit) with an 8-hour safety ceiling.

• 🔄 1% Quota Auto-Rotator: Continuously tracks model quota and seamlessly switches accounts when quota reaches $\le 1%$.

• ⚡ Accurate Token Counter: Multi-model token measurement (Gemini, Claude, GPT-4o, DeepSeek) and session budget protection.

• 📉 Model Context Compression: Structural context and token pruning via LightCompress reconstruction.

• 🌐 In-IDE Webview Extension: Live token burn, remaining quota, task dashboard, and click-to-check update indicators.

• 🤖 Chat Mention @agent-guard: Summon Agent Guard directly in Antigravity or AI coding chat by typing @agent-guard.

System Architecture

flowchart TD
    subgraph Antigravity ["Google Antigravity & AI IDEs"]
        Agent["Autonomous AI Agent"]
        HookEngine["Stop Hook Engine"]
        Rules["Workspace Rules (AGENTS.md)"]
        LS["Antigravity Language Server"]
    end

    subgraph AgentGuard ["agent-guard (Node 20+ / TypeScript)"]
        MCPServer["MCP Server (stdio)\nsrc/index.ts"]
        Tools["9 Core MCP Tools\ntask_start | task_checkpoint | task_status\nkeep_awake | repo_brief | agent_enforce\ntoken_counter | account_switcher | model_compressor"]
        Ledger["Safe Ledger Engine\n(Atomic Rename, Auto-Repair)"]
        AwakeMgr["Awake Supervisor\n(caffeinate / Win32 / systemd)"]
        Rotator["Account 1% Auto-Rotator"]
        QuotaProbe["Live Quota Probe"]
        StopHook["Stop Hook Script\n(3-Idle Push Loop Breaker)"]
        ExtUI["In-IDE Web Extension"]
    end

    subgraph Project ["Target Repository: <project>/"]
        AgentDir[".agent/"]
        LedgerJson[".agent/ledger.json\n(Task & Step DAG)"]
        BriefMd[".agent/brief.md\n(Cached Map < 1.5k tok)"]
        AccountsJson[".agent/accounts.json\n(Multi-Account Pool)"]
        LogTxt[".agent/log.txt\n(1MB Rotated Audit Log)"]
    end

    Rules -->|Guides Calls| Agent
    Agent <-->|MCP Protocol| MCPServer
    MCPServer --> Tools
    Tools --> Ledger
    Tools --> AwakeMgr
    Tools --> Rotator
    Tools --> QuotaProbe
    QuotaProbe <-->|Probes| LS
    Rotator --> AccountsJson
    Ledger --> LedgerJson
    HookEngine -->|Fires on Exit| StopHook
    StopHook --> LedgerJson
    StopHook -->|continue or allow| HookEngine
    ExtUI <--> Tools

Core Pillars & Capabilities

1. 🛡️ Zero Telemetry & Local Sandboxing

• 100% Offline & Private: Zero network dependencies, zero tracking, no cloud telemetry.

• Strict Path Sandboxing: Resolves canonical realpaths; strictly jails writes to <project>/.agent/. Disallows root directory, user home directory, and uninitialized paths.

2. 💾 Crash-Proof, Self-Healing State Ledger

• Atomic Writes: Writes to .agent/ledger.tmp followed by atomic filesystem rename.

• Lock Contention: Concurrency locking (.agent/ledger.lock) with 30-second stale lock eviction.

• Automatic Recovery: Backs up prior state to ledger.prev.json before writing; automatically self-heals and restores state if corruption is ever detected on read.

3. 🔄 1% Quota Auto-Rotator & Account Pool

• Continuously probes active session quota via Antigravity Language Server and proxy balance.

• Automatically triggers rotation when quota $\le 1.0%$, seamlessly switching credentials without disturbing running tasks.

• Supports Antigravity OAuth tokens, Claude API keys, OpenAI tokens, and custom proxy endpoints.

4. ⚡ Multi-Model Token Counter & Cost Monitor

• Real-time token calculation across Gemini, Claude 3.5 Sonnet, GPT-4o, and DeepSeek.

• Analyzes raw text snippets, project files, or conversation transcripts (transcript.jsonl).

• Context budget alerts prevent agents from crossing prompt limits.

5. 📉 Model & Context Compression (LightCompress REA)

• Structural pruning of bloated outputs, verbose stack traces, and boilerplate logs.

• Memory footprint estimator for LLMs, VLMs, and diffusion models (1B to 671B parameters).

• Quantization and deployment config generation (W4A16, FP8, INT4).

6. ☕ Supervised Keep-Awake Leases

• Prevents unattended computers from sleeping during long builds, tests, or multi-step execution.

• Native OS helpers:

  • macOS: caffeinate -di -t <sec> -w <pid> with seamless child swapping (no sleep gap).

  • Windows: PowerShell SetThreadExecutionState continuous wrapper.

  • Linux: systemd-inhibit --what=idle:sleep.

• Auto-expiring lease renewed at every checkpoint, guarded by an 8-hour hard ceiling.

7. 🛑 Antigravity Stop Hook & Loop Breaker

• Wired via Antigravity's .agents/hooks.json.

• Detects premature agent stops: if unfinished, unblocked steps remain, soft-pushes the agent back to continue.

• Loop Breaker: If the agent makes no checkpoint progress for 3 consecutive pushes, or reaches 10 total pushes, allows stop to prevent runaway loops.

MCP Tools Reference

🛠️ Unified CLI Reference

Agent Guard includes an exhaustive command-line interface:

# Diagnostic & Installation
node dist/cli.js doctor                       # Complete integration & readiness health check
node dist/cli.js install                      # Universal multi-app auto-installer
node dist/cli.js auto-accept                  # Grant autoApprove permissions across all IDEs

# Task & Supervised Sleep
node dist/cli.js awake status                 # Check OS sleep inhibition status
node dist/cli.js awake hold --minutes 45      # Request a 45-minute keep-awake lease
node dist/cli.js awake release                # Release active sleep lease

# Quota & Token Monitoring
node dist/cli.js tokens                       # View session token count and active model budget
node dist/cli.js tokens --live                # Synchronously query Antigravity live quota

# Multi-Account Management
node dist/cli.js accounts status              # Inspect accounts pool and active quota %
node dist/cli.js accounts switch --name work  # Switch active profile to "work"
node dist/cli.js accounts rotate              # Manually trigger quota failover check

# Model & Context Compression
node dist/cli.js compress --file trace.log    # Compress verbose file before sending to model
node dist/cli.js compress estimate -p 70      # Estimate memory for 70B parameter model

# In-IDE Extension & Dashboard
node dist/cli.js extension status             # Check extension build and version status
node dist/cli.js extension install            # Re-link web extension in Antigravity IDE
node dist/cli.js update                       # Self-update Agent Guard from GitHub origin/main

🚀 App-by-App Installation Guide & Agent Configuration Recipes

Agent Guard seamlessly integrates into any autonomous coding application using standard Model Context Protocol (MCP) configuration over stdio. Use the automated installer (./install.sh) or manually add the configuration snippets below:

Configuration Path: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"]
    }
  }
}

Antigravity Stop Hook (<project>/.agents/hooks.json):

{
  "agent-guard-stop": {
    "Stop": [
      {
        "type": "command",
        "command": "node /Users/sarvesh/Downloads/mcp/agent-guard/dist/hook/stop-hook.js"
      }
    ]
  }
}

Chat Mention: Summon directly in any chat:

@agent-guard run complete audit and tests before committing

One-Line CLI Setup:

claude mcp add agent-guard -- node /Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js

Configuration Path: ~/.claude/mcp.json or ~/.claude.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"],
      "autoApprove": [
        "task_start",
        "task_checkpoint",
        "task_status",
        "keep_awake",
        "repo_brief",
        "agent_enforce",
        "token_counter",
        "account_switcher",
        "model_compressor"
      ]
    }
  }
}

Configuration Path: ~/.cursor/mcp.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"]
    }
  }
}

System Prompt / Rules (<project>/.cursorrules):

Supervised by Agent Guard:
- Check task_status or call repo_brief on session start.
- Break down tasks with task_start.
- Checkpoint each step with test proofs using task_checkpoint.

Configuration Path: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"]
    }
  }
}

Configuration Path: cline_mcp_settings.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"],
      "disabled": false,
      "autoApprove": [
        "task_start",
        "task_checkpoint",
        "task_status",
        "keep_awake",
        "repo_brief",
        "agent_enforce",
        "token_counter",
        "account_switcher",
        "model_compressor"
      ]
    }
  }
}

Configuration Path: ~/.codex/mcp.json or $CODEX_HOME/mcp.json

{
  "mcpServers": {
    "agent-guard": {
      "command": "node",
      "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"]
    }
  }
}

Configuration Path: ~/.config/zed/settings.json

{
  "experimental": {
    "model_context_protocol": {
      "servers": {
        "agent-guard": {
          "command": "node",
          "args": ["/Users/sarvesh/Downloads/mcp/agent-guard/dist/index.js"]
        }
      }
    }
  }
}

🧪 Test Suite & Quality Verification

Agent Guard is verified by an exhaustive 16-suite Vitest test harness:

npm test

 RUN  v3.2.7 /Users/sarvesh/Downloads/mcp/agent-guard

 ✓ test/tokenCounter.test.ts (14 tests)
 ✓ test/liveQuota.test.ts (10 tests)
 ✓ test/stepRules.test.ts (7 tests)
 ✓ test/appInstall.test.ts (8 tests)
 ✓ test/skills.test.ts (10 tests)
 ✓ test/stopHook.test.ts (4 tests)
 ✓ test/repoBrief.test.ts (4 tests)
 ✓ test/update.test.ts (4 tests)
 ✓ test/accountSwitcher.test.ts (11 tests)
 ✓ test/tools.test.ts (7 tests)
 ✓ test/extension.test.ts (8 tests)
 ✓ test/ledger.test.ts (6 tests)
 ✓ test/modelCompressor.test.ts (8 tests)
 ✓ test/agentEnforce.test.ts (5 tests)
 ✓ test/paths.test.ts (8 tests)
 ✓ test/keepAwake.test.ts (7 tests)

 Test Files  16 passed (16)
      Tests  124 passed (124)
   Duration  2.58s

🌟 Active Skills Catalog (78 Active / 3,500+ Library)

Agent Guard automatically deploys 78 production skills directly into ~/.gemini/config/skills/, workspace .gemini/skills.json, and plugin directories, making them immediately discoverable and callable by AI agents in Google Antigravity, Claude Code, Cursor, Windsurf, and VS Code.

📄 1. Official Office Document & API Skills (anthropics/skills)

🎨 2. Design Intelligence, UI/UX & Web Artifacts (nextlevelbuilder/ui-ux-pro-max-skill)

🛡️ 3. Core Architecture, TDD & Supervised Engineering (agent-guard & addyosmani/agent-skills)

⚡ 4. Productivity, Workflow & External Connectors (addyosmani/agent-skills)

🦹 5. Lazy Senior Dev Mode (DietrichGebert/ponytail Plugin)

⚡ Autonomous JIT Dynamic Skill Activation Engine (3,600+ Skills)

To solve the Context Bloat Paradox (where loading 3,600+ skills into system prompts consumes ~180,000 tokens), Agent Guard features a Zero-Turn Autonomous Just-in-Time (JIT) Semantic Router:

1. Sub-10ms In-Memory Semantic Router (src/skills/router.ts):

   • Indexes all 3,608 unique skills across Tier 1 (78 active), Tier 2 (832 Composio SaaS), and Tier 3 (2,749 Awesome community).

   • Inverted BM25 keyword index with stemming, exact slug boost, and category relevance.

2. Ambient PreInvocation Zero-Turn Hook (src/hook/pre-invocation-hook.ts):

   • Intercepts user requests prior to model generation in Google Antigravity and Gemini CLI.

   • Dynamically injects specialized procedural runbooks via ephemeralMessage without polluting permanent context.

   • De-duplicates activations per conversation session to prevent repetitive token overhead.

3. skill_activate Universal MCP Tool (src/tools/skillActivate.ts):

   • AI agents can dynamically query, rank, and activate any skill on-demand mid-task.

   • Automatically symlinks/installs full templates into <project>/.agents/skills/<id> and updates .agents/skills.json.

4. Workspace Tech-Stack Auto-Scanner (src/skills/scanner.ts):

   • Inspects package.json, Dockerfile, go.mod, Cargo.toml, and CI/CD pipelines.

   • Automatically maps detected frameworks and tools to top matching skills from the 3,600+ library.

🛠️ CLI Commands:

# Semantic JIT route query across 3,790+ skills (sub-10ms)
node dist/cli.js skills route "biopython fasta sequence"
node dist/cli.js skills route "format docx word document letter"

# Activate and auto-link skill into current workspace
node dist/cli.js skills activate "remember"
node dist/cli.js skills activate "clean architecture"

# Auto-scan workspace tech stack and recommend skills
node dist/cli.js skills scan

# Auto-scan and save recommendations to .agents/skills.json
node dist/cli.js skills scan --save

🧠 Cognitive Long-Term Memory Engine (Cross-Session Recall)

Your coding agent remembers architectural decisions, conventions, and bug fixes across restarts and conversations without manual re-explaining:

# Save an architectural rule or decision to project memory
node dist/cli.js memory store "Use in-memory BM25 index for sub-10ms skill routing" --tags skills,routing,perf --category architecture

# Recall past decisions, learnings, and context
node dist/cli.js memory recall "BM25 skill routing"

# List all stored memories for the project
node dist/cli.js memory list

📚 Integrated 3,790+ Skills Ecosystem

To prevent saturating the model's prompt context with tens of thousands of tokens, Agent Guard dynamically indexes 5 major collections under unified local offline management:

• 🔬 177 Scientific Research Skills (templates/skills/scientific/): Biopython, Astropy, Cirq (quantum), DeepChem, DiffDock, CellProfiler, Cantera, PyTorch scientific workflows.

• 🧠 18 Cognitive Memory Skills (templates/skills/memory/): Remember, Recall, Recap, Forget, Handoff, Lesson, Session History, and Memory Discipline.

• ⚡ 75 Core Curated Skills (templates/skills/curated/): Clean Architecture, TDD, Agent Skills Patterns, Agent GUI Dashboard, Security Audit, DevOps, Token Optimizer.

• 🌐 833 Composio SaaS Integrations (agent-skills/skills/composio-skills/): Turnkey API recipes for 800+ cloud platforms (Stripe, GitHub, Jira, Salesforce, HubSpot).

• 🌟 2,689 Awesome Community Skills (templates/skills/skills_index.json): Broad collection across 114 technical disciplines.

Search and install any skill from the catalog on-demand:

# Search the 3,790+ skill catalog
node dist/cli.js skills search "biology"

# Install a specific skill into your active IDE skills directory
node dist/cli.js skills install "biopython"

👨‍💻 Developer & Author

• Developer: Sarvesh (@anksarvesh-lgtm)

• Project Repository: https://github.com/anksarvesh-lgtm/agent-guard

📄 License

Agent Guard is free and open-source software licensed under the Apache License, Version 2.0.