ling/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-27 22:41:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: revert docs

Browse Source
This commit is contained in:
Harry Riddle
2026-04-26 18:46:55 +07:00
committed by Teknium
parent 0f3a6f0fb3
commit 2511207cb0
3 changed files with 1 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
AGENTS.md
View File

@@ -667,27 +667,6 @@ def profile_env(tmp_path, monkeypatch):
return home
```
### Clipboard environment variables and pitfalls
Hermes TUI clipboard handling uses a three-tier strategy:
1. **Native OS tools** (`pbcopy`, `wl-copy`, `xclip`, `xsel`, `clip.exe`) — available **only** when a display server is present (`$DISPLAY` for X11 or `$WAYLAND_DISPLAY` for Wayland). On Linux in headless environments (Docker, remote SSH without X11 forwarding), these tools fail or hang. The code now short-circuits immediately if both variables are unset.
2. **tmux buffer** (`tmux load-buffer`) — when inside a tmux session; requires `set-clipboard on` for system clipboard propagation.
3. **OSC 52 escape** — written to stdout; the terminal emulator must intercept and set the clipboard. Support varies: iTerm2 disables it by default, VS Code may block it behind a permission prompt, and raw PTYs without an emulator drop it silently.
**Environment variables:**
| Variable | Purpose |
|---|---|
| `HERMES_TUI_CLIPBOARD_OSC52` or `HERMES_TUI_COPY_OSC52` | Force OSC 52 emission (`1`/`true`) or disable (`0`/`false`). Ignored when native tools are expected to work (macOS local, or Linux with `$DISPLAY/$WAYLAND_DISPLAY`). |
| `HERMES_TUI_DEBUG_CLIPBOARD` | Set to `1` to log detailed debug information to stderr about which clipboard path is taken, probe results on Linux, and why OSC 52 may be suppressed. |
| `SSH_CONNECTION` | Presence indicates an SSH session; this gates native tool usage (to avoid writing to the remote machine's clipboard) and prefers OSC 52. |
| `TMUX`, `STY` | Used to detect tmux/screen and apply appropriate passthrough or buffer loading. |
**Common false-positive:** The UI message "copied selection" is displayed **unconditionally** after Ctrl+C, even if all clipboard mechanisms fail. If you're in a headless Docker container or a non-OSC52-capable terminal, you'll see the message but nothing is copied. Use `HERMES_TUI_DEBUG_CLIPBOARD=1` to diagnose.
**Dashboard caveat:** The dashboard's `Ctrl+C` path relies on OSC 52 → xterm's handler → browser Clipboard API. Because the Clipboard API requires a user gesture, this can fail if the OSC 52 response arrives outside the key event's activation window. Use `Ctrl+Shift+C` (Cmd+Shift+C on macOS) as a reliable fallback; it calls `navigator.clipboard.writeText()` directly inside the key handler.
---
## Testing

21
CHANGELOG.md
View File

@@ -1,21 +0,0 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Fixed
- **TUI clipboard copy** — Native tool probing on Linux now short-circuits immediately when `$DISPLAY` and `$WAYLAND_DISPLAY` are both unset, avoiding wasted time and silent failures in headless environments (Docker, CI). (Hermes Ink / osc.ts)
- **TUI debug visibility** — Added `HERMES_TUI_DEBUG_CLIPBOARD` environment variable. When set, the TUI logs which clipboard mechanism is used, probe results, and why OSC 52 might be suppressed. Helps users and operators diagnose copy failures.
- **Dashboard clipboard logging** — Silent failures in OSC 52 → Clipboard API bridge and direct `Ctrl+Shift+C` copy are now logged to the browser console with explanatory warnings, replacing empty catch blocks. Makes clipboard permission issues and gesture-timeout failures visible during development.
- **Documentation** — Added comprehensive "Clipboard Troubleshooting" section to README covering OSC 52 verification, tmux configuration, Docker/headless constraints, environment variables, and dashboard caveats. AGENTS.md now documents all clipboard-related environment variables and known failure modes.
### Changed
- Desktop and dashboard clipboard error handling is now consistent: all Clipboard API rejections and native tool failures produce diagnostic logs rather than being swallowed.
</content>

94
README.md
View File

@@ -169,99 +169,7 @@ scripts/run_tests.sh
- 💬 [Discord](https://discord.gg/NousResearch)
- 📚 [Skills Hub](https://agentskills.io)
- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
---
## Clipboard Troubleshooting
Hermes TUI (standalone) and dashboard both support copying via `Ctrl+C` / `Cmd+C`. This requires either:
- A terminal with **OSC 52** support enabled, **or**
- Native clipboard utilities (`pbcopy`, `wl-copy`, `xclip`, `xsel`, `clip.exe`) available in PATH **and** a running display server (X11 or Wayland).
If the UI says "copied" but the text is not in your system clipboard, follow these steps.
### Standalone TUI (`hermes --tui`)
#### Verify OSC 52 support
Run this in the same terminal you use for Hermes:
```bash
printf '\e]52;c;%s\a' "$(echo -n 'test-osc52' | base64)" && echo
```
Then paste (Cmd+V / Ctrl+Shift+V). If you see `test-osc52`, OSC 52 works.
If it fails, enable OSC 52 in your terminal:
| Terminal | Setting |
|--------------|-------------------------------------------------------------------------|
| iTerm2 | Preferences → General → Selection → check "Copy to pasteboard" |
| Kitty | `allow_remote_control yes` (default: on) |
| WezTerm | `enable_osc52_copy = true` |
| VS Code | Usually works; if blocked, check DevTools console for permission error |
| GNOME | Enabled by default |
#### tmux users
tmux absorbs OSC 52 unless explicitly configured. Add to `~/.tmux.conf`:
```tmux
set -g set-clipboard on
set -g allow-passthrough on
```
Then reload: `tmux source-file ~/.tmux.conf`.
#### Docker/headless environments
Inside a Docker container, `$DISPLAY` and `$WAYLAND_DISPLAY` are typically unset, so native clipboard tools fail immediately. OSC 52 is the only path — it must be supported by your local terminal emulator (the one connected to the container's PTY). If your terminal doesn't support OSC 52, consider:
- Using `ssh -X` / `ssh -Y` to forward X11 and run `xclip` on the host via SSH
- Running Hermes on the host directly, not inside a container
- Writing copied text to a file: `/copy` saves to `~/.hermes/clipboard.txt` (fallback)
#### Force OSC 52 emission
If your terminal supports OSC 52 but Hermes isn't emitting it (e.g., inside SSH where native tools are skipped), set:
```bash
export HERMES_TUI_CLIPBOARD_OSC52=1
hermes --tui
```
#### Debug mode
To see exactly which clipboard path Hermes takes:
```bash
export HERMES_TUI_DEBUG_CLIPBOARD=1
hermes --tui
```
Then attempt a copy and watch stderr for messages like:
```
[clipboard] [native] Linux: no DISPLAY or WAYLAND_DISPLAY — native clipboard unavailable
[clipboard] [native] Linux: clipboard probe complete → xclip
[clipboard] [osc52] no sequence emitted — native clipboard or tmux buffer path in use
```
### Dashboard (`hermes dashboard` → /chat)
The dashboard uses the browser's Clipboard API. There are two copy paths:
1. **Ctrl/Cmd+Shift+C** — direct copy from xterm's selection (most reliable)
2. **Ink's Ctrl+C** — emits OSC 52 → xterm OSC 52 handler → Clipboard API; this is more fragile because the Clipboard API requires a **user gesture**. In some browsers the OSC 52 response is processed outside the original key event's activation window, causing a silent failure.
If copy doesn't work in the dashboard:
- Use `Ctrl+Shift+C` (Linux/Windows) or `Cmd+Shift+C` (macOS) instead
- Check the browser console (F12) for warnings like `[dashboard clipboard] OSC 52 write failed`
- Ensure the page has clipboard permissions (browser may ask on first use)
Clicking the "copy last response" button also sends `/copy` over the WebSocket, which suffers from the same OSC 52 timing issue.
### When all else fails: file-based fallback
You can save copied text to a file manually:
```bash
hermes --tui # inside TUI, use /copy which includes a file fallback in future versions
```
Or implement a custom skill that writes the last assistant message to disk.
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
---