Reusing Coding-Tool Subscriptions as Hermes Backends (Copilot / Codex / Claude Max)
Connect Hermes to the coding-tool subscription you already pay for — GitHub Copilot, OpenAI Codex, or a Claude Max plan with extra-usage credits — using the provider that matches the subscription's native auth method, so you avoid buying another API key.
Requirements
- For the direct Copilot provider (
copilot), Hermes resolves the auth chainCOPILOT_GITHUB_TOKEN→GH_TOKEN→GITHUB_TOKEN→gh auth token, and acceptsgho_OAuth,github_pat_fine-grained PAT, andghu_GitHub App tokens — but notghp_*classic PATs. - The
copilot-acpACP backend requires the Copilot CLI in PATH and an existingcopilot login; the command and arguments are overridable viaHERMES_COPILOT_ACP_COMMAND/HERMES_COPILOT_ACP_ARGS(defaultscopilot/--acp --stdio). - The
anthropicprovider (aliasesclaude,claude-code) supports API-key auth viaANTHROPIC_API_KEY(pay-per-token), OAuth viahermes model(only on a Claude Max plan with purchased extra-usage credits), and legacy setup-token auth viaANTHROPIC_TOKEN; Hermes prefers Claude Code's own credential store over copying the token into~/.hermes/.envand auto-detects existing Claude Code credential files. - An active Copilot subscription for direct mode, or the Copilot CLI plus
copilot loginfor ACP mode. - A Codex / OpenAI coding-plan account for the device-code flow.
- For Claude Max, the plan must include purchased extra-usage credits (plain Max without extra usage won't OAuth), or an
ANTHROPIC_API_KEYfor the pay-per-token path.
How to use
Hermes ships first-class provider IDs for the three major coding-tool backends, each matching the subscription's native auth method.
The openai-codex provider authenticates by device code (open a URL, enter a code) with no Codex CLI install required; credentials land in ~/.hermes/auth.json and can be imported from ~/.codex/auth.json. On refresh failure (HTTP 4xx / invalid_grant) it marks the refresh token dead, and you re-login with hermes auth add codex-oauth.
Token-type restrictions are real: Copilot's direct API rejects classic ghp_* PATs, so use a fine-grained PAT or an OAuth/App token instead of debugging a 401 on a classic PAT.
On Copilot, the 401 one-shot recovery (re-resolves the token, rebuilds the client, retries once) means a transient auth blip won't kill your session; a persistent 401 means the token is actually invalid and you re-run gh auth login.
Claude Max OAuth is conditional on plans with extra-usage credits; if hermes model OAuth fails and you're on plain Max, fall back to an API key.
ACP-mode Copilot (copilot-acp, which spawns the local Copilot CLI subprocess speaking ACP) differs from direct-API Copilot (copilot, an HTTP client): direct API is simpler, while ACP is useful when you want the CLI's own session/auth handling.
Mid-session switching via /model copilot:gpt-5.4 and /model anthropic:claude-sonnet-4-6 lets you spend cheap tokens for routine work and reserve your subscription's quota-billed models for the hard parts.
Set up GitHub Copilot (direct): easiest is to let Hermes reuse your gh auth token by running gh auth login once if not already logged in, then point the provider at copilot in ~/.hermes/config.yaml.
# easiest: let Hermes reuse your gh login
gh auth login # once, if not already
# ~/.hermes/config.yaml
model:
provider: "copilot"
default: "gpt-5.4"
Set up OpenAI Codex (device-code OAuth): run hermes model and choose OpenAI Codex to start the device-code flow in your browser, or import an existing Codex login by copying credentials from ~/.codex/auth.json into ~/.hermes/auth.json.
hermes model # → "OpenAI Codex" → device-code flow in browser
# or import an existing Codex login:
# credentials copied from ~/.codex/auth.json into ~/.hermes/auth.json
If the Codex refresh token dies later, re-authenticate with hermes auth add codex-oauth.
hermes auth add codex-oauth
Set up Anthropic / Claude Max: run hermes model and choose Anthropic for OAuth (needs Claude Max with extra-usage credits), or export ANTHROPIC_API_KEY to use an API key instead, then set the provider to anthropic in ~/.hermes/config.yaml.
hermes model # → "Anthropic" → OAuth (needs Claude Max + extra-usage credits)
# or API key:
# export ANTHROPIC_API_KEY=sk-ant-...
# ~/.hermes/config.yaml
model:
provider: "anthropic"
default: "claude-sonnet-4-6"
Source: aliaihub/awesome-hermes-usecases and its contributors. License: CC-BY-4.0. Source license notice.
Translation and editorial adaptation by ClawCases.
>Resources
>Related Use Cases
Agent Merge-Conflict Arbiter
Resolve a git merge conflict between two agents' branches as an impartial third party: a neutral arbiter that takes both diffs and their stated intents and produces a merged result without overwriting either side.
Autonomous Project Management with Subagents
Coordinate projects autonomously: a main agent delegates work to PM subagents that track tasks in a shared STATE.yaml, update it as they progress, pick up unblocked work in parallel, and keep all task state in version-controlled files.
Email from the shell with Himalaya
Himalaya lets you manage IMAP/SMTP email from the shell, from reading and searching messages to writing, sending, replying, forwarding and organizing mail.