HeyRocky

Use Hermes CLI Shell Mode Without Polluting Agent Context

Hermes CLI shell mode runs a command directly when a line begins with !. The model is not called, and neither the command nor its output is added to conversation history.

> !git status
> !pwd
> !pytest -x tests/cli

Use it for fast, deterministic checks that you understand and would have run in a separate terminal. It saves model latency and keeps transient command output out of the agent context and prompt cache.

Understand the boundary

Shell mode:

  • uses the same session working directory as the agent terminal;
  • shows nonzero exits explicitly;
  • keeps normal dangerous-command approvals;
  • avoids an API call and token use;
  • is available in the interactive CLI, not messaging gateways or cron delivery.

It is not a security bypass. A risky deletion or protected configuration write still follows Hermes approval policy.

Decide between shell mode and the agent

Use ! when the command and interpretation are both obvious. Ask the agent when you need it to select tools, inspect several results, explain an error, or carry verification through to a deliverable.

A productive pattern is:

  1. Run !git status to establish a quick baseline.
  2. Ask Hermes to implement a bounded change.
  3. Let Hermes run the verification required by its task.
  4. Use !git diff --check as an independent final sanity check if appropriate.

Do not use shell mode to hide important evidence from a session that must reason about that evidence. If the agent needs the output, give it the relevant result or let its terminal tool run the command.

Safety checklist

  • The command is deterministic and fully understood.
  • The current working directory is confirmed.
  • No secret will be printed into the terminal transcript.
  • The command does not bypass a needed review or verification narrative.
  • Any failure that needs reasoning is brought back into the agent workflow.

Common pitfalls

  • Assuming output becomes context. Shell-mode output is intentionally absent from conversation history.
  • Using it on gateway platforms. A leading exclamation mark there is not the CLI shell shortcut.
  • Running a broad command from the wrong directory. Check !pwd before destructive or expensive work.
  • Confusing speed with safety. Approval rules still matter, and external side effects still require the same judgment.

Verification

Run !pwd and !git status in a disposable CLI session. Confirm the working directory is correct, then ask Hermes what commands it has seen in the conversation; the shell-mode command should not have been inserted into chat history. Test a harmless failing command and confirm the nonzero exit is visible.

Official reference: Hermes CLI shell mode.

Related pages