HeyRocky

Inspect Hermes Sessions with Diff, Focus, and Context

A productive session audit answers four different questions: Which conversation did I resume? What changed in the workspace? What is consuming the model's context window? How much operational detail do I want to see on screen? Hermes has separate commands for each layer. Keeping those layers distinct prevents a quiet display from being mistaken for a small context, or a Git diff from being mistaken for conversation history.

Find and resume the correct session

Hermes stores session metadata and full message history in the active profile's ~/.hermes/state.db. Start outside the chat by listing or browsing sessions:

hermes sessions list
hermes sessions list --workspace <project-name>
hermes sessions browse

--workspace matches a path substring or an exact directory basename. The interactive browser supports search and resume. Once you know the session, resume by ID or title:

hermes --resume <session-id>
hermes -c "<session-title>"

A named continuation lineage may contain titles such as a base name plus numbered variants. Resuming by the base title selects the most recent variant. Resuming a CLI session also restores its recorded working directory unless --no-restore-cwd is supplied.

Do not inspect ~/.hermes/sessions/sessions.json as though it were the master session list. The docs identify it as a legacy gateway-routing mirror; CLI, TUI, gateway, and dashboard sessions are all listed from state.db.

Confirm the resumed session before acting

Inside the session, use read-only local commands first:

/status
/history

/status reports the model, provider, profile, session ID, working directory, title, timestamps, token totals, and whether the agent is running. It also adds a locally computed recap with recent turn counts, tool-result counts, top tools, recently touched files, and the latest user and assistant messages. It makes no LLM call and does not affect prompt caching.

/history shows the conversation history. Use it when the recap is too compact, but avoid copying a large transcript back into a new prompt; the session already contains that history.

Inspect workspace changes with /diff

The /diff command inspects Git state, not chat state. Its forms are:

/diff
/diff staged
/diff all --stat
/diff session --stat
/diff session path/to/file
  • Bare /diff shows unstaged changes plus untracked files.
  • /diff staged shows the index.
  • /diff all shows everything since HEAD.
  • --stat gives a changed-file summary before you read a full patch.
  • Relative path arguments narrow the result to the files you care about.
  • /diff session shows the cumulative change from the earliest retained checkpoint baseline for the session.

The session form requires checkpoints. Checkpoints are opt-in, so launch a work session with:

hermes chat --checkpoints

You can also enable checkpoints.enabled in configuration. If no retained checkpoint baseline exists, /diff session cannot reconstruct an agent-only cumulative patch. In that case, use ordinary Git scopes and /rollback diff <N> for a specific available checkpoint rather than assuming the session view is complete.

Inspect the context window with /context

Run:

/context
/context all

/context renders a visual usage grid and an estimated category table covering the system prompt, tool definitions, project rules, skills index, MCP content, subagents, memory, conversation, and free space. /context all expands the report with per-skill and per-toolset costs. Both are local and read-only: they do not call the model or alter the prompt cache.

Session storage and active context are not the same thing. Hermes can keep a full transcript in state.db while sending only the current conversation window and explicitly injected material to the model. Raw image, audio, and binary document bytes are not repeatedly copied into later prompts. Large pasted text, logs, tool outputs, and diffs are more common sources of context growth.

If the session is genuinely too large, use /compress; do not expect /focus to reduce it.

Use focus view after the audit

Focus view is for display control:

/focus status
/focus on
/focus off

When enabled, it shows the prompt and final answer while suppressing tool-progress detail. Hermes remembers the previous /verbose mode and restores it when focus view turns off. A status-bar badge and a recovery line make the hidden activity visible as a count.

Focus view does not edit conversation history, the system prompt, tool schemas, or request payloads. It is display-only and leaves prompt caching unchanged. Turn it off when debugging a failed tool call; turn it on when the session is healthy and you want less terminal noise.

A practical inspection workflow

  • Locate the session with hermes sessions list --workspace or hermes sessions browse.
  • Resume it and run /status before any file-changing request.
  • Start with /diff --stat, then select staged, all, or session and a path as needed.
  • Run /context, escalating to /context all only when you need the detailed cost sources.
  • Use /focus on only after you know the session, workspace, diff scope, and context state are correct.

Pitfalls

  • Focus view is not compression, deletion, redaction, or a privacy boundary. It only changes rendering.
  • /diff session is checkpoint-based. It is not guaranteed to equal all work ever associated with a title, especially after checkpoint pruning or when checkpoints were disabled.
  • A resumed title can point to the newest lineage member. Confirm the exact ID and working directory with /status.
  • The default /diff is not "everything Hermes changed." It is current unstaged and untracked work.
  • A large state.db does not prove the current prompt is full; use /context for the active-window estimate.
  • Resuming with --no-restore-cwd is useful, but it also makes it easier to inspect or edit the wrong checkout. Confirm the workspace explicitly.

Verification checklist

  • Verify the session ID, title, profile, model, and working directory with /status.
  • Verify the selected diff scope matches the question you are asking: working tree, staged, all since HEAD, or checkpoint-backed session changes.
  • Verify checkpoints were enabled and retained before relying on /diff session.
  • Verify /context shows the expected categories and enough free space for the next task.
  • Verify /focus status reflects whether tool detail is intentionally hidden.
  • Verify /focus off restores the diagnostic view before investigating a failure.

Official references

Related pages