顺便说一下，对于任何想要搭建完美的 @NousResearch Hermes Agent 的人：(a) 将你最强大的 LLM 指向 https://hermes-agent.nousresearch.com/docs/llms-full.txt… (b) 说明你的需求、你希望 agent 为你做什么，并提供完整上下文 (c) 尽情享用 这个文件是整个 Hermes Agent 文档的拼接版，专为 LLM 上下文摄入而设计。

从命令行启动。使用hermes sessions list` 浏览历史会话。

会话存储

CLI 会话存储在 Hermes 的 SQLite 状态数据库中，路径为 ~/.hermes/state.db。数据库保存：

• 会话元数据（ID、标题、时间戳、token 计数器）
• 消息历史
• 跨压缩/恢复会话的谱系
• session_search 使用的全文搜索索引

某些消息适配器还会在数据库旁保留平台特定的转录文件，但 CLI 本身是从 SQLite 会话存储中恢复的。

上下文压缩

长对话在接近上下文限制时会自动总结：

# ~/.hermes/config.yaml
compression:
  enabled: true
  threshold: 0.50 # 默认在上下文限制的 50% 时压缩
  # 总结模型在 auxiliary 下配置
auxiliary:
  compression:
    model: "" # 留空则使用主对话模型（默认）。或者指定一个便宜且快速的模型，例如 "google/gemini-3-flash-preview"。

当压缩触发时，中间的消息会被总结，而前 3 条和后 20 条消息始终保留。

后台会话

在继续使用 CLI 进行其他工作时，在后台运行一个独立会话：

/background 分析 /var/log 中的日志，并总结今天的任何错误

Hermes 会立即确认任务，并将提示交还给你：

🔄 后台任务 #1 已启动："分析 /var/log 中的日志..."
任务 ID: bg_143022_a1b2c3

工作原理

每个 /background 提示都会在一个守护线程中生成一个完全独立的 agent 会话：

• 隔离对话 — 后台 agent 不知道你当前会话的历史，只接收你提供的提示。
• 相同配置 — 后台 agent 继承当前会话的模型、provider、工具集、推理设置和备用模型。
• 非阻塞 — 前台会话保持完全交互。你可以聊天、运行命令，甚至启动更多后台任务。
• 多任务 — 你可以同时运行多个后台任务，每个都有编号 ID。

结果

当后台任务完成时，结果会在终端中以面板形式显示：

╭─ ⚕ Hermes (后台 #1) ──────────────────────────────────╮
│ 在今天的系统日志中发现 3 个错误：                              │
│ 1. 03:22 调用了 OOM killer — 杀死了 nginx 进程                 │
│ 2. 07:15 在 /dev/sda1 上出现磁盘 I/O 错误                      │
│ 3. 14:30 来自 192.168.1.50 的 SSH 登录尝试失败                  │
╰──────────────────────────────────────────────────────────────╯

如果任务失败，你会看到错误通知。如果配置中启用了 display.bell_on_complete，任务完成时终端会响铃。

用例

• 长时间研究 — 在处理代码时执行 “/background 研究量子纠错的最新进展”
• 文件处理 — 在继续对话时执行 “/background 分析此仓库中的所有 Python 文件并列出安全问题”
• 并行调查 — 启动多个后台任务，同时探索不同角度

:::info 后台会话不会出现在你的主对话历史中。它们是独立的会话，有自己的任务 ID（例如 bg_143022_a1b2c3）。 :::

静默模式

默认情况下，CLI 以静默模式运行，这会：

• 抑制工具的冗长日志
• 启用卡哇伊风格的动画反馈
• 保持输出整洁且用户友好

要查看调试输出：

hermes chat --verbose

TUI

TUI

TUI 是 Hermes 的现代前端——一个终端 UI，其底层 Python 运行时与 经典 CLI 相同。相同的 agent、相同的会话、相同的斜杠命令；但交互界面更干净、更灵敏。这是推荐用于交互式运行 Hermes 的方式。

启动

# 启动 TUI
hermes --tui

# 恢复最近的 TUI 会话（如果没有，则回退到最近的经典会话）
hermes --tui -c
hermes --tui --continue

# 通过 ID 或标题恢复特定会话
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"

# 直接运行源码——跳过预构建步骤（适用于 TUI 贡献者）
hermes --tui --dev

你也可以通过环境变量启用：

export HERMES_TUI=1
hermes # 现在使用 TUI
hermes chat # 相同

或者将其设为 ~/.hermes/config.yaml 中的持久默认值：

display:
  interface: tui # "cli"（默认）或 "tui"

当 display.interface: tui 时，单独的 hermes（以及 hermes chat）会启动 TUI。显式标志始终优先——运行 hermes --cli 可暂时回到经典 REPL，或使用 hermes --tui / HERMES_TUI=1 在配置默认为 cli 时强制使用 TUI。

经典 CLI 仍然是默认发行版本。所有在 CLI 界面 中记录的——斜杠命令、快速命令、技能预加载、角色、多行输入、中断——在 TUI 中完全相同。

为什么选择 TUI

• 即时首帧 — 在应用完全加载完成之前，横幅就会显示，因此终端在 Hermes 启动时不会显得卡顿。
• 非阻塞输入 — 在会话准备好之前即可输入和排队消息。你的第一条提示会在 agent 上线时立即发送。
• 丰富的覆盖层 — 模型选择器、会话选择器、批准和澄清提示都以模态面板形式呈现，而非内联流程。
• 实时会话面板 — 工具和技能在初始化时会逐步显示。
• 鼠标友好的选择 — 拖拽可高亮显示，带有统一背景，而非 SGR 反向显示。使用终端正常的复制手势进行复制。
• 备用屏幕渲染 — 差异更新意味着流式传输时无闪烁，退出后无滚动回混乱。
• 编辑器辅助功能 — 内联粘贴折叠长片段，Cmd+V / Ctrl+V 文本粘贴带有剪贴板图片回退，括起来的粘贴安全性，以及图片/文件路径附加规范化。
• 同样支持 皮肤 和 角色。在会话中通过 /skin ares、/personality pirate 切换，UI 会实时重绘。参见 皮肤与主题 获取所有可定制键的完整列表，以及哪些适用于经典 CLI 与 TUI——TUI 尊重横幅调色板、UI 颜色、提示符字形/颜色、会话显示、完成菜单、选择背景、tool_prefix 和 help_header。

可折叠的横幅部分

TUI 启动横幅将运行时信息分为四个可折叠部分，每个部分标题旁边都有一个 ▸ / ▾ 箭头：

点击任何部分标题（或其箭头）可切换状态。工具列表默认打开，因为它是会话启动时最常检查的部分；技能、系统提示和 MCP 服务器默认折叠，因此即使你安装了数十个技能或连接了许多 MCP 服务器，横幅也能保持紧凑。状态是横幅实例本地的，因此下次启动会重置为默认值。

要求

• Node.js ≥ 20 — TUI 作为从 Python CLI 启动的子进程运行。hermes doctor 会验证这一点。
• TTY — 与经典 CLI 一样，当通过管道输入 stdin 或在非交互式环境中运行时，会回退到单查询模式。

首次启动时，Hermes 会将 TUI 的 Node 依赖项安装到 ui-tui/node_modules（一次性操作，需要几秒钟）。后续启动会很快。如果你拉取了新版本的 Hermes，当源文件比 dist 文件更新时，TUI 包会自动重建。

外部预构建

提供预构建包的发行版（Nix、系统包）可以将 Hermes 指向该包：

export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui

目录必须包含 dist/entry.js。

键绑定

键绑定与 经典 CLI 完全相同。唯一的区别在于行为：

• 鼠标拖拽 会用统一的选择背景高亮文本。
• Cmd+V / Ctrl+V 首先尝试正常文本粘贴，然后回退到 OSC52/原生剪贴板读取，最后在剪贴板或粘贴的内容解析为图片时附加图片。
• /terminal-setup 安装本地 VS Code / Cursor / Windsurf 终端绑定，以实现更好的 Cmd+Enter 和撤销/重做在 macOS 上的一致性。
• 斜杠自动补全 以浮动面板形式打开，带有描述，而不是内联下拉框。
• Ctrl+X 打开实时会话切换器。当已排队的消息被高亮（在 agent 仍在运行时发送）时，它仍会删除该排队消息。
• Esc 取消编辑并取消高亮，而不删除。
• Ctrl+G / Ctrl+X Ctrl+E — 在 $EDITOR 中打开当前输入缓冲区以进行多行/长提示编辑；保存并退出会将内容作为提示发送回去。

斜杠命令

所有斜杠命令都保持不变。一些命令由 TUI 拥有——它们会产生更丰富的输出或渲染为覆盖层而非内联面板：

其他所有斜杠命令（包括已安装的技能、快速命令和角色切换）都与经典 CLI 相同。参见 斜杠命令参考。

实时会话切换器

当你希望一个终端作为多个 TUI 会话的调度器时，使用实时会话切换器。它只列出当前在此 TUI 进程中活跃的会话；已关闭的会话作为保存的转录保留，仍可以使用 /resume 或 hermes --tui --resume <ID> 重新打开。

使用以下任一方式打开：

• TUI 中的 Ctrl+X
• /sessions 或 /switch
• /sessions new 立即创建一个新的实时会话
• 点击状态行中的 N live sessions 计数

在切换器内部：

• ↑ / ↓ 移动选择；鼠标点击也可选择行。
• Enter 切换到选中的实时会话。
• Ctrl+D 关闭选中的实时会话。
• Ctrl+N 启动一个空白的实时会话。
• Ctrl+R 刷新实时会话列表。
• Esc 关闭切换器。
• 选择 +new，输入提示，然后按 Enter 可启动一个新的实时会话。如果你希望先为那个新会话选择模型，请先按 Tab。

LaTeX 数学渲染

TUI 的 markdown 管道会内联渲染 LaTeX 数学：$E = mc^2$ 和 $$\frac{a}{b}$$ 会渲染为 Unicode 格式的数学公式，而不是原始的 TeX 源码。适用于内联和块级数学；不支持的语法会回退为显示原始 TeX，包裹在代码片段中以便复制。此功能始终启用——无需配置。经典 CLI 保留原始 TeX。

浅色终端检测

TUI 会自动检测浅色终端并相应切换到浅色主题。检测分三层进行：

1. HERMES_TUI_THEME 环境变量——最高优先级。值：light、dark 或原始 6 字符背景十六进制（例如 ffffff、1a1a2e）。
2. COLORFGBG 环境变量——经典的“我的背景色是什么？”提示，由 xterm 衍生终端使用。
3. 通过 OSC 11 探测终端背景——适用于不设置 COLORFGBG 的现代终端（Ghostty、Warp、iTerm2、WezTerm、Kitty）。

如果你希望永久使用浅色主题，无论终端如何：

export HERMES_TUI_THEME=light

忙碌指示器样式

状态栏的忙碌指示器是可插拔的——默认情况下，在 agent 工作期间，每 2.5 秒旋转一次 Hermes 的卡哇伊表情调色板。通过配置或 /indicator 斜杠命令选择不同的样式：

display:
  tui_status_indicator: kaomoji # kaomoji | emoji | unicode | ascii

或在会话中：/indicator emoji（等等）。样式自带匹配的字形宽度，所以状态栏的其余部分不会在旋转时抖动。

自动恢复

默认情况下，hermes --tui 每次启动都会创建一个新会话。要自动重新附加到最近的 TUI 会话（当你的终端或 SSH 连接意外断开时很有用），请选择启用：

export HERMES_TUI_RESUME=1 # 最近的 TUI 会话
# 或：export HERMES_TUI_RESUME=<ID> # 特定会话

取消设置该变量或显式传递 --resume <ID> 可每次启动时覆盖。

状态行

TUI 的状态行实时跟踪 agent 状态：

每个皮肤的状态栏颜色和阈值与经典 CLI 共享——参见 皮肤 了解自定义。状态行还显示：

• 带有 git 分支的工作目录 — ~/projects/hermes-agent (docs/two-week-gap-sweep)。分支后缀会在你侧边终端执行 git checkout 时更新（基于 mtime 缓存），因此 TUI 反映的是你实际活跃的分支，而不是启动时的分支。
• 每轮提示耗时 — 当轮次正在运行时显示 ⏱ 12s/3m 45s（实时），轮次完成后冻结为 ⏲ 32s / 3m 45s。第一个数字是自上次用户消息以来的时间；第二个是总会话持续时间。每个新提示都会重置。
• 🗜️ N — 当前会话被自动压缩的次数。在第一次压缩触发后出现。
• ▶ N — 此会话中正在运行的后台任务数量。只要有至少一个任务在进行中，就会显示。
• ⚠ YOLO — 当 YOLO 模式开启（hermes --yolo、/yolo 或 HERMES_YOLO_MODE=1）时的可见警告。同样的徽章也会出现在启动横幅中，这样你就不会在未注意到的情况下启动自动批准的会话。

配置

TUI 遵循所有标准的 Hermes 配置：~/.hermes/config.yaml、配置文件、角色、皮肤、快速命令、凭证池、记忆提供者、工具/技能启用。没有仅适用于 TUI 的配置文件。少量键专门调整 TUI 界面：

display:
  skin: default # 任何内置或自定义皮肤
  personality: helpful
  details_mode: collapsed # hidden | collapsed | expanded — 全局手风琴默认
  sections: # 可选：按部分覆盖（任意子集）
    thinking: expanded # 始终打开
    tools: expanded # 始终打开
    activity: collapsed # 选择重新启用活动面板（默认隐藏）
  mouse_tracking: all # off | wheel | buttons | all（或 true/false 以向后兼容）
    # wheel — 1000+1006（滚动 + 点击；无拖拽，无悬停 —
    # 在 tmux 内推荐使用，以消除提示行的
    # "No image in c