Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix macOS: hermes crashes at startup — Invalid key c-S-c (Ctrl+Shift+C) [2 pull requests, 6 comments, 7 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#19894•Fetched 2026-05-05 06:04:31
View on GitHub
Comments
6
Participants
7
Timeline
20
Reactions
1
Author
MalaeuMalaeu
Participants
GabrielDuarteMGGabrielDuarteMGgrizdumgrizdumlaurentpayotlaurentpayotlloyd094lloyd094LordDeTracyLordDeTracyMalaeuMalaeusalazrsalazr
Timeline (top)
commented ×6cross-referenced ×4labeled ×3referenced ×3

On macOS, Hermes Agent v0.12.0 (2026-04-30) crashes immediately after the welcome banner with:

Error: Invalid key: c-S-c

The TUI never reaches the prompt. Reproduces with both bare hermes and hermes -s <skill> (so it's not skill-related).

Error Message

Error: Invalid key: c-S-c

Root Cause

cli.py:10487 registers a no-op binding for Ctrl+Shift+C:

@kb.add('c-S-c')  # Ctrl+Shift+C
def handle_ctrl_shift_c(event):
    """Copy text to clipboard (terminal-native).

    This is a no-op at the application level. Terminal emulators
    handle the actual copy operation when Ctrl+Shift+C is pressed.

    On macOS the standard copy shortcut is Cmd+C (no Hermes binding
    needed). On Linux/Windows Ctrl+Shift+C is the conventional
    terminal copy shortcut.
    """
    return  # No-op — let the terminal perform native copy

The docstring already acknowledges the binding is only needed on Linux/Windows, but the registration is unconditional. prompt_toolkit on macOS cannot parse the c-S-c key spec and raises ValueError during init, which propagates up and aborts the agent before the prompt loop starts.

Fix Action

Fixed

PR fix notes

PR #19895: fix(cli): guard c-S-c key binding with try/except to prevent startup crash

Description (problem / solution / changelog)

What does this PR do?

PR #19884 added @kb.add('c-S-c') unconditionally. prompt_toolkit raises ValueError("Invalid key: c-S-c") during HermesCLI.__init__ on platforms where this key spec is not recognised — the process exits before reaching the prompt loop.

Reported on macOS (#19894) and Linux (#19896) immediately after #19884 landed.

Root cause: prompt_toolkit.key_binding.KeyBindings.add() calls _parse_key('c-S-c') which raises ValueError: Invalid key: c-S-c on the current platform/version. The exception propagates through HermesCLI.__init__ and aborts startup.

Fix: Wrap the @kb.add('c-S-c') registration in try/except ValueError. Where the spec is accepted the binding is registered normally as a no-op; where it fails, startup continues cleanly and Ctrl+Shift+C falls through to the terminal's native handler.

Verified locally:

from prompt_toolkit.key_binding import KeyBindings
kb = KeyBindings()
try:
    @kb.add('c-S-c')
    def f(e): pass
except ValueError as ex:
    print(ex)  # "Invalid key: c-S-c"

Related Issue

Fixes #19894 (macOS crash) Fixes #19896 (Linux crash)

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests
  • ♻️ Refactor
  • 🎯 New skill

Changes Made

  • cli.py: wrap @kb.add('c-S-c') in try/except ValueError (+13/-14)

How to Test

On affected macOS or Linux: run hermes. Before this fix: Error: Invalid key: c-S-c and immediate exit. After: clean startup.

Checklist

Code

  • Contributing Guide read
  • Conventional Commits
  • No duplicate PR
  • This fix only
  • pytest run (no tests added — interactive TUI binding, not unit-testable)
  • Platform: macOS + Linux (regression from #19884, same day)

Documentation & Housekeeping

  • Docs — N/A
  • cli-config.yaml.example — N/A
  • CONTRIBUTING.md/AGENTS.md — N/A
  • Cross-platform impact — fixes both macOS (#19894) and Linux (#19896)
  • Tool descriptions — N/A

Changed files

  • cli.py (modified, +13/-14)

PR #19907: fix(cli): remove invalid ctrl-shift-c keybinding

Description (problem / solution / changelog)

What does this PR do?

Removes the @kb.add('c-S-c') prompt_toolkit binding that crashes Hermes startup with Error: Invalid key: c-S-c.

The handler was a no-op intended to let terminals handle Ctrl+Shift+C. Because prompt_toolkit rejects that key spec on affected installs, registering it aborts CLI startup before the prompt opens. Removing it preserves terminal-native copy behavior and avoids registering an invalid key.

This is an alternative to #19895. That PR keeps the binding behind try/except; this PR removes the no-op binding entirely and adds a regression test that validates literal CLI keybindings against prompt_toolkit.

Related Issue

Fixes #19894 Fixes #19896 Fixes #19903

Related: #19895 Regression introduced by #19884

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

  • cli.py: removed the invalid no-op c-S-c binding.
  • tests/cli/test_cli_keybindings.py: added a regression test that parses literal @kb.add(...) decorators in cli.py and verifies prompt_toolkit can register them.

How to Test

  1. On an affected checkout, run hermes; before this fix it exits during startup with Error: Invalid key: c-S-c.
  2. Run .venv/bin/python -m py_compile cli.py.
  3. Run scripts/run_tests.sh tests/cli/test_cli_keybindings.py -q.

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: Linux / WSL

Documentation & Housekeeping

  • I've updated relevant documentation (README, docs/, docstrings) — or N/A
  • I've updated cli-config.yaml.example if I added/changed config keys — or N/A
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Validation run locally:

.venv/bin/python -m py_compile cli.py
scripts/run_tests.sh tests/cli/test_cli_keybindings.py -q

1 passed in 2.96s

Changed files

  • cli.py (modified, +0/-15)
  • tests/cli/test_cli_keybindings.py (added, +51/-0)

Code Example

Error: Invalid key: c-S-c

---

$ hermes --version
Hermes Agent v0.12.0 (2026.4.30)
Python: 3.11.13

$ hermes
[welcome banner — tools, skills, model info]

Welcome to Hermes Agent! Type your message or /help for commands.
✦ Tip: …

Error: Invalid key: c-S-c

---

@kb.add('c-S-c')  # Ctrl+Shift+C
def handle_ctrl_shift_c(event):
    """Copy text to clipboard (terminal-native).

    This is a no-op at the application level. Terminal emulators
    handle the actual copy operation when Ctrl+Shift+C is pressed.

    On macOS the standard copy shortcut is Cmd+C (no Hermes binding
    needed). On Linux/Windows Ctrl+Shift+C is the conventional
    terminal copy shortcut.
    """
    return  # No-op — let the terminal perform native copy

---

import sys

if sys.platform != 'darwin':
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        ...
        return

---

try:
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        ...
        return
except ValueError:
    pass

---

$ echo "/quit" | gtimeout 8 hermes
Welcome to Hermes Agent! Type your message or /help for commands.
…
❯ /quit
Goodbye! ⚕
RAW_BUFFERClick to expand / collapse

Summary

On macOS, Hermes Agent v0.12.0 (2026-04-30) crashes immediately after the welcome banner with:

Error: Invalid key: c-S-c

The TUI never reaches the prompt. Reproduces with both bare hermes and hermes -s <skill> (so it's not skill-related).

Reproduction

$ hermes --version
Hermes Agent v0.12.0 (2026.4.30)
Python: 3.11.13

$ hermes
[welcome banner — tools, skills, model info]

Welcome to Hermes Agent! Type your message or /help for commands.
✦ Tip: …

Error: Invalid key: c-S-c

(Process exits.)

Root cause

cli.py:10487 registers a no-op binding for Ctrl+Shift+C:

@kb.add('c-S-c')  # Ctrl+Shift+C
def handle_ctrl_shift_c(event):
    """Copy text to clipboard (terminal-native).

    This is a no-op at the application level. Terminal emulators
    handle the actual copy operation when Ctrl+Shift+C is pressed.

    On macOS the standard copy shortcut is Cmd+C (no Hermes binding
    needed). On Linux/Windows Ctrl+Shift+C is the conventional
    terminal copy shortcut.
    """
    return  # No-op — let the terminal perform native copy

The docstring already acknowledges the binding is only needed on Linux/Windows, but the registration is unconditional. prompt_toolkit on macOS cannot parse the c-S-c key spec and raises ValueError during init, which propagates up and aborts the agent before the prompt loop starts.

Suggested fix

Either gate by platform (preferred — keeps the no-op active where it actually does something):

import sys

if sys.platform != 'darwin':
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        ...
        return

Or wrap in try/except (more permissive, also handles any other platform where the spec might fail):

try:
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        ...
        return
except ValueError:
    pass

I applied the try/except variant locally and verified clean startup:

$ echo "/quit" | gtimeout 8 hermes
Welcome to Hermes Agent! Type your message or /help for commands.
…
❯ /quit
Goodbye! ⚕

Happy to send a PR if helpful.

Environment

  • macOS 15.5 (Tahoe) on Apple Silicon (M4 Max)
  • Terminal: Ghostty
  • Python 3.11.13 (venv from hermes-agent install)
  • Hermes Agent: v0.12.0 (2026.4.30)
  • Upstream commit shown in banner: 81cd6782

extent analysis

TL;DR

The issue can be fixed by conditionally registering the Ctrl+Shift+C key binding based on the platform or by wrapping the registration in a try-except block to catch the ValueError.

Guidance

  • The root cause of the issue is the unconditional registration of the Ctrl+Shift+C key binding, which is not supported on macOS.
  • To fix the issue, gate the key binding registration by platform using sys.platform != 'darwin'.
  • Alternatively, wrap the key binding registration in a try-except block to catch the ValueError and prevent the agent from crashing.
  • Verify the fix by running the Hermes Agent and checking that it starts up cleanly without crashing.

Example

import sys

if sys.platform != 'darwin':
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        return  # No-op — let the terminal perform native copy

Alternatively:

try:
    @kb.add('c-S-c')  # Ctrl+Shift+C
    def handle_ctrl_shift_c(event):
        return
except ValueError:
    pass

Notes

The suggested fix assumes that the issue is specific to macOS and that the Ctrl+Shift+C key binding is not needed on this platform. If the issue occurs on other platforms, additional debugging may be required.

Recommendation

Apply the workaround by gating the key binding registration by platform or wrapping it in a try-except block, as this is a more targeted and less invasive fix.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#network issue#logging issue#authentication issue#prompt issue#agent setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix macOS: hermes crashes at startup — Invalid key c-S-c (Ctrl+Shift+C) [2 pull requests, 6 comments, 7 participants]