A Hermes Agent customization: the dsfox-skin theme, a patched terminal UI,
optional independent response review, and capability-evaluation preparation tools.
The default installer installs the visual customization without modifying the
Hermes source checkout and rebuilds it after each hermes update. The optional
reviewer has a separate explicit host-patch step; evaluation runs only on request.
| Part | What you get |
|---|---|
Skin (skins/dsfox-skin.yaml) |
Muted green ANSI-256 palette, high-contrast diffs, DSFOX-AGENT wordmark |
TUI patch (patches/hermes-tui.patch) |
Chat canvas #1c1c1c, black user messages and composer, compact transcript, themed choice cards, activity status indicator with elapsed-time colors, copy-on-select on every platform (drag, double-click word, triple-click line) with a confirmation, a bright-green stats line after each final reply (time without and with waiting for your answers, tokens/s for the task and for the model, estimated cost ≈$ at API prices) |
Refusal retry (plugins/refusal-retry/) |
When the provider's safety filter refuses a request and no fallback provider is configured, the same request is sent again after 10 s and after 60 s; the third refusal ends the turn as before |
Repo guard (plugins/repo-guard/) |
A chat working inside one git repository asks you before any tool call reaches another repository (each project keeps its own chat) |
Tool preview (plugins/tool-preview/) |
Tool rows in the TUI show the call's arguments up to display.tool_preview_length (0 = no limit, the default) instead of a fixed 80 characters; with the TUI patch the row itself uses the window width |
Local Heretic route (plugins/heretic-route/) |
A TUI message that starts with _ runs one full agent turn on the local Heretic model (/heretic): the same tools, rules, memory and skills as the cloud model, and it sees the whole chat. The turn is never stored in the chat, so the cloud model never sees it and its prompt cache is untouched; Heretic keeps its own per-chat view (compressed by its own compressor when the chat outgrows its window). __ turns thinking on, /heretic --reset clears the view. Needs the heretic model alias (see local Heretic agent); heretic_route.alias in config.yaml names another alias |
| Optional skill notes | Extended hermes-agent skill notes |
| Question wizard | Batched selectors and checkboxes, Back/Next, editable review, one final submission; see question wizard |
| Optional response review | Local Heretic review, separate attributed output, independent primary-agent assessment; see response review |
| Capability evaluation (preparation stage) | Metadata inventory, synthetic comparison inputs and typed outcome checks; no automatic model runs, rankings or archival; see capability evaluation |
Without the patch the skin still applies colors and branding; the canvas,
message backgrounds, choice cards and activity indicator need the patch.
- Hermes Agent installed with the official installer (a git checkout under the
Hermes home), started at least once in TUI mode (
hermes --tui) so its Node dependencies exist. hermesonPATH(the installer callshermes skin useandhermes config set).gitand Python 3.9+ (the macOS system/usr/bin/python3is enough).
| Platform | Hermes home | Python command |
|---|---|---|
| macOS, Linux | ~/.hermes |
python3 |
| Windows | %LOCALAPPDATA%\hermes |
py -3 (Python launcher) |
HERMES_HOME, when set, overrides the Hermes home.
macOS / Linux:
git clone https://github.com/dsfox-idea/hermes-setup.git
cd hermes-setup
python3 -I scripts/setup.py installWindows (PowerShell):
git clone https://github.com/dsfox-idea/hermes-setup.git
cd hermes-setup
py -3 -I scripts\setup.py installFor every profile (default and each one under profiles/) the script:
- copies the skin into
<profile>/skins/and runshermes skin use dsfox-skin; - sets
display.interface tuianddisplay.tui_compact true; - builds the patched TUI into
<Hermes home>/tui-overlay/ui-tui-<version>and points Hermes at it withHERMES_TUI_DIRin the profile's.env; - sets
display.tui_status_indicator activity; - makes
soul/SOUL.mdthe profile'sSOUL.md(the agent's standing rules, in Russian); a different existingSOUL.mdis first copied to<profile>/backups/hermes-setup-<timestamp>/; - installs the
tui-overlaygateway hook into<Hermes home>/hooks/; - copies
plugins/refusal-retry,plugins/repo-guard,plugins/tool-previewandplugins/heretic-routeinto<profile>/plugins/, enables them and checks that refusal-retry fits the installed Hermes version.
Options, combinable:
| Option | Effect |
|---|---|
--timezone Europe/Berlin |
Sets timezone in every profile |
--skill |
Replaces the hermes-agent skill with skills/autonomous-ai-agents/hermes-agent |
--keep-soul |
Leaves every profile's SOUL.md as it is (step 5 is skipped) |
--skill first backs up the replaced skill to
<profile>/backups/hermes-setup-<timestamp>/.
Exit code 1 means the patch or the refusal-retry plugin does not fit your Hermes
version: the skin is installed, the stock TUI stays (or the plugin leaves Hermes
unchanged and logs refusal-retry inactive), and the reason is in the output.
Two lines in the output look like errors and are not: HERMES_TUI_DIR='' in profile ... (the old build is switched off before the new one is made; the path
is filled in a few seconds later) and the esbuild size warning entry.js 3.9mb.
The gateway hook starts working after the next gateway start. Run
hermes gateway restart once, or let the next hermes update do it; until then
an update is not followed by a rebuild.
The provider's safety filter sometimes refuses an ordinary request (for example
Anthropic's "Cyber safeguards flagged this message"). Hermes treats a refusal as
final: it tries a configured fallback provider once, otherwise the turn ends. The
refusal-retry plugin keeps the fallback step and, with no fallback left, waits
and sends the same request again. While it waits the chat shows
⏳ The provider's safety filter refused the request — retrying automatically in 10 s (retry 1/2);
Esc stops the wait. If every retry is refused, the usual error message ends with
Retried 2 times (after 10 s, 60 s); the filter refused every attempt.
The count is per model request, so a normal answer starts the next one at zero. Both ways Hermes reports a refusal are covered: an answer that stops with a refusal and an API error classified as a content-policy block. To change the waits (seconds, at most 5 retries of up to 600 s; an empty list turns retries off):
hermes config set plugins.entries.refusal-retry.settings.delays '[10, 60]'The plugin wraps two internal Hermes functions at load time and does not modify
the source checkout. After hermes update, scripts/setup.py install reruns its
compatibility test. It takes effect in sessions started after installation: new
TUI windows and the gateway after its next start.
python3 -I scripts/setup.py status # Windows: py -3 -I scripts\setup.py statusIt must print patched TUI current: True. Then open a new TUI window
(hermes): the canvas is dark gray and the wordmark reads DSFOX-AGENT.
Windows that were already open keep the old interface until restarted.
hermes config get display.tui_compact warns that the key is not recognized.
That is expected: the TUI reads this key, the configuration validator does not
know it.
Nothing to do. The update restarts the gateway; the tui-overlay hook then
compares the Hermes version with the last build and rebuilds in the background
(about 15 s). Until the rebuild finishes, and permanently if the patch no longer
fits, Hermes uses its stock TUI. The last run is logged in
<Hermes home>/hooks/tui-overlay/last-run.log.
To take a newer version of this customization:
git pull
python3 -I scripts/setup.py install # Windows: py -3 -I scripts\setup.py installpython3 -I scripts/setup.py uninstall # Windows: py -3 -I scripts\setup.py uninstallThis restores the default skin and the stock TUI in every profile and removes
the hook. SOUL.md stays; the previous one, and backups from --skill, are in
<profile>/backups/.
| Platform | Note |
|---|---|
| Windows | Hermes refuses to modify its own running checkout; this setup never does. The build links Node dependencies with NTFS junctions. |
| Warp | Shift+Enter inserts a newline (Warp sends it as LF; the patch treats LF as newline under TERM_PROGRAM=WarpTerminal). |
| macOS | Terminals inside IDEs or agents may export PYTHONPATH or NODE_ENV; -I keeps PYTHONPATH out of the run, and Terminal.app or iTerm avoids both. |
| Linux | Same commands as macOS. Not yet exercised on Linux. |
When a chat's working directory is inside a git repository, every tool call is
checked before it runs: the path/workdir arguments of any tool, and the paths
a terminal command or execute_code source names (absolute, ~/, $HOME/,
../, and the targets of cd, pushd, git -C). If one of them lies in a
different repository, Hermes' normal approval prompt appears, naming both
repositories. "Once" or "session" continues in this chat; "deny" stops the step
and tells the agent to name the mismatch and offer to hand the work to that
project's chat. A chat without a repository (a service chat, a chat in the home
directory) is not checked. Paths outside any repository, the Hermes home and
repositories nested inside the session's own pass. Runs without anyone to answer
(hermes chat -q, cron) follow approvals.single_query_mode / approvals.cron_mode;
the default deny blocks the step.
Directories that never count as foreign:
hermes config set plugins.entries.repo-guard.settings.allow '["/path/to/shared-repo"]'The command parsing is a heuristic: a path assembled at run time (D=x; cd $D)
is not seen.
| Path | Purpose |
|---|---|
scripts/setup.py, scripts/tui_overlay.py |
Installer and patched-TUI builder (tui_overlay.py status/ensure/disable handles the TUI alone) |
hooks/tui-overlay/ |
Gateway hook that rebuilds the TUI after updates |
soul/SOUL.md |
Default agent rules installed into every profile (stock Hermes intro, then 47 working rules in Russian) |
config.example.json |
Non-secret configuration example; set single keys with hermes config set, never copy it over a profile |
upstream.json |
Hermes revision the patch was cut from, and the patch checksum |
plugins/repo-guard/ |
Repo-guard plugin and its tests (python3 -m unittest discover -s plugins/repo-guard/tests) |
plugins/tool-preview/ |
Tool-preview plugin and its tests (hermes --run-module unittest discover -s plugins/tool-preview/tests) |
plugins/heretic-route/ |
Heretic-route plugin and its tests (hermes --run-module unittest discover -s plugins/heretic-route/tests) |
plugins/refusal-retry/ |
Refusal-retry plugin and its tests (hermes --run-module unittest discover -s plugins/refusal-retry/tests) |
plugins/heretic-reviewer/, scripts/install_review.py |
Explicit, single-profile installation of local response review |
patches/response-review-host.patch |
Optional Python-host support; unlike the default TUI overlay, applying this modifies the selected source checkout |
scripts/skill_evaluation.py, scripts/prepare_skill_trials.py, evaluations/skill-selection/ |
Portable capability inventory and preparation-only evaluation inputs |
skills/ |
Skill snapshots, including optional local-model skills |
models/, plugins/honcho/ |
Reference material for optional local models and the Honcho memory plugin; read their own README before use |
docs/maintaining.md |
Updating and publishing this repository |