Hermes Antigravity Pool

Google Antigravity CLI (agy) account-pool bridge for original Hermes.

Original Hermes can load OpenAI-compatible custom providers from ~/.hermes/config.yaml, but it does not ship a native Antigravity provider. This package supplies the missing compatibility layer:

• Multi-Account Isolation: Isolates multiple agy logins under separate HOME directories.
• Failover & LRU Rotation: Automatically selects the least-recently-used healthy account and handles cooldowns for rate-limited/exhausted slots.
• Reasoning Stream Extraction: Translates custom XML-like reasoning tags to native OpenAI reasoning_content to display real-time thinking processes in the Hermes TUI.
• Tool Interception: Bridges custom XML-like tool tags into OpenAI function calling format to support native agent operations.

:gear: Architecture & Workflow

Here is how agy-pool bridges original Hermes and Google's Antigravity CLI with account isolation, health checking, and live token routing:

graph TD
    subgraph Hermes Environment
        Hermes[Hermes Agent CLI/TUI]
        Config[config.yaml]
    end

    subgraph agy-pool Bridge
        Bridge[API Endpoint: /v1/chat/completions]
        LRU[Account Selector / LRU Routing]
        Health[Health & Cooldown Tracker]
    end

    subgraph Isolated Accounts
        Acc1[Account 1: virtual HOME]
        Acc2[Account 2: virtual HOME]
        AccN[Account N: virtual HOME]
    end

    subgraph Google Antigravity
        AgyCLI[agy CLI executable]
        Google[Google Cloud AI Backend]
    end

    Hermes -->|1. OpenAI chat completion| Bridge
    Config -.->|configures custom provider| Hermes
    Bridge -->|2. Get healthiest account| LRU
    LRU <-->|tracks status & locks| Health
    LRU -->|3. Route with isolated env| Acc1
    LRU -.-> Acc2
    LRU -.-> AccN
    Acc1 -->|4. Execute agy --print| AgyCLI
    AgyCLI -->|5. Print stdout| Google
    Google -->|6. Stream response| AgyCLI
    AgyCLI -->|7. SSE event stream / JSON| Bridge
    Bridge -->|8. Standard completions| Hermes

:sparkles: Key Features

• Isolated Sessions: No shared state between accounts. Each slot gets its own conversation history and credentials.
• OpenAI-Compatible Bridge: Exposes a local /v1/chat/completions endpoint for the custom Hermes provider custom:agy-pool.
• Robust Health Check: Automatically identifies quota limits, auth expiration, and network errors, applying smart cooldowns.
• Real-Time Streaming: Stream completions token-by-token with minimized initial latency.
• Zero Configuration Fallback: If a selected account is exhausted, request failover occurs transparently in the background.

For more details on design and protocols, see docs/features.md.

:quicksand: Requirements

• Linux or macOS shell environment
• Python 3.10+
• PyYAML (required for automated Hermes configuration updates)
• Hermes Agent installed
• Google Antigravity CLI installed and available as agy

Check:

command -v hermes
command -v agy

If agy is not on your PATH, export its location:

export AGY_BIN=/absolute/path/to/agy

:rocket: One-Line Install

Run the following command to automatically install the script and configure the Hermes custom provider:

curl -fsSL https://raw.githubusercontent.com/ahmedsaid47/hermes-antigravity-pool/main/install.sh | bash -s -- --configure-hermes

:books: Quick Start Guide

1. Register Accounts

Start the interactive login flow for your accounts. agy-pool handles directory isolation automatically:

~/.hermes/bin/agy-pool login [email protected]

Repeat for each slot in your account pool:

~/.hermes/bin/agy-pool login [email protected]

Verify your active slots:

~/.hermes/bin/agy-pool status

2. Configure Hermes & Start Bridge

You can configure Hermes manually or let the helper set up ~/.hermes/config.yaml automatically:

~/.hermes/bin/agy-pool bridge configure-hermes

Start the local API bridge service:

~/.hermes/bin/agy-pool bridge start

3. Verify Health & Monitor Logs

Confirm that both the bridge and Hermes configurations are aligned and operational:

~/.hermes/bin/agy-pool bridge check

Monitor incoming requests and logs in real-time:

~/.hermes/bin/agy-pool bridge logs -f

Test chat completions directly via Hermes:

hermes chat -Q -q "Sadece ANTIGRAVITY_POOL_OK yaz."

:microscope: Development & Testing

When adding features or making modifications locally:

1. Clone the repository:

   git clone https://github.com/ahmedsaid47/hermes-antigravity-pool.git
   cd hermes-antigravity-pool
   

2. Install the package in development mode:

   ./install.sh --configure-hermes
   

3. Run the contract tests:

   python3 -m unittest discover -s tests
   

:shield: Security

Do not commit or share:

• ~/.hermes/auth.json / ~/.hermes/.env
• ~/.hermes/antigravity/accounts/
• Any active Google/OAuth tokens or session files.

Read docs/security.md before publishing modifications.

:life_preserver: Troubleshooting

Check docs/troubleshooting.md for details regarding account cooldowns, starting/stopping the bridge, and resolving provider resolution errors.