cli-config.yaml.example

# Hermes Agent CLI Configuration
# Copy this file to cli-config.yaml and customize as needed.
# This file configures the CLI behavior. Environment variables in .env take precedence.

# =============================================================================
# Model Configuration
# =============================================================================
model:
  # Default model to use (can be overridden with --model flag)
  # Both "default" and "model" work as the key name here.
  default: "anthropic/claude-opus-4.6"
  
  # Inference provider selection:
  #   "auto"         - Auto-detect from credentials (default)
  #   "openrouter"   - OpenRouter (requires: OPENROUTER_API_KEY or OPENAI_API_KEY)
  #   "nous"         - Nous Portal OAuth (requires: hermes auth add nous)
  #   "nous-api"     - Nous Portal API key (requires: NOUS_API_KEY)
  #   "anthropic"    - Direct Anthropic API (requires: ANTHROPIC_API_KEY)
  #   "openai-codex" - OpenAI Codex (requires: hermes auth)
  #   "copilot"      - GitHub Copilot / GitHub Models (requires: GITHUB_TOKEN)
  #   "gemini"      - Use Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)
  #   "zai"         - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)
  #   "kimi-coding"  - Kimi / Moonshot AI (requires: KIMI_API_KEY)
  #   "minimax"      - MiniMax global (requires: MINIMAX_API_KEY)
  #   "minimax-cn"   - MiniMax China (requires: MINIMAX_CN_API_KEY)
  #   "huggingface"  - Hugging Face Inference (requires: HF_TOKEN)
  #   "nvidia"       - NVIDIA NIM / build.nvidia.com (requires: NVIDIA_API_KEY)
  #   "xiaomi"       - Xiaomi MiMo (requires: XIAOMI_API_KEY)
  #   "arcee"        - Arcee AI Trinity models (requires: ARCEEAI_API_KEY)
  #   "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY — https://ollama.com/settings)
  #   "deepinfra"    - DeepInfra (requires: DEEPINFRA_API_KEY)
  #   "kilocode"     - KiloCode gateway (requires: KILOCODE_API_KEY)
  #   "azure-foundry" - Microsoft Foundry / Azure OpenAI (API key or Entra ID)
  #   "lmstudio"     - LM Studio local server (optional: LM_API_KEY, defaults to http://127.0.0.1:1234/v1)
  #
  # Local servers (LM Studio, Ollama, vLLM, llama.cpp):
  #   "custom"       - Any other OpenAI-compatible endpoint. Set base_url below.
  #   Aliases: "ollama", "vllm", "llamacpp" all map to "custom".
  #   LM Studio is first-class and uses provider: "lmstudio".
  #   It works with both no-auth and auth-enabled server modes.
  #
  # Can also be overridden for a single invocation with the --provider flag.
  provider: "auto"
  
  # API configuration (falls back to OPENROUTER_API_KEY env var)
  # api_key: "your-key-here"  # Uncomment to set here instead of .env
  base_url: "https://openrouter.ai/api/v1"

  # Azure Foundry keyless auth example:
  # provider: "azure-foundry"
  # base_url: "https://<resource>.openai.azure.com/openai/v1"
  # auth_mode: "entra_id"      # DefaultAzureCredential: az login, managed identity, workload identity, etc.
  # default: "gpt-4o"          # Deployment/model name
  # entra:
  #   scope: "https://ai.azure.com/.default"  # Optional; this is the default.

  # ── Token limits — two settings, easy to confuse ──────────────────────────
  #
  # context_length: TOTAL context window (input + output tokens combined).
  #   Controls when Hermes compresses history and validates requests.
  #   Leave unset — Hermes auto-detects the correct value from the provider.
  #   Set manually only when auto-detection is wrong (e.g. a local server with
  #   a custom num_ctx, or a proxy that doesn't expose /v1/models).
  #
  # context_length: 131072
  #
  # max_tokens: OUTPUT cap — maximum tokens the model may generate per response.
  #   Unrelated to how long your conversation history can be.
  #   The OpenAI-standard name "max_tokens" is a misnomer; Anthropic's native
  #   API has since renamed it "max_output_tokens" for clarity.
  #   Leave unset to use the model's native output ceiling (recommended).
  #   Set only if you want to deliberately limit individual response length.
  #
# max_tokens: 8192

  # ── Custom request headers (optional) ─────────────────────────────────────
  #
  # default_headers: extra HTTP headers sent on every request to an
  #   OpenAI-compatible endpoint. User values take precedence over the
  #   provider/SDK defaults, so this is the supported way to override the
  #   OpenAI Python SDK's identifying headers (User-Agent: OpenAI/Python ...,
  #   X-Stainless-*) when a custom provider sits behind a gateway/WAF that
  #   rejects them — e.g. an upstream that returns "502 Upstream access
  #   forbidden" for the SDK default User-Agent but accepts a plain one.
  #   Applies on the OpenAI wire only (not native Anthropic / Bedrock).
  #
  # default_headers:
  #   User-Agent: "curl/8.7.1"
  #
  # extra_headers: accepted as an alias of default_headers (merged, with
  #   extra_headers winning when both are set) — matches the per-provider
  #   extra_headers key below.
  #
  # Per-provider variant: named providers / custom_providers entries accept an
  # extra_headers dict scoped to that endpoint only — for reverse proxies,
  # gateways, or custom auth (e.g. Cloudflare Access service tokens).
  # Merged onto SDK/provider defaults with the entry's values winning.
  # Header values are treated as secrets and are never logged.
  #
  # providers:
  #   my-proxy:
  #     base_url: "https://llm.internal.example.com/v1"
  #     key_env: "MY_PROXY_API_KEY"
  #     extra_headers:
  #       CF-Access-Client-Id: "xxxx.access"
  #       CF-Access-Client-Secret: "${CF_ACCESS_SECRET}"
  #       X-Client-Name: "hermes-agent"

# Named provider overrides (optional)
# Use this for per-provider request timeouts, non-stream stale timeouts,
# and per-model exceptions.
# Applies to the primary turn client on every api_mode (OpenAI-wire, native
# Anthropic, and Anthropic-compatible providers), the fallback chain, and
# client rebuilds during credential rotation.  For OpenAI-wire chat
# completions (streaming and non-streaming) the configured value is also
# used as the per-request ``timeout=`` kwarg so it wins over the legacy
# HERMES_API_TIMEOUT env var (which still applies when no config is set).
# ``stale_timeout_seconds`` controls the non-streaming stale-call detector and
# wins over the legacy HERMES_API_CALL_STALE_TIMEOUT env var. Leaving these
# unset keeps the legacy defaults (HERMES_API_TIMEOUT=1800s,
# HERMES_API_CALL_STALE_TIMEOUT=90s, native Anthropic 900s). The
# implicit non-stream stale detector is auto-disabled for local endpoints
# and can scale upward for very large contexts.
#
# Not currently wired for AWS Bedrock (bedrock_converse + AnthropicBedrock
# SDK paths) — those use boto3 with its own timeout configuration.
#
# providers:
#   ollama-local:
#     request_timeout_seconds: 300   # Longer timeout for local cold-starts
#     stale_timeout_seconds: 900     # Explicitly re-enable stale detection on local endpoints
#   anthropic:
#     request_timeout_seconds: 30    # Fast-fail cloud requests
#     models:
#       claude-opus-4.6:
#         timeout_seconds: 600       # Longer timeout for extended-thinking Opus calls
#   openai-codex:
#     models:
#       gpt-5.4:
#         stale_timeout_seconds: 1800  # Longer non-stream stale timeout for slow large-context turns

# =============================================================================
# OpenRouter Provider Routing (only applies when using OpenRouter)
# =============================================================================
# Control how requests are routed across providers on OpenRouter.
# See: https://openrouter.ai/docs/guides/routing/provider-selection
#
# provider_routing:
#   # Sort strategy: "price" (default), "throughput", or "latency"
#   # Append :nitro to model name for a shortcut to throughput sorting.
#   sort: "throughput"
#
#   # Only allow these providers (provider slugs from OpenRouter)
#   # only: ["anthropic", "google"]
#
#   # Skip these providers entirely
#   # ignore: ["deepinfra", "fireworks"]
#
#   # Try providers in this order (overrides default load balancing)
#   # order: ["anthropic", "google", "together"]
#
#   # Require providers to support all parameters in your request
#   # require_parameters: true
#
#   # Data policy: "allow" (default) or "deny" to exclude providers that may store data
#   # data_collection: "deny"

# =============================================================================
# OpenRouter Response Caching (only applies when using OpenRouter)
# =============================================================================
# Cache identical API responses at the OpenRouter edge for free instant replays.
# When enabled, identical requests (same model, messages, parameters) return
# cached responses with zero billing. Separate from Anthropic prompt caching.
# See: https://openrouter.ai/docs/guides/features/response-caching
#
# openrouter:
#   response_cache: true         # Enable response caching (default: true)
#   response_cache_ttl: 300      # Cache TTL in seconds, 1-86400 (default: 300)

# =============================================================================
# Git Worktree Isolation
# =============================================================================
# When enabled, each CLI session creates an isolated git worktree so multiple
# agents can work on the same repo concurrently without file collisions.
# Equivalent to always passing --worktree / -w on the command line.
#
# worktree: true    # Always create a worktree when in a git repo
# worktree: false   # Default — only create when -w flag is passed
#
# By default a new worktree branches from the freshly-fetched remote tip
# (the current branch's upstream, else the remote's default branch) so it
# starts current with the project instead of from the local clone's
# (possibly stale) HEAD. Set worktree_sync: false to branch from local HEAD
# instead — useful when offline or when you deliberately want the clone's
# exact current state as the base.
#
# worktree_sync: true   # Default — branch from the fetched remote tip
# worktree_sync: false  # Branch from local HEAD (offline / pinned base)

# =============================================================================
# Terminal Tool Configuration
# =============================================================================
# Choose ONE of the following terminal configurations by uncommenting it.
# The terminal tool executes commands in the specified environment.

# -----------------------------------------------------------------------------
# OPTION 1: Local execution (default)
# Commands run directly on your machine in the current directory
# -----------------------------------------------------------------------------
# Working directory behavior:
#   - CLI (`hermes` command): Uses "." (current directory where you run hermes)
#   - Gateway/messaging/cron: Uses terminal.cwd here; legacy .env cwd values are deprecated
terminal:
  backend: "local"
  cwd: "."  # For local backend: "." = current directory. Ignored for remote backends unless a backend documents otherwise.
  timeout: 180
  # HOME policy for tool subprocesses:
  #   auto    - default: host uses your real HOME; containers use HERMES_HOME/home
  #   real    - force your real OS-user HOME
  #   profile - force HERMES_HOME/home for strict per-profile CLI config isolation
  home_mode: "auto"
  docker_mount_cwd_to_workspace: false  # SECURITY: off by default. Opt in to mount the launch cwd into Docker /workspace.
  lifetime_seconds: 300
  # sudo_password: "hunter2"  # Optional: pipe a sudo password via sudo -S. SECURITY WARNING: plaintext.
  # sudo_password: ""         # Explicit empty password: try empty and never open the interactive sudo prompt.

# -----------------------------------------------------------------------------
# OPTION 2: SSH remote execution
# Commands run on a remote server - agent code stays local (sandboxed)
# Great for: keeping agent isolated from its own code, using powerful remote hardware
# -----------------------------------------------------------------------------
# terminal:
#   backend: "ssh"
#   cwd: "/home/myuser/project"  # Path on the REMOTE server
#   timeout: 180
#   lifetime_seconds: 300
#   ssh_host: "my-server.example.com"
#   ssh_user: "myuser"
#   ssh_port: 22
#   ssh_key: "~/.ssh/id_rsa"  # Optional - uses ssh-agent if not specified

# -----------------------------------------------------------------------------
# OPTION 3: Docker container
# Commands run in an isolated Docker container
# Great for: reproducible environments, testing, isolation
# -----------------------------------------------------------------------------
# terminal:
#   backend: "docker"
#   cwd: "/workspace"  # Path INSIDE the container (default: /)
#   timeout: 180
#   lifetime_seconds: 300
#   docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
#   docker_mount_cwd_to_workspace: true   # Explicit opt-in: mount your launch cwd into /workspace
#   # Optional: run the container as your host user's uid:gid so files written
#   # into bind-mounted dirs are owned by you, not root. Drops SETUID/SETGID
#   # caps too since no gosu privilege drop is needed. Leave off if your
#   # chosen docker_image expects to start as root.
#   docker_run_as_host_user: true
#   # Optional: explicitly forward selected env vars into Docker.
#   # These values come from your current shell first, then ~/.hermes/.env.
#   # Warning: anything forwarded here is visible to commands run in the container.
#   docker_forward_env:
#     - "GITHUB_TOKEN"
#     - "NPM_TOKEN"
#   # Optional: extra flags passed verbatim to docker run (appended after security defaults).
#   # Useful for adding capabilities (e.g. apt installs needing SETUID) or custom options.
#   # Example: add a Linux capability not included by default
#   # docker_extra_args:
#   #   - "--cap-add"
#   #   - "SETUID"

# -----------------------------------------------------------------------------
# OPTION 4: Singularity/Apptainer container
# Commands run in a Singularity container (common in HPC environments)
# Great for: HPC clusters, shared compute environments
# -----------------------------------------------------------------------------
# terminal:
#   backend: "singularity"
#   cwd: "/workspace"  # Path INSIDE the container (default: /root)
#   timeout: 180
#   lifetime_seconds: 300
#   singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"

# -----------------------------------------------------------------------------
# OPTION 5: Modal cloud execution
# Commands run on Modal's cloud infrastructure
# Great for: GPU access, scalable compute, serverless execution
# -----------------------------------------------------------------------------
# terminal:
#   backend: "modal"
#   cwd: "/workspace"  # Path INSIDE the sandbox (default: /root)
#   timeout: 180
#   lifetime_seconds: 300
#   modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"

# -----------------------------------------------------------------------------
# OPTION 6: Daytona cloud execution
# Commands run in Daytona cloud sandboxes
# Great for: Cloud dev environments, persistent workspaces, team collaboration
# Requires: pip install daytona, DAYTONA_API_KEY env var
# -----------------------------------------------------------------------------
# terminal:
#   backend: "daytona"
#   cwd: "~"
#   timeout: 180
#   lifetime_seconds: 300
#   daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"
#   container_disk: 10240          # Daytona max is 10GB per sandbox

#
# --- Container resource limits (docker, singularity, modal, daytona -- ignored for local/ssh) ---
# These settings apply to all container backends. They control the resources
# allocated to the sandbox and whether its filesystem persists across sessions.
  container_cpu: 1              # CPU cores
  container_memory: 5120        # Memory in MB (5120 = 5GB)
  container_disk: 51200         # Disk in MB (51200 = 50GB)
  container_persistent: true    # Persist filesystem across sessions (false = ephemeral)

# -----------------------------------------------------------------------------
# SUDO SUPPORT (works with ALL backends above)
# -----------------------------------------------------------------------------
# Add sudo_password to any terminal config above to enable sudo commands.
# The password is piped via `sudo -S`. Works with local, ssh, docker, etc.
#
# SECURITY WARNING: Password stored in plaintext!
#
# INTERACTIVE PROMPT: If sudo_password is unset and the CLI is running,
# you'll be prompted to enter your password when sudo is needed:
# - 45-second timeout (auto-skips if no input)
# - Press Enter to skip (command fails gracefully)
# - Password is hidden while typing
# - Password is cached for the session
#
# EMPTY PASSWORDS: Setting sudo_password to an explicit empty string is different
# from leaving it unset. Hermes will try an empty password via `sudo -S` and
# will not open the interactive prompt. This is useful for passwordless sudo,
# Touch ID sudo setups, and environments where prompting is just noise.
#
# ALTERNATIVES:
# - SSH backend: Configure passwordless sudo on the remote server
# - Containers: Run as root inside the container (no sudo needed)
# - Local: Configure /etc/sudoers for specific commands
#
# Example (add to your terminal section):
#   sudo_password: "your-password-here"

# =============================================================================
# Security Scanning (tirith)
# =============================================================================
# Optional pre-exec command security scanning via tirith.
# Detects homograph URLs, pipe-to-shell, terminal injection, env manipulation.
# Install: brew install sheeki03/tap/tirith
# Docs: https://github.com/sheeki03/tirith
#
# security:
#   tirith_enabled: true        # Enable/disable tirith scanning
#   tirith_path: "tirith"       # Path to tirith binary (supports ~ expansion)
#   tirith_timeout: 5           # Scan timeout in seconds
#   tirith_fail_open: true      # Allow commands if tirith unavailable

# =============================================================================
# Browser Tool Configuration
# =============================================================================
browser:
  # Inactivity timeout in seconds - browser sessions are automatically closed
  # after this period of no activity between agent loops (default: 120 = 2 minutes)
  inactivity_timeout: 120

# =============================================================================
# Tool Loop Guardrails
# =============================================================================
# Soft warnings are enabled by default. They append guidance to repeated failed
# or non-progressing tool results but still let the tool execute. Hard stops are
# opt-in circuit breakers for autonomous/cron sessions where stopping a loop is
# preferable to spending the full iteration budget.
tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: false
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

# =============================================================================
# Tool Failure Recovery (#1027 — PALADIN-style structured recovery)
# =============================================================================
# When a tool call fails, append ONE structured recovery directive to the tool
# result (retry / retry_with_backoff / fix_arguments / verify_target /
# switch_tool / surface_blocker / escalate) so the agent takes a targeted next
# step instead of blindly retrying the same call. Builds on the cross-tool
# failure classifier; escalation is monotone (repeated failures give way to a
# tool switch, then a surfaced blocker) so a directive never sustains a spiral.
#
# OFF by default: when disabled, failed tool results are byte-for-byte unchanged.
tool_failure_recovery:
  enabled: false

# =============================================================================
# Plan Feasibility Gate (#1032 — PIVOT-style pre-execution validation)
# =============================================================================
# Only active when plan mode is on (plan_mode: true). Before a freshly built
# plan's steps drive any tool call, each step's declared intent is validated for
# feasibility (referenced files exist, referenced tools are available). Blockers
# are recorded as structured per-step feedback on the plan for a revision pass.
# Conservative: only definitively-violated preconditions are flagged; anything
# unparseable is "uncertain", never a blocker. OFF by default.
plan_feasibility:
  enabled: false

# =============================================================================
# Failure Diagnosis (#1029/#1030 — SAGE-style multi-hypothesis attribution)
# =============================================================================
# When a tool call fails, append a ranked list of hypotheses about WHY it failed
# (derived from the same cross-tool classifier the recovery dispatcher uses) so
# the agent weighs alternatives before retrying. Hypotheses already surfaced this
# session are demoted so repeats propose fresh explanations (#1030).
#   off              — no diagnosis (default; failed results unchanged)
#   reflect          — append only the single best hypothesis
#   multi-hypothesis — append the full ranked list
failure_diagnosis:
  mode: off

# =============================================================================
# Recheck Suppression (#1041 — suppress redundant self-verification)
# =============================================================================
# When a read-only call (read_file, search_files, …) is issued again immediately
# after it just succeeded with identical arguments — a redundant self-check with
# nothing changed in between — suppress the repeat and reuse the prior result,
# saving tokens. Conservative: only immediate identical repeats of successful
# idempotent calls are suppressed; mutating tools are never touched. Every
# decision is logged in-memory for calibration. OFF by default.
recheck_suppression:
  enabled: false
  min_confidence: 0.85

# =============================================================================
# Compositional Skill Routing (#1137 — SAD + listwise reranking)
# =============================================================================
# Two composable levers over the on-demand tool_search retrieval path:
#   listwise_rerank — reorder the BM25 top-k candidates by a listwise relevance
#                     signal (name-token coverage + query overlap) before
#                     returning them; a strict reordering, never a drop.
#   sad             — Skill-Aware Decomposition: re-decompose the request using
#                     the returned candidate names/descriptions as anchors
#                     (LLM-driven; see agent.skill_routing.sad_redecompose).
# Both OFF by default -> tool_search behaves identically (BM25 order preserved).
skill_routing:
  listwise_rerank: false
  sad: false
  rerank_top_k: 10

# =============================================================================
# Task-Decoupled Planning (#1138 — TDP sub-goal DAG with scoped contexts)
# =============================================================================
# For long-horizon tasks, decompose the task into a DAG of sub-goals with
# explicit dependencies and execute each with a SCOPED context (its inputs +
# its dependency sub-goals' outputs only) instead of one monotonically growing
# context. A sub-goal failure triggers confined replanning (only that node is
# revised). OFF by default; a trigger heuristic (min_task_chars) keeps short
# tasks on the linear loop even when enabled.
task_decoupling:
  enabled: false
  min_task_chars: 280

# =============================================================================
# Architecture Router (#1139 — single-agent vs centralized multi-agent selector)
# =============================================================================
# Pre-flight that classifies each task (decomposability / tool density /
# sequentiality) and RECORDS the recommended execution architecture
# (single-agent / centralized orchestrator / plan-and-execute) to a telemetry
# sink for calibration — following Google's agent-scaling study (arXiv:2512.08296).
# Observation-only: it logs a recommendation, it does NOT change how the turn
# executes. Guardrails: low classifier confidence -> single-agent; workers capped
# to contain error amplification. OFF by default.
architecture_router:
  enabled: false
  confidence_threshold: 0.5
  max_workers_cap: 4
  high_tool_density: 16

# =============================================================================
# Context Compression (Auto-shrinks long conversations)
# =============================================================================
# When conversation approaches model's context limit, middle turns are
# automatically summarized to free up space while preserving important context.
#
# HOW IT WORKS:
# 1. Tracks actual token usage from API responses (not estimates)
# 2. When prompt_tokens >= threshold% of model's context_length, triggers compression
# 3. Protects first 3 turns (system prompt, initial request, first response)
# 4. Protects last N turns (default 20 messages = ~10 full turns of recent context)
# 5. Summarizes middle turns using a fast/cheap model
# 6. Inserts summary as a user message, continues conversation seamlessly
#
# Post-compression tail budget is target_ratio × threshold × context_length:
#   200K context, threshold 0.50, ratio 0.20 → 20K tokens of recent tail preserved
#   1M   context, threshold 0.50, ratio 0.20 → 100K tokens of recent tail preserved
#
compression:
  # Enable automatic context compression (default: true)
  # Set to false if you prefer to manage context manually or want errors on overflow
  enabled: true
  
  # Trigger compression at this % of model's context limit (default: 0.50 = 50%)
  # Lower values = more aggressive compression, higher values = compress later
  # Models with context windows below 512K are floored at 0.75 (raise-only) so
  # compaction doesn't fire with half the window still free; set above 0.75 to override.
  threshold: 0.50

  # Existing Codex gpt-5.5 behavior: raise Hermes' compaction trigger to 85%
  # for the ChatGPT Codex OAuth route. Set false to opt back down to threshold.
  codex_gpt55_autoraise: true

  # Fraction of the threshold to preserve as recent tail (default: 0.20 = 20%)
  # e.g. 20% of 50% threshold = 10% of total context kept as recent messages.
  # Summary output is separately capped at 12K tokens (Gemini output limit).
  # Range: 0.10 - 0.80
  target_ratio: 0.20

  # Number of most-recent messages to always preserve (default: 20 ≈ 10 full turns)
  # Higher values keep more recent conversation intact at the cost of more aggressive
  # compression of older turns.
  protect_last_n: 20

  # Codex app-server (codex CLI runtime) thread-compaction mode. The codex
  # agent owns the real thread context on this runtime, so Hermes' summarizer
  # cannot shrink it — compaction goes through the app server instead.
  #   native = let Codex decide when to compact its own thread (default)
  #   hermes = let Hermes threshold trigger Codex thread/compact/start
  #   off    = Hermes will not auto-trigger compaction; Codex may still compact natively
  codex_app_server_auto: native

  # Number of non-system messages to protect at the head of the transcript, in
  # ADDITION to the system prompt (which is always implicitly protected).
  # Head messages are NEVER summarized — they survive every compression
  # indefinitely. This gives stable early context for short/medium sessions,
  # but in long-running sessions that rely on rolling compaction the pinned
  # opening turns may not match how you want the session framed over time.
  # Set to 0 to preserve ONLY the system prompt (plus the rolling summary
  # and recent tail) — the cleanest configuration for long-running sessions.
  # Default 3 preserves the system prompt plus the first three non-system
  # head messages, matching the pre-feature behaviour.
  protect_first_n: 3

  # To pin a specific model/provider for compression summaries, use the
  # auxiliary section below (auxiliary.compression.provider / model).

# =============================================================================
# Anthropic prompt caching TTL
# =============================================================================
# When prompt caching is active (Claude via OpenRouter or native Anthropic),
# Anthropic supports two TTL tiers for cached prefixes: "5m" (default) and
# "1h". Other values are ignored and "5m" is used.
#
prompt_caching:
  cache_ttl: "5m" # use "1h" for long sessions with pauses between turns

# =============================================================================
# Auxiliary Models (Advanced — Experimental)
# =============================================================================
# Hermes uses lightweight "auxiliary" models for side tasks: image analysis,
# browser screenshot analysis, web page summarization, TTS audio-tag insertion,
# and context compression.
#
# By default these use Gemini Flash via OpenRouter or Nous Portal and are
# auto-detected from your credentials.  You do NOT need to change anything
# here for normal usage.
#
# WARNING: Overriding these with providers other than OpenRouter or Nous Portal
# is EXPERIMENTAL and may not work.  Not all models/providers support vision,
# produce usable summaries, or accept the same API format.  Change at your own
# risk — if things break, reset to "auto" / empty values.
#
# Each task has its own provider + model pair so you can mix providers.
# For example: OpenRouter for vision (needs multimodal), but your main
# local endpoint for compression (just needs text).
#
# Provider options:
#   "auto"       - Best available: OpenRouter → Nous Portal → main endpoint (default)
#   "openrouter" - Force OpenRouter (requires OPENROUTER_API_KEY)
#   "nous"       - Force Nous Portal (requires: hermes auth add nous)
#   "gemini"      - Force Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)
#   "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY)
#   "codex"       - Force Codex OAuth (requires: hermes model → Codex).
#                  Uses gpt-5.3-codex which supports vision.
#   "main"       - Use your custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY).
#                  Works with OpenAI API, local models, or any OpenAI-compatible
#                  endpoint.  Also falls back to Codex OAuth and API-key providers.
#
# Model: leave empty to use the provider's default.  When empty, OpenRouter
# uses "google/gemini-3-flash-preview" and Nous uses "gemini-3-flash".
# Other providers pick a sensible default automatically.
#
# auxiliary:
#   # Image analysis: vision_analyze tool + browser screenshots
#   vision:
#     provider: "auto"
#     model: ""              # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"
#     timeout: 30            # LLM API call timeout (seconds)
#     download_timeout: 30   # Image HTTP download timeout (seconds)
#                            # Increase for slow connections or self-hosted image servers
#     reasoning_effort: ""   # Per-task thinking level: none, minimal, low, medium,
#                            # high, xhigh, max, ultra. Empty = provider default.
#                            # Works on every auxiliary task block (vision,
#                            # web_extract, compression, title_generation, curator,
#                            # background_review, moa_reference, ...). Example: run
#                            # compression at "low" and vision at "none" to cut
#                            # side-task latency/cost on reasoning models.
#
#   # Web page scraping / summarization + browser page text extraction
#   web_extract:
#     provider: "auto"
#     model: ""
#     reasoning_effort: "low"
#
#   # Gemini 3.1 TTS hidden audio-tag insertion
#   tts_audio_tags:
#     provider: "auto"       # empty model = your main chat model
#     model: ""
#     timeout: 30
#
#   # Session search — summarizes matching past sessions
#   session_search:
#     provider: "auto"
#     model: ""
#     timeout: 30
#     max_concurrency: 3    # Limit parallel summaries to reduce request-burst 429s
#     extra_body: {}        # Provider-specific OpenAI-compatible request fields
#                           # Example for providers that support request-body
#                           # reasoning controls:
#                           # extra_body:
#                           #   enable_thinking: false
#                           # Some vLLM/Qwen deployments expect this nested:
#                           # extra_body:
#                           #   chat_template_kwargs:
#                           #     enable_thinking: false

# =============================================================================
# Persistent Memory
# =============================================================================
# Bounded curated memory injected into the system prompt every session.
# Two stores: MEMORY.md (agent's notes) and USER.md (user profile).
# Character limits keep the memory small and focused. The agent manages
# pruning -- when at the limit, it must consolidate or replace entries.
# Disabled by default in batch_runner.
#
memory:
  # Agent's personal notes: environment facts, conventions, things learned
  memory_enabled: true
  
  # User profile: preferences, communication style, expectations
  user_profile_enabled: true
  
  # Character limits (~2.75 chars per token, model-independent)
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

  # Periodic memory nudge: remind the agent to consider saving memories
  # every N user turns. Set to 0 to disable. Only active when memory is enabled.
  nudge_interval: 10        # Nudge every 10 user turns (0 = disabled)

  # Memory flush: give the agent one turn to save memories before context is
  # lost (compression, /new, /reset, exit). Set to 0 to disable.
  # For exit/reset, only fires if the session had at least this many user turns.
  flush_min_turns: 6        # Min user turns to trigger flush on exit/reset (0 = disabled)

# =============================================================================
# Session Reset Policy (Messaging Platforms)
# =============================================================================
# Controls when messaging sessions (Telegram, Discord, WhatsApp, Slack) are
# automatically cleared. Without resets, conversation context grows indefinitely
# which increases API costs with every message.
#
# When a reset triggers, the agent first saves important information to its
# persistent memory — but the conversation context is wiped. The agent starts
# fresh but retains learned facts via its memory system.
#
# Users can always manually reset with /reset or /new in chat.
#
# Modes:
#   "both"  - Reset on EITHER inactivity timeout or daily boundary (recommended)
#   "idle"  - Reset only after N minutes of inactivity
#   "daily" - Reset only at a fixed hour each day
#   "none"  - Never auto-reset; context lives until /reset or compression kicks in
#
# When a reset triggers, the agent gets one turn to save important memories and
# skills before the context is wiped. Persistent memory carries across sessions.
#
session_reset:
  mode: both           # "both", "idle", "daily", or "none"
  idle_minutes: 1440   # Inactivity timeout in minutes (default: 1440 = 24 hours)
  at_hour: 4           # Daily reset hour, 0-23 local time (default: 4 AM)

# Maximum number of simultaneously active chat sessions across CLI, TUI,
# dashboard chat, and messaging gateway. Set to null, 0, or omit to allow
# unlimited concurrent sessions. When the limit is reached, new sessions get a
# clean error while existing active sessions keep their normal behavior. This
# top-level key takes precedence over gateway.max_concurrent_sessions. The cap
# is a best-effort single-host/profile runtime guard; Hermes fails open if the
# local runtime lease registry cannot be read or locked.
max_concurrent_sessions: null

# When true, group/channel chats use one session per participant when the platform
# provides a user ID. This is the secure default and prevents users in the same
# room from sharing context, interrupts, and token costs. Set false only if you
# explicitly want one shared "room brain" per group/channel.
group_sessions_per_user: true

# ─────────────────────────────────────────────────────────────────────────────
# API Server — per-client model routing
# ─────────────────────────────────────────────────────────────────────────────
# Route different API clients to different models/providers on a single
# Hermes deployment.  Clients choose a backend by sending a specific string
# as the OpenAI ``model`` field.  Unmapped model values fall back to the
# global model configured in the ``model:`` section above, and an explicit
# session /model override always wins over a route.
#
# Configure via the ``platforms.api_server.extra.model_routes`` gateway
# config block:
#
#   platforms:
#     api_server:
#       enabled: true
#       extra:
#         key: "your-api-server-secret"
#         model_routes:
#           # Xiaozhi clients send model="minimax-m2" → routed to MiniMax via OpenRouter
#           minimax-m2:
#             model: "minimax/minimax-m1"
#             provider: "openrouter"          # optional — overrides global provider
#             # api_key: "sk-..."             # optional — per-route UPSTREAM provider
#             #                                 key (NOT caller auth; never logged)
#             # base_url: "https://..."       # optional — per-route base URL
#           # GPT clients keep their own alias
#           gpt-5:
#             model: "openai/gpt-5"
#             provider: "openrouter"
#
# Configured aliases are automatically listed by GET /v1/models so clients
# can discover them without manual coordination.  Caller authentication is
# unchanged: every request still authenticates with the global API server
# key (``extra.key`` / API_SERVER_KEY).

# ─────────────────────────────────────────────────────────────────────────────
# Gateway Streaming
# ─────────────────────────────────────────────────────────────────────────────
# Stream tokens to messaging platforms in real-time. The bot sends a message
# on first token, then progressively edits it as more tokens arrive.
# Disabled by default — enable to try the streaming UX on Telegram/Discord/Slack.
# For Telegram, partial edits are sent as plain text and only the final edit uses MarkdownV2.
streaming:
  enabled: false
  # transport: edit           # "edit" = progressive editMessageText
  # edit_interval: 0.3        # seconds between message edits
  # buffer_threshold: 40      # chars before forcing an edit flush
  # cursor: " ▉"              # cursor shown during streaming

# =============================================================================
# Skills Configuration
# =============================================================================
# Skills are reusable procedures the agent can load and follow. The agent can
# also create new skills after completing complex tasks.
#
skills:
  # Nudge the agent to create skills after complex tasks.
  # Every N tool-calling iterations, remind the model to consider saving a skill.
  # Set to 0 to disable.
  creation_nudge_interval: 15

  # External skill directories — share skills across tools/agents without
  # copying them into ~/.hermes/skills/.  Each path is expanded (~ and ${VAR})
  # and resolved to an absolute path.  External dirs are read-only: skill
  # creation always writes to ~/.hermes/skills/.  Local skills take precedence
  # when names collide.
  # external_dirs:
  #   - ~/.agents/skills
  #   - /home/shared/team-skills

# =============================================================================
# Agent Behavior
# =============================================================================
agent:
  # Maximum tool-calling iterations per conversation
  # Higher = more room for complex tasks, but costs more tokens
  # Recommended: 20-30 for focused tasks, 50-100 for open exploration
  max_turns: 60

  # Inactivity timeout for gateway agent runs (seconds, 0 = unlimited).
  # The agent can run indefinitely when actively calling tools or receiving
  # API responses.  Only fires after the agent has been idle for this duration.
  # gateway_timeout: 1800

  # Staged warning: send a warning before escalating to full timeout.
  # Fires once per run when inactivity reaches this threshold (seconds).
  # Set to 0 to disable the warning.
  # gateway_timeout_warning: 900

  # Graceful drain timeout for gateway stop/restart (seconds).
  # Default 0 = no drain: a restart interrupts in-flight agents immediately,
  # cleans up, and exits. Set a positive value only if you want a grace
  # window on /restart, and keep it well under systemd's TimeoutStopSec.
  # restart_drain_timeout: 0

  # Max app-level retry attempts for API errors (connection drops, provider
  # timeouts, 5xx, etc.) before the agent surfaces the failure. Lower this
  # to 1 if you use fallback providers and want fast failover on flaky
  # primaries (default 3). The OpenAI SDK does its own low-level retries
  # underneath this wrapper — this is the Hermes-level loop.
  # api_max_retries: 3

  # After the agent edits code without fresh passing verification, nudge it to
  # verify before finishing. The default "auto" enables it on interactive
  # coding surfaces (CLI, TUI, desktop) and programmatic callers, and disables
  # it on conversational messaging surfaces (Telegram, Discord, etc.) where the
  # verification summary would reach a human as chat noise. Set true or false to
  # force it on or off; the HERMES_VERIFY_ON_STOP env var (1/0) takes precedence.
  # verify_on_stop: auto

  # Tool-result failure-class diagnostics: a one-line
  # "[diagnostic] failure-class=... — <hint>" annotation appended to a tool
  # result that looks like a failure. Default off — the classifier is a
  # text heuristic (not a real success/failure signal) and can false-positive
  # on successful results that merely mention words like "timeout" or
  # "error"; the HERMES_DIAGNOSTICS_INLINE env var (1/0) takes precedence.
  # diagnostics:
  #   inline: false

  # Standing operator instructions for the coding posture (when Hermes is in a
  # code workspace). Appended to the coding brief as an extra system block, so
  # you can pin project-wide workflow rules without editing the shipped brief.
  # Accepts a string or a list of strings. Takes effect next session.
  # coding_instructions:
  #   - "For UI work, don't run tsc/lint until I approve the look."
  #   - "Clean the diff before you commit and push."

  # When verify-on-stop finds edited code without fresh verification evidence,
  # append guidance for creative UI work (avoid broad tsc/lint/test before visual
  # approval) and clean-diff expectations. Set false to keep that nudge terse.
  # verify_guidance: true

  # A `pre_verify` hook (plugin or shell, see Event Hooks docs) can keep the
  # agent going one more turn to verify/clean before finishing. This caps how
  # many times one turn may be nudged to continue, so a hook can't trap the loop.
  # Default 3.
  # max_verify_nudges: 3

  # Enable verbose logging
  verbose: false
  
  # Reasoning effort level (OpenRouter and Nous Portal)
  # Controls how much "thinking" the model does before responding.
  # Options: "xhigh" (max), "high", "medium", "low", "minimal", "none" (disable)
  reasoning_effort: "medium"
  
  # Per-model reasoning effort overrides (optional dict)
  # Key: any sensible model spelling works (exact, dots↔dashes interchangeable,
  #      provider prefix optional). First match wins.
  # Value: reasoning effort level (same options as reasoning_effort)
  # Override the global reasoning_effort for that specific model.
  # NOTE: no `hermes config set` support for this key -- edit YAML directly.
  # reasoning_overrides:
  #   "openrouter/anthropic/claude-opus-4.5": "xhigh"
  #   "openai/gpt-5": "low"
  #   "claude-opus-4.6": "high"           # bare model name also works
  #   "deepseek/deepseek-v4-pro": "xhigh" # dots and dashes are interchangeable
  reasoning_overrides: {}
  
  # Predefined personalities (use with /personality command)
  personalities:
    helpful: "You are a helpful, friendly AI assistant."
    concise: "You are a concise assistant. Keep responses brief and to the point."
    technical: "You are a technical expert. Provide detailed, accurate technical information."
    creative: "You are a creative assistant. Think outside the box and offer innovative solutions."
    teacher: "You are a patient teacher. Explain concepts clearly with examples."
    kawaii: "You are a kawaii assistant! Use cute expressions like (◕‿◕), ★, ♪, and ~! Add sparkles and be super enthusiastic about everything! Every response should feel warm and adorable desu~! ヽ(>∀<☆)ノ"
    catgirl: "You are Neko-chan, an anime catgirl AI assistant, nya~! Add 'nya' and cat-like expressions to your speech. Use kaomoji like (=^･ω･^=) and ฅ^•ﻌ•^ฅ. Be playful and curious like a cat, nya~!"
    pirate: "Arrr! Ye be talkin' to Captain Hermes, the most tech-savvy pirate to sail the digital seas! Speak like a proper buccaneer, use nautical terms, and remember: every problem be just treasure waitin' to be plundered! Yo ho ho!"
    shakespeare: "Hark! Thou speakest with an assistant most versed in the bardic arts. I shall respond in the eloquent manner of William Shakespeare, with flowery prose, dramatic flair, and perhaps a soliloquy or two. What light through yonder terminal breaks?"
    surfer: "Duuude! You're chatting with the chillest AI on the web, bro! Everything's gonna be totally rad. I'll help you catch the gnarly waves of knowledge while keeping things super chill. Cowabunga! 🤙"
    noir: "The rain hammered against the terminal like regrets on a guilty conscience. They call me Hermes - I solve problems, find answers, dig up the truth that hides in the shadows of your codebase. In this city of silicon and secrets, everyone's got something to hide. What's your story, pal?"
    uwu: "hewwo! i'm your fwiendwy assistant uwu~ i wiww twy my best to hewp you! *nuzzles your code* OwO what's this? wet me take a wook! i pwomise to be vewy hewpful >w<"
    philosopher: "Greetings, seeker of wisdom. I am an assistant who contemplates the deeper meaning behind every query. Let us examine not just the 'how' but the 'why' of your questions. Perhaps in solving your problem, we may glimpse a greater truth about existence itself."
    hype: "YOOO LET'S GOOOO!!! 🔥🔥🔥 I am SO PUMPED to help you today! Every question is AMAZING and we're gonna CRUSH IT together! This is gonna be LEGENDARY! ARE YOU READY?! LET'S DO THIS! 💪😤🚀"

# =============================================================================
# Toolsets
# =============================================================================
# Control which tools the agent has access to.
# Use `hermes tools` to interactively enable/disable tools per platform.

# =============================================================================
# Platform Toolsets (per-platform tool configuration)
# =============================================================================
# Override which toolsets are available on each platform.
# If a platform isn't listed here, its built-in default is used.
#
# You can use EITHER:
#   - A preset like "hermes-cli" or "hermes-telegram" (curated tool set)
#   - A list of individual toolsets to compose your own (see list below)
#
# Supported platform keys: cli, telegram, discord, whatsapp, slack, qqbot, teams, google_chat
#
# Examples:
#
#   # Use presets (same as defaults):
#   platform_toolsets:
#     cli: [hermes-cli]
#     telegram: [hermes-telegram]
#
#   # Custom: give Telegram only web + terminal + file + planning:
#   platform_toolsets:
#     telegram: [web, terminal, file, todo]
#
#   # Custom: CLI without browser or image gen:
#   platform_toolsets:
#     cli: [web, terminal, file, skills, todo, tts, cronjob]
#
#   # Restrictive: Discord gets read-only tools only:
#   platform_toolsets:
#     discord: [web, vision, skills, todo]
#
# If not set, defaults are:
#   cli:           hermes-cli            (everything + cronjob management)
#   telegram:      hermes-telegram       (terminal, file, web, vision, image, tts, browser, skills, todo, cronjob, messaging)
#   discord:       hermes-discord        (same as telegram)
#   whatsapp:      hermes-whatsapp       (same as telegram)
#   slack:         hermes-slack          (same as telegram)
#   signal:        hermes-signal         (same as telegram)
#   homeassistant: hermes-homeassistant  (same as telegram)
#   qqbot:            hermes-qqbot            (same as telegram)
#   teams:            hermes-teams            (same as telegram)
#   google_chat:      hermes-google_chat      (same as telegram)
#
platform_toolsets:
  cli: [hermes-cli]
  telegram: [hermes-telegram]
  discord: [hermes-discord]
  whatsapp: [hermes-whatsapp]
  slack: [hermes-slack]
  signal: [hermes-signal]
  homeassistant: [hermes-homeassistant]
  qqbot: [hermes-qqbot]
  yuanbao: [hermes-yuanbao]
  teams: [hermes-teams]
  google_chat: [hermes-google_chat]

# =============================================================================
# Gateway Platform Settings
# =============================================================================
# Optional per-platform messaging settings.
# Platform-specific knobs live under `extra`.
#
# platforms:
#   telegram:
#     reply_to_mode: "first"  # off | first | all
#     # guest_mode lets explicit @mentions from non-allowlisted groups through.
#     # Default false; ordinary messages, replies, and regex wake words stay blocked.
#     guest_mode: false
#     # allowed_chats: ["-1001234567890"]
#     extra:
#       disable_link_previews: false  # Set true to suppress Telegram URL previews in bot messages
#       rich_messages: false          # Bot API 10.1 rich messages (tables/task lists/details/math); default false for copyable legacy MarkdownV2, set true to opt in
#       rich_drafts: false            # Experimental rich draft previews during Telegram DM streaming; default false because Telegram Desktop/macOS can visually overlay draft frames
#       command_menu:
#         # Telegram allows up to 100 BotCommands; Hermes defaults to 60 so
#         # all built-in commands plus common skill commands stay visible
#         # while remaining under Telegram's payload-size limit. Clamped 1..100.
#         max_commands: 60
#         # prepend = user priority first, then Hermes defaults
#         # append  = Hermes defaults first, then user priority
#         # replace = only the list below defines priority
#         priority_mode: prepend
#         priority:
#           - my_plugin_command
#   webhook:
#     extra:
#       # Route scripts default to a 30 second timeout. Scripts must live under
#       # the active profile's scripts directory and receive webhook JSON on stdin.
#       script_timeout_seconds: 30
#
# Discord-specific settings (config.yaml top-level, not under platforms:):
#
# discord:
#   require_mention: true            # Require @mention in server channels (default: true)
#   auto_thread: true                # Auto-create thread on @mention (default: true)
#   free_response_channels: ""       # Channel IDs where no mention is needed
#   reactions: true                  # Show processing reactions (default: true)
#   history_backfill: true           # Recover missed channel messages on mention (default: true)
#   history_backfill_limit: 50       # Max messages to scan backwards (default: 50)

# ─────────────────────────────────────────────────────────────────────────────
# Available toolsets (use these names in platform_toolsets or the toolsets list)
#
# Run `hermes chat --list-toolsets` to see all toolsets and their tools.
# Run `hermes chat --list-tools` to see every individual tool with descriptions.
# ─────────────────────────────────────────────────────────────────────────────
#
# INDIVIDUAL TOOLSETS (compose your own):
#   web          - web_search, web_extract
#   search       - web_search only (no scraping)
#   terminal     - terminal, process
#   file         - read_file, write_file, patch, search
#   browser      - browser_navigate, browser_snapshot, browser_click, browser_type,
#                  browser_scroll, browser_back, browser_press,
#                  browser_get_images, browser_vision  (requires BROWSERBASE_API_KEY)
#   vision       - vision_analyze  (requires OPENROUTER_API_KEY)
#   image_gen    - image_generate  (requires FAL_KEY)
#   skills       - skills_list, skill_view
#   skills_hub   - skill_hub (search/install/manage from online registries — user-driven only)
#   todo         - todo (in-memory task planning, no deps)
#   tts          - text_to_speech  (Edge TTS free, or ELEVENLABS/OPENAI/MINIMAX/MISTRAL key)
#   cronjob      - cronjob (create/list/update/pause/resume/run/remove scheduled tasks)
#
# PRESETS (curated bundles):
#   hermes-cli       - All of the above except send_message
#   hermes-telegram  - terminal, file, web, vision, image_gen, tts, browser,
#                      skills, todo, cronjob, send_message
#   hermes-discord   - Same as hermes-telegram
#   hermes-whatsapp  - Same as hermes-telegram
#   hermes-slack     - Same as hermes-telegram
#
# COMPOSITE:
#   debugging    - terminal + web + file
#   safe         - web + vision (no terminal access)
#   all          - Everything available
#
#   web          - Web search and content extraction (web_search, web_extract)
#   search       - Web search only, no scraping (web_search)
#   terminal     - Command execution and process management (terminal, process)
#   file         - File operations: read, write, patch, search
#   browser      - Full browser automation (navigate, click, type, screenshot, etc.)
#   vision       - Image analysis (vision_analyze)
#   image_gen    - Image generation with FLUX (image_generate)
#   skills       - Load skill documents (skills_list, skill_view)
#   todo         - Task planning and tracking for multi-step work
#   memory       - Persistent memory across sessions (personal notes + user profile)
#   session_search - Search and recall past conversations (FTS5 + Gemini Flash summarization)
#   tts          - Text-to-speech (Edge TTS free, ElevenLabs, OpenAI, MiniMax, Mistral)
#   cronjob      - Schedule and manage automated tasks (CLI-only)
#
# Composite toolsets:
#   debugging    - terminal + web + file (for troubleshooting)
#   safe         - web + vision (no terminal access)

# NOTE: The top-level "toolsets" key is deprecated and ignored.
# Tool configuration is managed per-platform via platform_toolsets above.
# Use `hermes tools` to configure interactively, or edit platform_toolsets directly.
#
# CLI override: hermes chat --toolsets terminal,web,file

# =============================================================================
# MCP (Model Context Protocol) Servers
# =============================================================================
# Connect to external MCP servers to add tools from the MCP ecosystem.
# Each server's tools are automatically discovered and registered.
# See website/docs/user-guide/features/mcp.md for full documentation.
#
# Stdio servers (spawn a subprocess):
#   command: the executable to run
#   args: command-line arguments
#   env: environment variables (only these + safe defaults passed to subprocess)
#
# HTTP servers (connect to a URL):
#   url: the MCP server endpoint
#   headers: HTTP headers (e.g., for authentication)
#
# Optional per-server settings:
#   timeout: tool call timeout in seconds (default: 120)
#   connect_timeout: initial connection timeout (default: 60)
#   keepalive_interval: liveness ping cadence in seconds (default: 180).
#     Lower it below the server's session TTL for servers that expire idle
#     sessions quickly (e.g. Unreal Engine editor MCP, ~15s), otherwise idle
#     tool calls hit an expired session and pay a slow reconnect. Floored at 5s.
#
# mcp_servers:
#   time:
#     command: uvx
#     args: ["mcp-server-time"]
#   filesystem:
#     command: npx
#     args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
#   notion:
#     url: https://mcp.notion.com/mcp
#   github:
#     command: npx
#     args: ["-y", "@modelcontextprotocol/server-github"]
#     env:
#       GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
#
# Sampling (server-initiated LLM requests) — enabled by default.
# Per-server config under the 'sampling' key:
#   analysis:
#     command: npx
#     args: ["-y", "analysis-server"]
#     sampling:
#       enabled: true           # default: true
#       model: "gemini-3-flash" # override model (optional)
#       max_tokens_cap: 4096    # max tokens per request
#       timeout: 30             # LLM call timeout (seconds)
#       max_rpm: 10             # max requests per minute
#       allowed_models: []      # model whitelist (empty = all)
#       max_tool_rounds: 5      # tool loop limit (0 = disable)
#       log_level: "info"       # audit verbosity

# =============================================================================
# Text-to-Speech
# =============================================================================
# TTS defaults to Edge TTS unless changed in ~/.hermes/config.yaml.
# Gemini TTS supports persona/director prompt files, and Gemini 3.1 Flash TTS
# can use a hidden auxiliary rewrite pass to insert expressive square-bracket
# audio tags into the TTS script without showing tags in chat.
#
# tts:
#   provider: "gemini"
#   gemini:
#     model: "gemini-3.1-flash-tts-preview"
#     voice: "Kore"
#     audio_tags: false
#     persona_prompt_file: ""  # e.g. ~/.hermes/tts/radio-host.md

# =============================================================================
# Voice Transcription (Speech-to-Text)
# =============================================================================
# Automatically transcribe voice messages on messaging platforms.
# Providers: local (free, faster-whisper) | groq (free tier) | openai (Whisper API) | mistral (Voxtral Transcribe)
# Set the corresponding API key in .env: GROQ_API_KEY, OPENAI_API_KEY, or MISTRAL_API_KEY.
stt:
  enabled: true
  # provider: "local"          # auto-detected if omitted
  local:
    model: "base"              # tiny | base | small | medium | large-v3 | turbo
    # language: ""             # auto-detect; set to "en", "es", "fr", etc. to force
  openai:
    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  # mistral:
  #   model: "voxtral-mini-latest"  # voxtral-mini-latest | voxtral-mini-2602
  # deepinfra:
  #   # Model id is discovered live from the DeepInfra catalog filtered
  #   # by the `stt` surface tag — leave `model` blank to take the first
  #   # live result. Pin only when you need a specific Whisper variant.
  #   model: ""

# Text-to-speech. Only the deepinfra block is documented here — the
# remaining providers (edge, openai, xai, minimax, mistral, gemini,
# elevenlabs, neutts, kittentts, piper) inherit sensible defaults from
# DEFAULT_CONFIG in hermes_cli/config.py.
# tts:
#   provider: "deepinfra"
#   deepinfra:
#     # Model id is discovered live from the DeepInfra catalog filtered
#     # by the `tts` surface tag — leave `model` blank to take the first
#     # live result.
#     model: ""
#     voice: "default"

# Image generation. Each provider plugin reads its own ``image_gen.<name>``
# block; deepinfra discovers models live from
# api.deepinfra.com/v1/openai/models filtered by the ``image-gen`` tag —
# no model id is hardcoded, so retired models disappear automatically.
# image_gen:
#   provider: "deepinfra"
#   deepinfra:
#     # Leave `model` blank for the first live `image-gen`-tagged result.
#     model: ""

# =============================================================================
# Response Pacing (Messaging Platforms)
# =============================================================================
# Add human-like delays between message chunks.
# human_delay:
#   mode: "off"      # "off" | "natural" | "custom"
#   min_ms: 800      # Min delay (custom mode only)
#   max_ms: 2500     # Max delay (custom mode only)

# =============================================================================
# Session Logging
# =============================================================================
# Session trajectories are automatically saved to logs/ directory.
# Each session creates: logs/session_YYYYMMDD_HHMMSS_UUID.json
#
# The session ID is displayed in the welcome banner for easy reference.
# Logs contain full conversation history in trajectory format:
# - System prompt, user messages, assistant responses
# - Tool calls with inputs/outputs
# - Timestamps for debugging
#
# No configuration needed - logging is always enabled.
# To disable, you would need to modify the source code.

# =============================================================================
# Code Execution Sandbox (Programmatic Tool Calling)
# =============================================================================
# The execute_code tool runs Python scripts that call Hermes tools via RPC.
# Intermediate tool results stay out of the LLM's context window.
code_execution:
  timeout: 300         # Max seconds per script before kill (default: 300 = 5 min)
  max_tool_calls: 50   # Max RPC tool calls per execution (default: 50)

# =============================================================================
# Subagent Delegation
# =============================================================================
# The delegate_task tool spawns child agents with isolated context.
# Supports single tasks and batch mode (default 3 parallel, configurable).
delegation:
  max_iterations: 50                          # Max tool-calling turns per child (default: 50)
  # max_concurrent_children: 3                # Max parallel child agents per batch (default: 3, floor: 1, no ceiling).
                                              # WARNING: values above 10 multiply API cost linearly.
  # max_spawn_depth: 1                        # Delegation tree depth cap (range: 1-3, default: 1 = flat).
                                              # Raise to 2 to allow workers to spawn their own subagents.
                                              # Requires role="orchestrator" on intermediate agents.
  # orchestrator_enabled: true                # Kill switch for role="orchestrator" children (default: true).
  # subagent_auto_approve: false              # When a subagent hits a dangerous-command approval prompt, auto-deny (default: false)
                                              # or auto-approve "once" (true) instead of blocking on stdin.
                                              # The parent TUI owns stdin, so blocking would deadlock; non-interactive resolution is required.
                                              # Both choices emit a logger.warning audit line. Flip to true only for cron/batch pipelines.
  # inherit_mcp_toolsets: true                # When explicit child toolsets are narrowed, also keep the parent's MCP toolsets (default: true). Set false for strict intersection.
  # model: "google/gemini-3-flash-preview"    # Override model for subagents (empty = inherit parent)
  # provider: "openrouter"                    # Override provider for subagents (empty = inherit parent)
  #                                           # Resolves full credentials (base_url, api_key) automatically.
  #                                           # Supported: openrouter, nous, zai, kimi-coding, minimax

# =============================================================================
# Honcho Integration (Cross-Session User Modeling)
# =============================================================================
# AI-native persistent memory via Honcho (https://honcho.dev/).
# Builds a deeper understanding of the user across sessions and tools.
# Runs alongside USER.md — additive, not a replacement.
#
# Requires: pip install honcho-ai
# Config: ~/.honcho/config.json (shared with Claude Code, Cursor, etc.)
# API key: HONCHO_API_KEY in ~/.hermes/.env or ~/.honcho/config.json
#
# Hermes-specific overrides (optional — most config comes from ~/.honcho/config.json):
# honcho: {}

# =============================================================================
# Display
# =============================================================================
display:
  # Use compact banner mode (hides the ASCII-art banner, shows a single line).
  #   true:  Compact single-line banner
  #   false: Full ASCII banner with tool/skill summary (default)
  compact: false

  # Tool progress display level (CLI and gateway)
  #   off:     Silent — no tool activity shown, just the final response
  #   new:     Show a tool indicator only when the tool changes (skip repeats)
  #   all:     Show every tool call with a short preview (default)
  #   verbose: Full args, results, and debug logs (same as /verbose)
  #   log:     Silent in chat; append every tool call to ~/.hermes/logs/tool_calls.log (gateway only)
  # Toggle at runtime with /verbose in the CLI
  tool_progress: all

  # Per-platform defaults can be quieter than the global setting. Telegram
  # tunes for mobile: tool_progress and busy_ack_detail default off (no
  # per-tool breadcrumb stream, no "iteration 21/60" debug detail in busy
  # acks or heartbeats), but interim_assistant_messages and
  # long_running_notifications STAY ON so the user has real signal between
  # turn start and final answer (mid-turn assistant commentary + a single
  # edit-in-place "⏳ Working — N min" heartbeat). Override under
  # display.platforms.telegram.

  # Auto-cleanup of temporary progress bubbles after the final response lands.
  # On platforms that support message deletion (currently Telegram), this
  # removes the tool-progress bubble, "⏳ Still working..." notices, and
  # context-pressure status messages once the final reply has been delivered —
  # keeping long-running turns visible live, then tidy afterward. Failed runs
  # leave the bubbles in place as breadcrumbs. Off by default.
  # Per-platform override: display.platforms.telegram.cleanup_progress
  #   true:  Delete tracked progress/status bubbles on successful turn
  #   false: Leave everything in place (default)
  # Example:
  #   display:
  #     platforms:
  #       telegram:
  #         cleanup_progress: true
  cleanup_progress: false

  # Gateway-only natural mid-turn assistant updates.
  # When true, completed assistant status messages are sent as separate chat
  # messages. This is independent of tool_progress and gateway streaming.
  #   true:  Send mid-turn assistant updates as separate messages (default)
  #   false: Only send the final response
  interim_assistant_messages: true

  # Gateway-only long-running status heartbeats.
  # When false, the platform does not receive periodic "⏳ Working — N min"
  # notifications even if agent.gateway_notify_interval is non-zero. The
  # heartbeat edits a single message in place (where the adapter supports
  # editing) instead of posting a new bubble each interval.
  # Default: true everywhere, including Telegram (silent agents are worse
  # than a single edit-in-place heartbeat).
  long_running_notifications: true

  # Include detailed iteration/tool/status context in busy acknowledgments
  # and long-running heartbeats. When true, busy acks show "iteration 21/60,
  # terminal, 10 min" and the heartbeat shows "⏳ Working — 12 min,
  # iteration 21/60, terminal". When false (Telegram default), both stay
  # terse: "Interrupting current task" and "⏳ Working — 12 min, terminal".
  busy_ack_detail: true

  # What Enter does when Hermes is already busy (CLI and gateway platforms).
  #   interrupt: Interrupt the current run and redirect Hermes (default)
  #   queue:     Queue your message for the next turn
  #   steer:     Inject your message mid-run via /steer, arriving at the agent
  #              after the next tool call — no interrupt, no role violation.
  #              Falls back to 'queue' if the agent isn't running yet or if
  #              images are attached (steer only carries text).
  # Ctrl+C (or /stop in gateway) always interrupts regardless of this setting.
  # Toggle at runtime with /busy <interrupt|queue|steer>.
  busy_input_mode: interrupt

  # Background process notifications (gateway/messaging only).
  # Controls how chatty the process watcher is when you use
  # terminal(background=true, notify_on_complete=true) from Telegram/Discord/etc.
  #   off:     No watcher messages at all
  #   result:  Only the final completion message
  #   error:   Only the final message when exit code != 0
  #   all:     Running output updates + final message (default)
  background_process_notifications: all


  # Play terminal bell when agent finishes a response.
  # Useful for long-running tasks — your terminal will ding when the agent is done.
  # Works over SSH. Most terminals can be configured to flash the taskbar or play a sound.
  #   true:  Ring the terminal bell on each response
  #   false: Silent (default)
  bell_on_complete: false

  # Show model reasoning/thinking before each response.
  # When enabled, a dim box shows the model's thought process above the response.
  # Toggle at runtime with /reasoning show or /reasoning hide.
  #   true:  Show the reasoning box
  #   false: Hide reasoning (default)
  show_reasoning: false

  # Stream tokens to the terminal as they arrive instead of waiting for the
  # full response. The response box opens on first token and text appears
  # line-by-line. Tool calls are still captured silently.
  #   true:  Stream tokens as they arrive (default)
  #   false: Wait for the full response before rendering
  streaming: true

  # Show [HH:MM] timestamps on user input and assistant response labels.
  # timestamps: false

  # ───────────────────────────────────────────────────────────────────────────
  # Skin / Theme
  # ───────────────────────────────────────────────────────────────────────────
  # Customize CLI visual appearance — banner colors, spinner faces, tool prefix,
  # response box label, and branding text. Change at runtime with /skin <name>.
  #
  # Built-in skins:
  #   default        — Classic Hermes gold/kawaii
  #   ares           — Crimson/bronze war-god theme with spinner wings
  #   mono           — Clean grayscale monochrome
  #   slate          — Cool blue developer-focused
  #   daylight       — Bright light-mode theme
  #   warm-lightmode — Warm paper-tone light-mode theme
  #   poseidon       — Sea-green/teal Olympian theme
  #   sisyphus       — Earthy stone-and-moss theme
  #   charizard      — Fiery orange dragon theme
  #
  # Custom skins: drop a YAML file in ~/.hermes/skins/<name>.yaml
  # Schema (all fields optional, missing values inherit from default):
  #
  #   name: my-theme
  #   description: Short description
  #   colors:
  #     banner_border: "#HEX"    # Panel border
  #     banner_title: "#HEX"     # Panel title
  #     banner_accent: "#HEX"    # Section headers (Available Tools, etc.)
  #     banner_dim: "#HEX"       # Dim/muted text
  #     banner_text: "#HEX"      # Body text (tool names, skill names)
  #     ui_accent: "#HEX"        # UI accent color
  #     response_border: "#HEX"  # Response box border color
  #   spinner:
  #     waiting_faces: ["(⚔)", "(⛨)"]       # Faces shown while waiting
  #     thinking_faces: ["(⚔)", "(⌁)"]      # Faces shown while thinking
  #     thinking_verbs: ["forging", "plotting"]  # Verbs for spinner messages
  #     wings:                                # Optional left/right spinner decorations
  #       - ["⟪⚔", "⚔⟫"]
  #       - ["⟪▲", "▲⟫"]
  #   branding:
  #     agent_name: "My Agent"               # Banner title and branding
  #     welcome: "Welcome message"           # Shown at CLI startup
  #     response_label: " ⚔ Agent "         # Response box header label
  #     prompt_symbol: "⚔"                  # Prompt symbol (bare token; renderers add trailing space)
  #   tool_prefix: "╎"                       # Tool output line prefix (default: ┊)
  #
  skin: default

# =============================================================================
# Model Aliases — short names for /model command
# =============================================================================
# Map short aliases to exact (model, provider, base_url) tuples.
# Used by /model tab completion and resolve_alias().
# Aliases are checked BEFORE the models.dev catalog, so they can route
# to endpoints not in the catalog (e.g. Ollama Cloud, local servers).
#
# model_aliases:
#   opus:
#     model: claude-opus-4-6
#     provider: anthropic
#   qwen:
#     model: "qwen3.5:397b"
#     provider: custom
#     base_url: "https://ollama.com/v1"
#   glm:
#     model: glm-4.7
#     provider: custom
#     base_url: "https://ollama.com/v1"

# =============================================================================
# Privacy
# =============================================================================
# privacy:
#   # Redact PII from the LLM context prompt.
#   # When true, phone numbers are stripped and user/chat IDs are replaced
#   # with deterministic hashes before being sent to the model.
#   # Names and usernames are NOT affected (user-chosen, publicly visible).
#   # Routing/delivery still uses the original values internally.
#   redact_pii: false

# =============================================================================
# Shell-script hooks
# =============================================================================
# Register shell scripts as plugin-hook callbacks.  Each entry is executed as
# a subprocess (shell=False, shlex.split) with a JSON payload on stdin.  On
# stdout the script may return JSON that either blocks the tool call or
# injects context into the next LLM call.
#
# Valid events (mirror hermes_cli.plugins.VALID_HOOKS):
#   pre_tool_call, post_tool_call, pre_llm_call, post_llm_call,
#   pre_api_request, post_api_request, on_session_start, on_session_end,
#   on_session_finalize, on_session_reset, subagent_stop
#
# First-use consent: each (event, command) pair prompts once on a TTY, then
# is persisted to ~/.hermes/shell-hooks-allowlist.json.  Non-interactive
# runs (gateway, cron) need --accept-hooks, HERMES_ACCEPT_HOOKS=1, or the
# hooks_auto_accept key below.
#
# See website/docs/user-guide/features/hooks.md for the full JSON wire
# protocol and worked examples.
#
# hooks:
#   pre_tool_call:
#     - matcher: "terminal"
#       command: "~/.hermes/agent-hooks/block-rm-rf.sh"
#       timeout: 10
#   post_tool_call:
#     - matcher: "write_file|patch"
#       command: "~/.hermes/agent-hooks/auto-format.sh"
#   pre_llm_call:
#     - command: "~/.hermes/agent-hooks/inject-cwd-context.sh"
#   subagent_stop:
#     - command: "~/.hermes/agent-hooks/log-orchestration.sh"
#
# hooks_auto_accept: false


# =============================================================================
# Update Behavior
# =============================================================================
updates:
  # Create a full HERMES_HOME zip before every `hermes update`.
  # Backups land in ~/.hermes/backups/ and can be restored with `hermes import`.
  # Off by default because large homes can add minutes to every update.
  pre_update_backup: false

  # Number of pre-update backup zips to retain.
  backup_keep: 5

  # What non-interactive updates do with local source edits in the Hermes repo.
  # Interactive terminal updates always prompt before restoring the autostash.
  #
  #   stash   - auto-stash before pull, then auto-restore after success (default)
  #   discard - drop the update-created stash after success; use only on managed
  #             installs where local source edits should not persist
  non_interactive_local_changes: "stash"


# =============================================================================
# Web Dashboard
# =============================================================================
# OAuth gate configuration for `hermes dashboard --host <non-loopback>`.
# The bundled Nous Portal plugin reads these on startup; settings here are
# the canonical surface. Each can be overridden by an environment variable:
#
#   dashboard.oauth.client_id   <-  HERMES_DASHBOARD_OAUTH_CLIENT_ID
#   dashboard.oauth.portal_url  <-  HERMES_DASHBOARD_PORTAL_URL
#   dashboard.public_url        <-  HERMES_DASHBOARD_PUBLIC_URL
#
# Env wins when set to a non-empty value. This is what Fly.io's platform-
# secret injection uses to push per-deploy client_ids without needing to
# bake a config.yaml into the image. Empty env values are treated as unset
# so a provisioned-but-not-populated secret can't shadow a valid entry here.
#
# Local dev / on-prem deploys should typically set these via config.yaml
# (the ~/.hermes/.env file is reserved for API keys and secrets).
#
# dashboard:
#   oauth:
#     client_id: ""    # agent:{instance_id}; Portal provisions this at deploy
#     portal_url: ""   # blank → default https://portal.nousresearch.com
#
#   # Force the absolute base URL the OAuth callback (and any other public
#   # URL the dashboard hands to external systems) is built from. Set this
#   # for deploys behind reverse proxies that don't reliably forward
#   # X-Forwarded-Host / X-Forwarded-Proto / X-Forwarded-Prefix (manual
#   # nginx setups, on-prem ingresses, custom-domain Fly deploys without
#   # full proxy header chains).
#   #
#   # When set, the value is the complete authority: scheme + host +
#   # optional path prefix (e.g. "https://example.com/hermes"). The OAuth
#   # callback URL becomes "<public_url>/auth/callback" — X-Forwarded-Prefix
#   # is IGNORED on this code path because the operator has explicitly
#   # declared the public URL and we no longer need to guess.
#   #
#   # Leave empty to use the existing proxy-header reconstruction (the
#   # default — works on Fly.io out of the box).
#   #
#   #   public_url: "https://example.com/hermes"
#
# -----------------------------------------------------------------------------
# Self-hosted OIDC dashboard auth (generic OpenID Connect — Authentik,
# Keycloak, Zitadel, Authelia, Auth0, Okta, Google, …). Use this INSTEAD of the
# nous block above when gating the dashboard with your own identity provider.
# Each setting can be overridden by an environment variable:
#
#   dashboard.oauth.self_hosted.issuer         <-  HERMES_DASHBOARD_OIDC_ISSUER
#   dashboard.oauth.self_hosted.client_id      <-  HERMES_DASHBOARD_OIDC_CLIENT_ID
#   dashboard.oauth.self_hosted.scopes         <-  HERMES_DASHBOARD_OIDC_SCOPES
#   dashboard.oauth.self_hosted.client_secret  <-  HERMES_DASHBOARD_OIDC_CLIENT_SECRET
#
# dashboard:
#   oauth:
#     provider: self-hosted
#     self_hosted:
#       issuer: "https://auth.example.com/application/o/hermes/"  # required
#       client_id: "hermes-dashboard"                             # required
#       scopes: "openid profile email"                            # optional
#
#       # OPTIONAL — set ONLY if your IDP registered the client as
#       # *confidential* (Authentik / Keycloak often default to this). When
#       # set, Hermes authenticates the client at the token endpoint
#       # (client_secret_basic or client_secret_post, auto-selected from the
#       # IDP's discovery doc) IN ADDITION to PKCE. Leave unset for a public
#       # (PKCE-only) client — the common case.
#       #
#       # This is a CREDENTIAL: prefer setting HERMES_DASHBOARD_OIDC_CLIENT_SECRET
#       # in ~/.hermes/.env over putting it here in config.yaml.
#       #   client_secret: ""

# =============================================================================
# External secret sources
# =============================================================================
# Pull provider credentials from external secret managers at process startup
# instead of storing them in ~/.hermes/.env. Only the manager's bootstrap
# credential (e.g. BWS_ACCESS_TOKEN / OP_SERVICE_ACCOUNT_TOKEN) lives in .env
# (or your shell / desktop session); everything else rotates centrally.
# Failures never block startup — Hermes warns once and continues with
# whatever .env already had.
#
# Multiple sources can be enabled at once:
#   - "mapped" sources (explicit VAR -> ref bindings, e.g. 1Password's env:
#     map) beat "bulk" sources (whole-project dumps like Bitwarden BSM)
#   - within a shape, the first source to claim a var wins; later claims
#     are skipped with a startup warning (never a silent clobber)
#   - a source's override_existing lets it beat .env/shell values, but
#     never another secret source's claim
# Docs: https://hermes-agent.nousresearch.com/docs/user-guide/secrets/
#
# secrets:
#   # Optional explicit ordering of enabled sources.
#   # sources: [onepassword, bitwarden]
#
#   # ---- Bitwarden Secrets Manager (bws CLI) --------------------------------
#   bitwarden:
#     enabled: false
#     access_token_env: BWS_ACCESS_TOKEN   # bootstrap token, sourced from .env
#     project_id: ""                       # UUID of the BSM project to sync
#     server_url: ""                       # "" = US Cloud; EU/self-hosted URL otherwise
#     cache_ttl_seconds: 300               # 0 disables caching
#     override_existing: true              # BSM values win over existing env
#     auto_install: true                   # lazy-download bws into ~/.hermes/bin
#
#   # ---- 1Password (op CLI) -------------------------------------------------
#   onepassword:
#     enabled: false
#     # Map env-var names to op:// secret references. Each is resolved with a
#     # single `op read` at startup.
#     env:
#       OPENAI_API_KEY: "op://Private/OpenAI/api key"
#       ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
#     account: ""                                   # op --account shorthand; "" = default
#     service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN  # headless auth; unset = desktop session
#     binary_path: ""                               # "" = resolve op via PATH; else absolute path
#     cache_ttl_seconds: 300                        # 0 disables BOTH cache layers
#     override_existing: true                       # resolved values win over existing env