Intermediate

# ~/.hermes/skills/deploy-ayokoding.yml
# Auto-generated skill — created 2026-05-22 after 7-tool deployment session
 
name: deploy-ayokoding # => Unique identifier; used in /skills listing
level:
  frequent # => Disclosure level: always | frequent | rarely
  # =>   always: injected in full every session
  # =>   frequent: injected when name appears in context
  # =>   rarely: one-line summary only; full detail on demand
summary:
  "Deploy ayokoding-web to Vercel via prod-ayokoding-web branch"
  # => One-sentence description for summary mode
created: 2026-05-10T14:23:00+07:00 # => ISO 8601 timestamp; set at creation, never changed
updated: 2026-05-22T09:11:00+07:00 # => Updated each time the skill is refined
 
# Optional: tags help with skill retrieval when name alone is ambiguous
tags:
  - deploy # => Tag used for grouping in /skills output
  - ayokoding-web # => Tag used in search and FTS5 queries
  - vercel # => Platform tag
 
steps:
  - action: run # => action type: run | verify | note | branch
    command: nx build ayokoding-web # => Exact command to execute
    note:
      "Must pass before pushing — TypeScript errors will fail Vercel build"
      # => Inline note captures hard-won context
    on_failure:
      stop # => Stop execution if this step fails (default: stop)
      # => Other options: retry(n) | skip | branch
 
  - action: run
    command: git push origin main:prod-ayokoding-web --force
    note: "Force push is safe — prod-ayokoding-web is a deployment-only branch"
 
  - action: verify
    description:
      "Vercel dashboard shows green build status"
      # => verify steps are not commands; they are reminders
      # => Hermes presents them as confirmation prompts
    wait_seconds: 120 # => Suggest waiting 2 minutes before checking
 
# Optional: conditions under which this skill should NOT be applied
preconditions:
  - "Must be on main branch" # => Hermes checks this before applying the skill
  - "Nx build must be clean"
 
# Optional: history of refinements (append-only log)
refinements:
  - date: 2026-05-15T10:00:00+07:00
    change: "Added nx build step after failed deployment due to TypeScript error"
  - date: 2026-05-22T09:11:00+07:00
    change: "Added 120s wait in verify step based on observed Vercel build duration"

# Search sessions from within the TUI
/search --query "TypeScript error deploy"
# => Finds all sessions containing those terms
# => Returns ranked list of sessions with matching excerpts
 
# Search from the command line (outside TUI)
hermes search --query "Vercel build failed"
# => Same FTS5 index, same results, printed to stdout
 
# FTS5 supports boolean operators and phrase queries
hermes search --query '"nx build" AND deploy'
#                       ^^^^^^^^^^^           => Phrase search: exact phrase "nx build"
#                                   ^^^ ^^^^^ => Boolean AND: both terms must appear
# => Returns sessions containing the exact phrase "nx build" and also the word "deploy"
 
hermes search --query 'error OR failure'     # => OR: sessions containing either term
hermes search --query 'deploy NOT staging'   # => NOT: deploy but not staging
hermes search --query 'deploy*'              # => Prefix: deploy, deployment, deploying, etc.
 
# Filter by date range
hermes search --query "deploy" --since 2026-05-01 --until 2026-05-22
# => Only sessions within this date range
 
# Filter by cost (useful for auditing expensive sessions)
hermes search --query "" --min-cost 0.50
# => Sessions with total cost > $0.50

# Retrieve a full session by its ID
hermes session --id ses_20260522_143012_a7b3
# => Prints the complete session transcript to stdout
 
# List recent sessions without searching
hermes session --list --limit 10
# => Shows 10 most recent sessions with ID, date, cost, and first message
 
# Export a session as a markdown file
hermes session --id ses_20260522_143012_a7b3 --export --format markdown
# => Writes session transcript to hermes-session-20260522.md

# Example delegate tool call (as Hermes would construct it internally)
# This is the tool schema — you do not write this; Hermes generates it
 
tool: delegate
parameters:
  task:
    "Audit the authentication module: list all endpoints, check for missing auth guards,
    report any SQL queries without parameterization"
    # => Natural language task for the subagent
  toolset:
    - terminal # => Subagent can read files and run safe commands
    # browser is NOT listed              # => Subagent cannot browse the web (restricted scope)
    # delegation is NOT listed           # => Subagents cannot spawn further subagents by default
  timeout_seconds: 300 # => Kill subagent if it has not finished in 5 minutes
  model:
    cheap_model # => Use cheap model for subagent to reduce cost
    # => Override with primary if the task requires reasoning

# ~/.hermes/config.yml — delegation configuration
 
delegation:
  max_concurrent:
    3 # => Maximum subagents running simultaneously
    # => Increase with caution — each subagent uses API quota
  default_timeout_seconds: 300 # => Kill unresponsive subagents after 5 minutes
  allow_nested:
    false # => Prevent subagents from spawning their own subagents
    # => Set true only if you have a specific reason
  result_format:
    structured # => How subagent results are returned to parent
    # =>   structured: JSON with task, result, duration fields
    # =>   prose: plain text summary (cheaper to process)

# ~/.hermes/config.yml — messaging platform configuration
 
gateway:
  enabled: true
 
  platforms:
    # --- Telegram ---
    telegram:
      enabled: true
      token: ${TELEGRAM_BOT_TOKEN} # => Bot token from @BotFather (/newbot command)
      allowed_users:
        - 123456789 # => Your Telegram user ID (from @userinfobot)
      pairing_required: true # => Require /pair DM before accepting tasks
      command_approval: interactive # => Approval prompts sent back via Telegram message
 
    # --- Discord ---
    discord:
      enabled: false # => Set true to enable
      token: ${DISCORD_BOT_TOKEN} # => Bot token from Discord Developer Portal
      guild_id: "987654321012345678" # => Server (guild) ID where bot operates
      channel_ids: # => Restrict to specific channels by ID
        - "111222333444555666" # => Bot only responds in this channel
      command_approval: interactive # => Approval prompts sent as Discord DM to invoker
 
    # --- Slack ---
    slack:
      enabled: false
      app_token: ${SLACK_APP_TOKEN} # => App-level token (xapp-...) from Slack App config
      bot_token: ${SLACK_BOT_TOKEN} # => Bot token (xoxb-...) from Slack App config
      allowed_channels:
        - "C01ABCDEFGH" # => Channel IDs (not names) allowed to invoke Hermes
      signing_secret:
        ${SLACK_SIGNING_SECRET}
        # => Used to verify Slack request authenticity
 
    # --- WhatsApp (via Twilio) ---
    whatsapp:
      enabled: false
      provider: twilio # => WhatsApp integration requires a Twilio account
      account_sid: ${TWILIO_ACCOUNT_SID}
      auth_token: ${TWILIO_AUTH_TOKEN}
      from_number:
        "whatsapp:+14155238886"
        # => Twilio WhatsApp sandbox number (testing)
        # => Replace with approved number for production
      allowed_numbers:
        - "whatsapp:+62812345678" # => Only respond to this WhatsApp number

# ~/.hermes/config.yml — terminal backend configuration
 
terminal:
  backend: local # => Options: local | docker | ssh | daytona | singularity | modal
 
 
  # --- local (default) ---
  # No additional configuration needed
  # => Commands run in a subprocess on the current machine
  # => Working directory defaults to the directory where hermes was started
 
  # --- docker ---
  # docker:
  #   image: python:3.12-slim            # => Container image to use for execution
  #   volumes:
  #     - "${HOME}/projects:/workspace"  # => Mount host directory into container
  #   network: none                      # => Disable network access in container (air-gap)
  #                                       # => Options: none | bridge | host
  #   remove_after_session: true         # => Delete container when session ends
  #   resource_limits:
  #     memory: 2g                       # => Maximum RAM the container may use
  #     cpus: 1.0                        # => Maximum CPU cores
 
  # --- ssh ---
  # ssh:
  #   host: my-server.example.com
  #   user: ubuntu
  #   key_path: ~/.ssh/id_ed25519        # => Private key for authentication
  #   port: 22                           # => Default SSH port
 
  # --- modal (serverless cloud) ---
  # modal:
  #   token_id: ${MODAL_TOKEN_ID}
  #   token_secret: ${MODAL_TOKEN_SECRET}
  #   image: modal/python:3.12           # => Modal-hosted image
  #   timeout_seconds: 600               # => Container idle timeout

# ~/.hermes/config.yml — browser toolset configuration
 
tools:
  enabled:
    - browser # => Add to enable Playwright-based browser automation
 
browser:
  headless:
    true # => Run Chromium without visible UI (default: true)
    # => Set false to watch the browser interact visually
  viewport:
    width: 1280 # => Browser window width in pixels
    height: 720 # => Browser window height in pixels
  timeout_ms: 30000 # => Default timeout for element waits (30 seconds)
  screenshots_dir: ~/.hermes/screenshots # => Where screenshots are saved for vision review

# Example session: scrape a paginated table from a web application
 
# User input to Hermes:
# "Fetch all rows from the pricing table at example.com/pricing, save to pricing.csv"
 
# Hermes constructs and executes the following tool call sequence:
 
# Tool 1: Navigate to the target URL
# [Tool: browser.navigate]
# url: https://example.com/pricing
# => Page loaded, title: "Pricing — Example"
 
# Tool 2: Extract the table content
# [Tool: browser.extract]
# selector: table.pricing-table
# format: text
# => <table data with all visible rows>
 
# Tool 3: Check for pagination
# [Tool: browser.extract]
# selector: .pagination .next
# => Element found: "Next page >"
 
# Tool 4: Click next page and extract again (repeats until no next page)
# [Tool: browser.click]
# selector: .pagination .next
# wait_for: networkidle
# => Page 2 loaded
 
# Tool 5: Write aggregated data to CSV
# [Tool: terminal.write]
# path: pricing.csv
# content: <combined CSV rows from all pages>
# => File written: pricing.csv (47 rows)

# Vision toolset — requires browser toolset to be enabled for screenshot capture
tools:
  enabled:
    - browser
    - vision # => Analyze screenshots with vision model

# ~/.hermes/config.yml — code execution toolset configuration
 
tools:
  enabled:
    - code # => Enable code execution toolset
 
code:
  sandbox:
    docker # => Isolation mode: none | docker | subprocess
    # =>   none: runs in current process (fastest, unsafe)
    # =>   subprocess: isolated subprocess (safer)
    # =>   docker: isolated container (safest, requires Docker)
  docker_image: python:3.12-slim # => Image for docker sandbox (ignored if sandbox != docker)
  timeout_seconds: 60 # => Kill code execution if it exceeds 60 seconds
  allowed_languages:
    - python # => Only Python execution enabled
    - javascript # => Node.js execution enabled
    # - shell                            # => Shell script execution (disabled; use terminal instead)
  network_access:
    false # => Prevent code from making network requests
    # => Important for untrusted code

# User input:
# "Analyze the CSV file data.csv: compute mean, median, and standard deviation for column 'revenue'"
 
# Hermes generates and executes a Python snippet:
# [Tool: code.execute]
# language: python
# code: |
#   import csv, statistics
#   revenues = []
#   with open('/workspace/data.csv') as f:     # => /workspace maps to mounted local directory
#       reader = csv.DictReader(f)
#       for row in reader:
#           revenues.append(float(row['revenue']))
#   print(f"Count:  {len(revenues)}")
#   print(f"Mean:   {statistics.mean(revenues):.2f}")
#   print(f"Median: {statistics.median(revenues):.2f}")
#   print(f"StdDev: {statistics.stdev(revenues):.2f}")
 
# => Output:
# Count:  1,247
# Mean:   48,392.17
# Median: 31,500.00
# StdDev: 52,841.33
 
# Hermes returns the output formatted in the response:
# Revenue analysis (1,247 rows):
# - Mean: $48,392
# - Median: $31,500 (significantly lower than mean — right-skewed distribution)
# - Standard deviation: $52,841 (high variance; outliers likely present)

# ~/.hermes/config.yml — cron scheduling configuration
 
cron:
  enabled: true # => Enable the cron scheduler
  timezone: Asia/Jakarta # => All cron expressions interpreted in this timezone
  jobs:
    - name: daily-cost-report # => Unique job identifier
      schedule:
        "0 9 * * *" # => Standard cron: minute hour day month weekday
        # => "0 9 * * *" = 9:00 AM every day
      task: >
        Generate a daily cost report: run `hermes --cost-report --days 1` and send
        the output to the #hermes-cost Slack channel
                                          # => Natural language task; Hermes interprets this
      toolsets:
        - terminal # => Only terminal toolset available for this job
        - messaging # => Messaging toolset to send the Slack message
 
    - name: weekly-skill-review
      schedule: "0 10 * * 1" # => 10:00 AM every Monday
      task: >
        Review skills created in the last 7 days: list new skills, check for duplicates
        or skills that could be merged, and prepare a summary
      toolsets:
        - skills
        - terminal
 
    - name: hourly-health-check
      schedule: "0 * * * *" # => Top of every hour
      task: "Check disk usage on the server, alert if any mount exceeds 85%"
      toolsets:
        - terminal
        - messaging
      on_failure:
        notify # => Send notification if the job fails
        # => Options: notify | retry(n) | skip

# List all configured cron jobs and their next run time
/tools cron.list
# => Output:
# JOB                  SCHEDULE        NEXT RUN                  LAST RUN
# daily-cost-report    0 9 * * *       2026-05-23 09:00:00 WIB   2026-05-22 09:00:04 WIB
# weekly-skill-review  0 10 * * 1      2026-05-25 10:00:00 WIB   2026-05-18 10:00:11 WIB
# hourly-health-check  0 * * * *       2026-05-22 15:00:00 WIB   2026-05-22 14:00:03 WIB
 
# Trigger a job immediately without waiting for the schedule
/tools cron.run --job daily-cost-report
 
# Disable a job without removing it from config
/tools cron.disable --job hourly-health-check
 
# View the log of recent job executions
/tools cron.log --job daily-cost-report --limit 5

# ~/.hermes/config.yml — Honcho dialectic integration configuration
 
honcho:
  enabled: true # => Enable Honcho user modeling
  api_url: https://api.honcho.dev # => Honcho service endpoint
  api_key: ${HONCHO_API_KEY} # => API key from honcho.dev
  app_id: hermes-agent # => Application identifier in Honcho
 
  dialectic:
    enabled: true # => Enable active dialectic questioning
    frequency:
      low # => How often Honcho asks clarifying questions
      # =>   low: rarely, only for high-uncertainty areas
      # =>   medium: occasionally during natural pauses
      # =>   high: frequently (can feel intrusive)
    max_questions_per_session: 2 # => Never ask more than 2 dialectic questions per session
 
  sync_to_user_md:
    true # => Write Honcho insights back to USER.md
    # => Keeps USER.md authoritative even without Honcho

# Example USER.md with Honcho-sourced entries
 
## Communication (Honcho-derived, confidence: high)
Response length: concise (confirmed by dialectic question 2026-05-10)
Technical depth: expert for TypeScript; intermediate for DevOps
Formality: informal with contractions preferred
 
## Expertise (direct observation)
Corrected Hermes explanations about: React hooks (2x), npm workspaces (1x)
# => Hermes inferred advanced React knowledge from the corrections
 
## Workflow Preferences (Honcho-derived, confidence: medium)
Code review style: focus on logic errors before style issues
Test preference: unit tests before writing implementation (TDD)

hermes honcho reset
# => Clears the Honcho-side model for your user ID
# => Clears Honcho-sourced entries in USER.md (preserves direct-observation entries)
# => Honcho begins rebuilding the model from the next session

# ~/.hermes/config.yml — Mixture of Agents configuration
 
llm:
  primary: claude-3-7-sonnet-20250219 # => Used as aggregator in MoA mode
  cheap_model: claude-haiku-4-5
 
  moa:
    enabled: false # => Disabled by default; enable explicitly per task
    reference_models: # => Models run in parallel on the same input
      - anthropic/claude-3-7-sonnet-20250219
        # => Claude as reference model 1
      - openai/gpt-4o # => GPT-4o as reference model 2 (via OpenRouter)
      - google/gemini-2.5-pro # => Gemini as reference model 3 (via OpenRouter)
    aggregator_model:
      claude-3-7-sonnet-20250219
      # => Aggregator receives all reference outputs and synthesizes
    reference_temperature: 0.7 # => Temperature for reference models (diversity in responses)
    aggregator_temperature: 0.3 # => Temperature for aggregator (conservative synthesis)

# Activate MoA for the next message only
/moa on
# => Hermes uses MoA mode for the next response, then returns to normal routing
 
# Example task where MoA adds value:
# "Review this authentication module for security vulnerabilities"
# => Reference model 1 (Claude): finds JWT expiry not enforced
# => Reference model 2 (GPT-4o): finds missing rate limiting on /login
# => Reference model 3 (Gemini): finds SQL query without parameterization
# => Aggregator synthesizes: ranked list of all three findings with severity assessment
 
# The MoA approach surfaced three different vulnerability classes
# that a single model call might have missed or underweighted

# ~/.hermes/config.yml — MCP client configuration
 
tools:
  enabled:
    - mcp # => Enable the MCP toolset (client mode)
 
mcp:
  servers:
    - name: github # => Display name in /tools listing
      command: npx # => Command to start the MCP server process
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
          # => MCP server package; npx downloads if not cached
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN:
          ${GITHUB_TOKEN}
          # => Environment variable passed to server process
      transport: stdio # => Communication via stdin/stdout (default for local servers)
 
    - name: postgres # => Database MCP server
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-postgres"
        - postgresql://localhost:5432/mydb
      transport: stdio
 
    - name: remote-analytics # => Remote MCP server over HTTP+SSE
      url:
        https://analytics.example.com/mcp
        # => HTTP-based transport for remote servers
      transport: sse # => Server-Sent Events transport (for remote servers)
      api_key: ${ANALYTICS_MCP_API_KEY}

/tools
# => Standard Hermes tools:
#    terminal.bash, terminal.read, terminal.write ...
#    web.search, web.fetch ...
#
# => MCP server: github
#    github.list_repos, github.create_issue, github.get_pull_request ...
#
# => MCP server: postgres
#    postgres.query, postgres.list_tables, postgres.describe_table ...

# ~/.hermes/config.yml — MCP server mode configuration
 
mcp_server:
  enabled: false # => Set true to enable server mode
  transport:
    stdio # => stdio: connect via subprocess stdin/stdout
    # =>   (for single-client integrations like Claude Code)
    # => sse: HTTP+SSE for multi-client remote access
  port: 8765 # => Port for SSE transport (ignored for stdio)
  exposed_toolsets: # => Only expose these toolsets to MCP clients
    - terminal # => Expose terminal tools (bash, read, write)
    - web # => Expose web tools (search, fetch)
    # memory is NOT listed               # => Memory tools not exposed (protect sensitive data)
    # delegation is NOT listed           # => Delegation not exposed (prevent recursive loops)
  auth:
    required: true # => Require authentication for SSE transport
    tokens:
      - ${MCP_CLIENT_TOKEN_1} # => Valid client tokens (bearer tokens)
      - ${MCP_CLIENT_TOKEN_2}

// ~/.claude/mcp_servers.json (Claude Code configuration)
{
  "hermes": {
    "command": "hermes",
    "args": ["--mcp-server"],
    "transport": "stdio"
  }
}

# Start Hermes in MCP server mode (stdio transport)
# => Claude Code launches this as a subprocess when you reference Hermes tools
hermes --mcp-server
 
# Start Hermes as a standalone MCP server (SSE transport)
# => Accepts connections from multiple clients over HTTP
hermes --mcp-server --transport sse --port 8765

# ~/.hermes/config.yml — Skills Hub configuration
 
skills_hub:
  enabled: true
  url:
    https://hub.hermes-agent.dev # => Official Nous Research Skills Hub
    # => Replace with your org's private hub URL
  api_key: ${SKILLS_HUB_API_KEY} # => Authentication for private hubs (not required for public)
  auto_update:
    false # => Never auto-update imported skills without consent
    # => Set true to receive hub updates automatically (risky)

# Browse available skills on the hub
hermes skills hub --list
# => Lists skills with name, author, version, downloads, and summary
# OUTPUT:
# NAME                    AUTHOR       VERSION  DOWNLOADS  SUMMARY
# deploy-vercel           nousresearch 1.2.0    4,821      Deploy Next.js to Vercel via env branches
# nx-affected-test        nousresearch 1.0.3    2,341      Run nx affected tests before committing
# docker-compose-dev      community    0.9.1    987        Start local dev services with health checks
# github-pr-review        community    1.1.0    1,203      Review PR: checklist, comments, approval
 
# Search for skills by keyword
hermes skills hub --search "deploy"
# => Returns skills matching "deploy" in name, summary, or tags
 
# Preview a skill before importing
hermes skills hub --preview deploy-vercel --version 1.2.0
# => Prints the full skill YAML without importing it
 
# Import a specific skill at a pinned version
hermes skills hub --import deploy-vercel --version 1.2.0
# => Downloads the skill YAML to ~/.hermes/skills/deploy-vercel.yml
# => Adds a hub_source field to the YAML recording origin and version
 
# Update an imported skill to a newer version
hermes skills hub --update deploy-vercel --version 1.3.0
# => Overwrites the local file with the hub version
# => Previous version is backed up to ~/.hermes/skills/backup/
 
# Publish a local skill to the hub
hermes skills hub --publish deploy-ayokoding --version 1.0.0
# => Uploads your skill to the hub
# => Requires hub API key with publish permission
# => Published skills are public unless your hub is configured as private