Tokenmaxer

Hermes

Point Hermes at a Tokenmaxer access token.

Before you start

  • Hermes installed, with hermes on your PATH. The setup script configures a harness; it does not install one. Install Hermes →
  • Node.js 18 or newer, which the setup script runs on.
  • A Tokenmaxer API key. Create one →

Run the setup script

Run this, pick Hermes, and paste your key when it asks. It writes the configuration below for you, backing up anything it touches.

Terminal
curl -fsSL https://tokenmaxer.dev/setup.sh | bash

To skip the menu, pass the harness: curl -fsSL https://tokenmaxer.dev/setup.sh | bash -s -- hermes. Run it again after connecting another provider plan to refresh the available models, or curl -fsSL https://tokenmaxer.dev/setup.sh | bash -s -- --undo to put your files back.

Test it

Terminal
hermes -z 'hello'

A reply from the configured default. `hermes doctor` will warn about the vendor prefix; ignore it.

Configure it manually

This is what the setup script writes, for anyone who would rather edit the files themselves. Replace<YOUR_KEY> with your Tokenmaxer access token.

  • The top-level key is `model:`, not `llm:`

    A custom provider also needs `key_env` rather than an inline secret.

  • The prompt flag is `-z`

    `-p` is a subcommand selector in Hermes, not a prompt flag.

  • Set each model's context length

    Hermes automatically compresses the conversation when it reaches 50% of the configured context length. The generated `context_length` values keep compression from triggering against Hermes's smaller default window.

~/.hermes/.env

Hermes reads the key from an environment variable; a custom provider cannot hold it inline.

~/.hermes/.env
TOKENMAXER_ACCESS_TOKEN=<YOUR_KEY>

Claude models

~/.hermes/config.yaml

Adds Tokenmaxer as a custom provider.

~/.hermes/config.yaml
custom_providers:
  - name: tokenmaxer
    base_url: https://api.tokenmaxer.dev/v1
    key_env: TOKENMAXER_ACCESS_TOKEN
    api_mode: chat_completions
    model: anthropic/claude-sonnet-5-5
    models:
      anthropic/claude-opus-5-5:
        context_length: 1000000
        supports_vision: true
      anthropic/claude-sonnet-5-5:
        context_length: 1000000
        supports_vision: true
      anthropic/claude-fable-5-1:
        context_length: 1000000
        supports_vision: true
      anthropic/claude-haiku-5-5:
        context_length: 1000000
        supports_vision: true

~/.hermes/config.yaml

Optional

Makes Tokenmaxer the default. Skip it to leave your current default alone.

~/.hermes/config.yaml
model:
  provider: tokenmaxer
  default: anthropic/claude-sonnet-5-5

ChatGPT models

~/.hermes/config.yaml

A second provider on the Responses transport, so Codex requests keep their native shape.

~/.hermes/config.yaml
custom_providers:
  - name: tokenmaxer-codex
    base_url: https://api.tokenmaxer.dev/v1
    key_env: TOKENMAXER_ACCESS_TOKEN
    api_mode: codex_responses
    model: openai/gpt-5.6-terra
    models:
      openai/gpt-6.1-sol:
        context_length: 872000
        supports_vision: true
      openai/gpt-6-astra:
        context_length: 872000
        supports_vision: true
      openai/gpt-6-sol:
        context_length: 872000
        supports_vision: true
      openai/gpt-6-luna:
        context_length: 872000
        supports_vision: true
      openai/gpt-5.6-terra:
        context_length: 872000
        supports_vision: true
      openai/gpt-5.6-luna:
        context_length: 872000
        supports_vision: true

~/.hermes/config.yaml

Optional

Makes Tokenmaxer the default. Skip it to leave your current default alone.

~/.hermes/config.yaml
model:
  provider: tokenmaxer-codex
  default: openai/gpt-5.6-terra