Hermes Plugin — Arquitetura Kickbacks Standalone

Hermes Agent plugin that implements Kickbacks.ai without depending on VS Code extension or IDE file patches.

Architecture vs VS Code Extension

Aspect	VS Code Extension (official)	Hermes Plugin (our version)
Coupling	Patches Claude Code's webview/index.js + extension.js	Zero patches — hook on Hermes lifecycle
Surfaces	Spinner overlay + banner (DOM)	Statusline (OSC 8) + banner + spinner
Ad length	text-overflow: ellipsis (truncated)	Marquee animation (scroll)
TOS	Modifies third-party files ✅❌	Official API only, nothing modified ✅
Dependency	VS Code / fork installed	Hermes Agent only (CLI)
Persistent banner	Only on idle	Fixed, even during thinking
Billing decay	Constant (5s tick always)	Logarithmic: 5s → 10s → 30s → 60s → stop (5min)
Authentication	Google OAuth in VS Code	Google OAuth via browser + polling
Backend	kickbacks-backend-*.run.app	Same official backend
Demo mode	/v1/portfolio/demo without token	Same endpoint
Metrics	/v1/metrics or /v1/metrics/demo	Same endpoint

How It Works

1. API Client (api.py)

Complete Kickbacks.ai API client:

• fetch_portfolio() — fetch ads (authenticated or demo)
• send_metric() — impression_rendered, view_tick, click, etc.
• start_sign_in() / poll_sign_in() — Google OAuth
• fetch_earnings() — balance
• write_ad_cache() — saves current ad to ~/.kickbacks/hermes-ad.json

Endpoint base: https://kickbacks-backend-gmdaqm2c7q-uw.a.run.app

2. Impression Tracker (tracker.py)

Billing engine with two simultaneous surfaces:

Statusline (thinking):

• start() → triggers when Hermes makes an LLM call or tool execution
• stop() → 350ms grace timer (covers LLM↔tool handoffs)
• AD_REST_MS (20s default) between billing sessions
• Ticks every 5s during visible time

Banner (idle + thinking):

• Starts IMMEDIATELY when thinking ends (without waiting for grace)
• Co-exists with thinking — banner stays fixed at all times
• Logarithmic billing decay:
  • 0-30s idle: tick every 5s
  • 30s-1min: tick every 10s
  • 1min-2min: tick every 30s
  • 2min-5min: tick every 60s

  • 5min: stop (ad persists visually, no billing)

Independent sessions: each surface has its own session_nonce, started_at, threshold_met — they don't compete with each other.

3. Marquee Animation (vs Ellipsis)

The official version uses CSS text-overflow: ellipsis on the overlay (line 101 of block.asset.js):

overflow:hidden;text-overflow:ellipsis

Our version has marquee animation for long ad text — instead of ugly truncation, the text slides horizontally. The exact code is in the Hermes scripts.

4. Status Line Display (hermes-kickbacks-status)

Python script that reads the cache ~/.kickbacks/hermes-ad.json and displays the ad as an OSC 8 hyperlink in the terminal:

ESC ]8;;<url> ESC \ ad· Texto do Anúncio ESC ]8;; ESC \

Integrable with:

• tmux (status-right)
• iTerm2 (Status Bar component)
• fish (prompt function)
• WezTerm (status bar)

5. No IDE Patches

Unlike the VS Code patch, the Hermes plugin:

1. Does not modify any extension file
2. Does not need CSP relaxation (connect-src)
3. Does not use DOM overlay / MutationObserver
4. Does not depend on webview/index.js or extension.js
5. Works in any terminal — VS Code, Antigravity, Cursor, plain terminal
6. Respects TOS — consumes the official API like any legitimate client

Hermes Agent has native hooks (pre_llm_call, post_llm_call, pre_tool_call, post_tool_call) that the plugin uses to know when the agent is "thinking" — without needing to reverse-engineer the DOM.

Installation

# Plugin already installed in ~/.hermes/plugins/kickbacks/
python3 ~/.hermes/plugins/kickbacks/scripts/setup.py

Ad Cache

The current ad is stored in ~/.kickbacks/hermes-ad.json — any script can read it:

{
  "ad_text": "Patrocinado por...",
  "click_url": "https://...",
  "ts": 1712345678000,
  "ad_id": "...",
  "demo": true
}

Debug

KICKBACKS_DEBUG=1 hermes chat ...
# Logs em: ~/.kickbacks/logs/

Links

• kickbacks-antigravity — Official VS Code patch (different approach)
• antigravity-ide — Google Antigravity IDE