Guide: Use Claude Max/Pro Subscription with Hermes on macOS

[DrQbz]

Use Your Claude Max/Pro Subscription with Hermes (macOS)

This guide documents a working setup for using a Claude subscription with Hermes via hermes-claude-auth, without needing to rediscover all the failure modes.

Tested on:

• macOS
• Hermes Agent v0.10.0 (2026.4.16)
• Claude Code 2.1.114
• hermes-claude-auth commit 22868d3

Direct patch repo:

• https://github.com/kristianvast/hermes-claude-auth

What actually worked

hermes-claude-auth alone was not enough.

The missing piece was that Hermes reads Claude subscription credentials from:

• ~/.claude/.credentials.json

On macOS, Claude Code may be authenticated in Keychain while that file is missing or stale.
When that happens, Hermes can fail with either:

• 401 authentication failed
• No Anthropic credentials found

The reliable fix was:

1. install hermes-claude-auth
2. refresh Claude subscription login with claude auth login --claudeai
3. write the current Keychain Claude Code-credentials entry into ~/.claude/.credentials.json
4. make sure stale ANTHROPIC_TOKEN / ANTHROPIC_API_KEY values do not override the Claude subscription path

Symptoms this solves

Common failure modes before the fix:

• Hermes says Anthropic 401 — authentication failed
• Hermes says No Anthropic credentials found
• Hermes uses an old ANTHROPIC_TOKEN from ~/.hermes/.env
• Claude Code itself works, but Hermes still fails

Prerequisites

You need:

• Hermes installed at ~/.hermes/hermes-agent/
• Claude Code installed and working
• An active Claude subscription login in Claude Code
• Python 3.11+

Useful checks:

hermes --version
claude --version
claude auth status --text

Step 1: Install the patch

Recommended:

curl -fsSL https://raw.githubusercontent.com/kristianvast/hermes-claude-auth/main/install-remote.sh | bash

Or manually:

git clone https://github.com/kristianvast/hermes-claude-auth.git
cd hermes-claude-auth
./install.sh

This installs:

• ~/.hermes/patches/anthropic_billing_bypass.py
• ~/.hermes/hermes-agent/venv/lib/python3.11/site-packages/sitecustomize.py

Step 2: Refresh Claude subscription auth

Run:

claude auth login --claudeai

This refreshes the Claude subscription login flow.

Step 3: Export Claude Code credentials from macOS Keychain to the file Hermes reads

On macOS, this was the key step.

Run:

python3 - <<'PY'
import subprocess
from pathlib import Path

secret = subprocess.check_output(
    ['security', 'find-generic-password', '-s', 'Claude Code-credentials', '-w'],
    text=True,
).strip()

cred_path = Path.home() / '.claude' / '.credentials.json'
cred_path.parent.mkdir(parents=True, exist_ok=True)
cred_path.write_text(secret)
cred_path.chmod(0o600)

print(f'wrote {cred_path}')
PY

Why this matters:

• Claude Code may be logged in via Keychain
• Hermes' Anthropic subscription path reads ~/.claude/.credentials.json
• If that file is missing or stale, Hermes may fail even though Claude Code works

Step 4: Remove stale Anthropic env credentials that override subscription auth

Check ~/.hermes/.env for:

• ANTHROPIC_TOKEN=
• ANTHROPIC_API_KEY=

These can force Hermes onto a broken or stale token path.

If you want Hermes to use Claude subscription auth instead of API-key billing, remove or blank them.

Example cleanup:

python3 - <<'PY'
from pathlib import Path

p = Path.home() / '.hermes' / '.env'
text = p.read_text() if p.exists() else ''
lines = []
for line in text.splitlines():
    if line.startswith('ANTHROPIC_TOKEN=') or line.startswith('ANTHROPIC_API_KEY='):
        continue
    lines.append(line)
p.write_text('\n'.join(lines) + ('\n' if lines else ''))
print(f'cleaned {p}')
PY

If Hermes has cached a bad Anthropic credential state, reset it:

hermes auth reset anthropic

Step 5: Test Hermes

Test Sonnet:

hermes chat -q 'Reply with exactly: PATCHED SONNET OK' --provider anthropic -m claude-sonnet-4-6 -Q

Expected output:

PATCHED SONNET OK

Test Opus:

hermes chat -q 'Reply with exactly: PATCHED OPUS OK' --provider anthropic -m claude-opus-4-6 -Q

Expected output:

PATCHED OPUS OK

Verify the patch is loading

When working, Hermes may print lines like:

[anthropic_billing_bypass] Claude Code OAuth bypass installed
[anthropic_billing_bypass] Aux client temperature hook installed

You can also verify the installed files directly:

ls -l ~/.hermes/patches/anthropic_billing_bypass.py
ls -l ~/.hermes/hermes-agent/venv/lib/python3.11/site-packages/sitecustomize.py

Troubleshooting

Problem: Anthropic 401 — authentication failed

Usually means Hermes is using a stale bearer token.

Fix order:

1. claude auth login --claudeai
2. rewrite ~/.claude/.credentials.json from Keychain
3. remove stale ANTHROPIC_TOKEN / ANTHROPIC_API_KEY from ~/.hermes/.env
4. hermes auth reset anthropic
5. retry

Problem: No Anthropic credentials found

Usually means Hermes cannot find valid refreshable Claude credentials.

Check:

• ~/.claude/.credentials.json exists
• it contains claudeAiOauth
• the file is fresh, not an old expired export

Re-export from Keychain using Step 3.

Problem: Claude Code works, Hermes still fails

This is exactly the macOS Keychain vs file mismatch.

Claude Code may be authenticated in Keychain, while Hermes still reads a missing or stale ~/.claude/.credentials.json.
Re-run Step 3.

Problem: patch installed but no effect

Check:

sed -n '1,80p' ~/.hermes/hermes-agent/venv/lib/python3.11/site-packages/sitecustomize.py

It should contain the marker:

# hermes-claude-auth managed

Important caveats

This setup is a compatibility hack, not an official Anthropic-supported flow.
It may break if:

• Anthropic changes OAuth validation again
• Hermes changes its Anthropic adapter internals
• hermes-claude-auth falls behind Hermes releases

Recommended maintenance workflow

If the setup stops working in the future, try this sequence first:

claude auth login --claudeai
python3 - <<'PY'
import subprocess
from pathlib import Path
secret = subprocess.check_output(
    ['security', 'find-generic-password', '-s', 'Claude Code-credentials', '-w'],
    text=True,
).strip()
cred_path = Path.home() / '.claude' / '.credentials.json'
cred_path.parent.mkdir(parents=True, exist_ok=True)
cred_path.write_text(secret)
cred_path.chmod(0o600)
print(f'wrote {cred_path}')
PY
hermes auth reset anthropic

Then retest Sonnet/Opus.

Summary

Working solution on macOS:

• use hermes-claude-auth
• refresh Claude subscription login
• mirror Claude Code credentials from Keychain into ~/.claude/.credentials.json
• remove stale Anthropic env tokens from ~/.hermes/.env

That combination made Hermes work successfully with both:

• claude-sonnet-4-6
• claude-opus-4-6

[kristianvast]

This is great \u2014 thank you for writing it up so thoroughly. The macOS Keychain mirror step is exactly the missing piece on macOS, and the symptoms/fix mapping is clean.

I've pulled the key steps into the README's new Troubleshooting \u2192 Auth issues section with credit back to you and a link to this issue, so anyone landing here from search has it in front of them. Closing this as merged into docs.

One caveat I added honestly to the README: the billing path (routing to Max/Pro subscription vs extra usage) is a separate cat-and-mouse game with Anthropic's server-side validation \u2014 being tracked in #6 \u2014 and even with perfect auth wiring, requests may still land on extra-usage credits depending on what Anthropic has deployed that week. Your guide fixes the "auth is broken" case; the "auth works but billing wrong tier" case needs the bypass itself to stay current with upstream.

[kristianvast]

Follow-up: as of v1.1.1 (75a3f71), install.sh auto-mirrors the Claude Code-credentials Keychain entry into ~/.claude/.credentials.json on every run when it detects Darwin. The oneliner now works end-to-end on macOS without a manual post-install step.

Flow on macOS:

1. claude auth login --claudeai (puts creds in Keychain)
2. curl -fsSL https://raw.githubusercontent.com/kristianvast/hermes-claude-auth/main/install-remote.sh | bash
3. Done — hermes-agent reads credentials.json on next start.

The Python snippet you originally wrote is kept in the README as a fallback for edge cases (e.g. if the Keychain entry is under a different service name). Thanks again @DrQbz for the writeup that unblocked this.