kristianvast/hermes-claude-auth

Claude Code OAuth bypass for hermes-agent

hermes‑claude‑auth – OAuth bypass for the Hermes AI agent

What it is

  • A tiny Python‑only patch that lets the hermes‑agent (an open‑source Claude‑based chatbot/assistant) keep using a Claude Code subscription (Max/Pro) after Anthropic added server‑side OAuth validation on 2026‑04‑04.
  • It does not modify any hermes‑agent source files. Instead it installs a runtime hook (via a .pth shim) that monkey‑patches the function build_anthropic_kwargs the moment the hermes virtual‑environment starts.

Why you might need it

  • Without this patch, hermes‑agent’s OAuth flow is rejected and the request falls back to Anthropic’s “extra‑usage” (pay‑per‑token) billing, or simply fails with HTTP 400/401.
  • The hook adds the exact billing header, system‑prompt layout, beta flags, and user‑agent fingerprint that Claude Code expects, so the request is treated as a normal subscription call.
  • It also adds a subscription‑window aware auto‑wait: when a Claude Pro/Max quota window (5 h, 1 d, 7 d) is exhausted, the agent will sleep until the window resets instead of aborting.

How it works (high‑level)

  1. Bootstrap – a .pth file placed in the hermes venv’s site‑packages imports a tiny bootstrap module at interpreter start.
  2. MetaPathFinder hook – the bootstrap registers a finder that intercepts imports of agent.anthropic_adapter and patches build_anthropic_kwargs.
  3. Billing header – computes a SHA‑256‑signed x-anthropic-billing-header and injects it as the first system message.
  4. System‑prompt relocation – moves non‑identity system entries into a <system‑reminder> block inside the first user message (the format Claude Code expects).
  5. Rate‑limit auto‑wait – on HTTP 429 the hook reads Anthropic’s anthropic‑ratelimit‑unified‑*‑reset headers, picks the longest window, sleeps (capped per‑window) and retries transparently.
  6. Fingerprint parity – forces the user‑agent and billing header to report the same Claude Code version (2.1.112 or the locally detected version) and sets x‑app: cli so Anthropic does not treat the request as “extra usage”.

Installation

  • Linux/macOS – one‑liner: curl … | bash or clone the repo and run ./install.sh.
  • Windows – PowerShell one‑liner: irm … | iex or clone and run . install.ps1.
  • The installer automatically:
    • Detects the hermes data directory ($HERMES_HOME or defaults).
    • Copies anthropic_billing_bypass.py to <hermes‑dir>/patches/.
    • Places the .pth shim and bootstrap module inside the hermes virtual‑env.
    • Mirrors Claude Code credentials from the OS credential store to ~/.claude/.credentials.json.
    • Restarts the hermes‑gateway.service on Linux if it is running.

Uninstall

  • Run ./uninstall.sh (Linux/macOS) or . uninstall.ps1 (Windows). Use --purge / -Purge to also delete the patch file.

Recovery after hermes update

  • hermes update can wipe the sitecustomize.py that previously held the hook. This repo installs two defenses:
    1. Git hooks placed outside the repo (core.hooksPath) that re‑run the installer after a merge.
    2. A cron‑style watchdog (restore_loader.sh) that restores the loader every 15 min while the Hermes gateway is up.
  • The installer also provides --post-update and --check flags to verify that the patch file matches the repo and to restore a missing loader.

Verification After installation, you should see lines like:

[anthropic_billing_bypass] Bypass installed
[anthropic_billing_bypass] Rate‑limit auto‑wait installed

in the Hermes gateway logs. A successful chat command such as:

hermes chat --provider anthropic -m claude‑sonnet‑4‑6 -q "OK" -Q

should complete without extra usage or HTTP 400 errors.

Compatibility

  • hermes‑agent ≥ Python 3.11, Linux/macOS/Windows.
  • Works with multiple hermes profiles; the patch lives at the data‑root and is shared.
  • Relies on the internal function build_anthropic_kwargs(is_oauth=…); if hermes‑agent changes that signature the patch will need an update.

Key take‑aways

  • No source code changes – everything is applied at runtime via import hooks.
  • Handles both OAuth validation and subscription‑window throttling, turning a hard failure into a graceful wait‑and‑retry.
  • Self‑healing – git‑hook + cron recovery keep the bypass alive across hermes updates.

All details above are taken directly from the repository’s README; no additional features have been inferred.

Related

  • Project
    wesammustafa/Claude-Code-Everything-You-Need-to-Know

    A thorough, example‑rich tutorial for Anthropic’s Claude Code CLI, covering installation, prompt engineering, and advanced extensions (Skills, Hooks, Sub‑agents, Workflows, MCP) to let developers use Claude for repo‑wide code analysis, editing, testing and automation.

  • Project
    cheapestinference/claude-auto-retry

    A utility for the Claude Code CLI that automatically detects rate limits and API errors, waiting for resets and sending "continue" to resume tasks without manual intervention.

  • Dispatch
    Understanding the New Claude Agent SDK Credit System

    Anthropic is introducing a monthly credit system for the Claude Agent SDK, separating automated agent usage from standard subscription limits.

  • Project
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent is an open‑source framework that gives Anthropic’s Claude Code project awareness and expert‑agent capabilities. It uses a Python Hook system and a locally‑run Ollama model to automatically detect the codebase type, analyse user intent, load 300+ domain‑specific “Skills” (backend, frontend, testing, security, etc.), and enforce automatic documentation (DEVELOPMENT.md, KNOWLEDGE.md, CHANGELOG.md). After cloning, installing Ollama, a model, and uv, you drop your project into the repo and Claude Code instantly knows its context, suggests appropriate tools, and can be driven with slash commands like `/backend‑specialist` or workflow commands such as `/kiro/spec`. Key points: - Zero‑config start; all configuration lives in `.claude/settings.json` and `prompts.json`. - Hooks run on session start, user prompt, tool use, etc., handling project detection, intent analysis, and doc updates. - Skills are defined by `SKILL.md` files and are auto‑discovered. - Works entirely locally (no external API), integrates with Git, and is MIT‑licensed. Ideal for developers or small teams who want a reproducible, on‑premise AI coding assistant.

  • Project
    richhickson/claudecodeusage

    Claude Usage is a native macOS menubar app that shows real‑time Claude Code quota usage (session, weekly, monthly) and alerts you when a Claude Code session is waiting for input, letting you jump directly to the terminal tab. It reads your OAuth token from the Keychain, polls Anthropic’s usage endpoint, and uses Claude Code’s hook system for session monitoring.