better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/cli.md

@@ -0,0 +1,591 @@
+---
+sidebar_position: 1
+title: "CLI Interface"
+description: "Master the Hermes Agent terminal interface — commands, keybindings, personalities, and more"
+---
+
+# CLI Interface
+
+Hermes Agent's CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal.
+
+:::tip First-time setup
+One command — `hermes setup --portal` — and you're ready to `hermes chat`. See [Nous Portal](/integrations/nous-portal).
+:::
+
+:::tip
+Hermes also ships a modern TUI with modal overlays, mouse selection, and non-blocking input. Launch it with `hermes --tui` — see the [TUI](tui.md) guide.
+:::
+
+## Running the CLI
+
+```bash
+# Start an interactive session (default)
+hermes
+
+# Single query mode (non-interactive)
+hermes chat -q "Hello"
+
+# Single query from a file or stdin — nothing is shell-interpreted, so
+# arbitrary text (quotes, $(...), backticks) arrives verbatim
+hermes chat --query-file prompt.txt
+hermes chat --query-file - < prompt.txt
+
+# With a specific model
+hermes chat --model "anthropic/claude-sonnet-4"
+
+# With a specific provider
+hermes chat --provider nous        # Use Nous Portal
+hermes chat --provider openrouter  # Force OpenRouter
+
+# With specific toolsets
+hermes chat --toolsets "web,terminal,skills"
+
+# Start with one or more skills preloaded
+hermes -s hermes-agent-dev,github-auth
+hermes chat -s github-pr-workflow -q "open a draft PR"
+
+# Resume previous sessions
+hermes --continue             # Resume the most recent CLI session (-c)
+hermes --resume <session_id>  # Resume a specific session by ID (-r)
+hermes --resume latest        # Resume the most recent session (same as -c)
+hermes --resume latest --in ./dir  # Resume ./dir's latest session, staying in ./dir
+
+# Verbose mode (debug output)
+hermes chat --verbose
+
+# Isolated git worktree (for running multiple agents in parallel)
+hermes -w                         # Interactive mode in worktree
+hermes -w -z "Fix issue #123"     # Single query in worktree
+```
+
+### Worktree cleanup
+
+`hermes -w` sessions create disposable worktrees under `<repo>/.worktrees/`.
+A conservative pruner runs automatically at startup (it only removes clean,
+fully-merged scratch trees past an age threshold), but preserved trees and
+merged local branches still accumulate on busy machines. Reclaim them
+explicitly:
+
+```bash
+hermes worktree list              # audit: age, size, verdict, reason per tree
+hermes worktree list --json       # machine-readable audit (trees, external trees, branches)
+hermes worktree prune             # remove safe trees + delete merged branches
+hermes worktree prune --dry-run   # show the plan without changing anything
+hermes worktree prune --older-than 7   # only reap trees idle for 7+ days
+hermes worktree prune --trees-only     # leave local branches alone
+hermes worktree prune --branches-only  # leave worktrees alone
+```
+
+Worktrees registered **outside** `.worktrees/` (created by hand or by another
+tool) are reported read-only in `list` output and are never removed. The one
+exception is metadata: registrations whose directory no longer exists are
+dropped via `git worktree prune` (no files are touched). `--older-than DAYS`
+only ever narrows what gets reaped — a tree carrying real work is kept at any
+age regardless of the flag.
+
+Inside a session, `/worktree prune [--dry-run]` does the same (and never
+touches the tree the session is running in).
+
+Safety guarantees (all modes, any age):
+
+- Uncommitted **tracked** changes are never deleted.
+- **Unique unpushed commits** are never deleted — commits that were
+  rebase/squash-merged upstream are detected via `git cherry`
+  patch-equivalence and count as merged, which is what lets the dominant
+  "merged PR, tree preserved forever" leak finally reclaim.
+- **Repositories without a remote** are judged against the local trunk
+  (`main`/`master`, else the branch checked out in the main worktree): only
+  trees and branches whose commits are reachable from — or patch-equivalent
+  to — that trunk are reclaimed. With no trunk to compare against, every tree
+  and branch is preserved.
+- **Pushed open-PR lanes free their disk without losing anything**: when a
+  clean tree's branch head exactly matches what `origin` holds (checked with
+  one `git ls-remote` per sweep), the checkout is redundant — the tree is
+  removed but its **branch ref is kept**, so the lane is one
+  `git worktree add .worktrees/<name> <branch>` away from restored. If the
+  remote can't be reached, the tree is preserved.
+- Trees **in use by a running hermes session** are never touched.
+- **Untracked-only scratch** (PR body drafts, notes) is archived to
+  `~/.hermes/archive/worktree-prune/` before its tree is removed — never
+  destroyed.
+- Branch deletion is content-gated, not name-gated: any local branch whose
+  commits are all on upstream is safe to delete; branches with unique work,
+  checked-out branches, and `main`/`master`/`develop` are always kept.
+
+The same conservative pruner also runs from the cron scheduler (at most once
+every 6 hours, in the background), so gateway-only machines — where nobody
+launches `hermes -w` for days — no longer accumulate merged scratch trees
+between CLI sessions.
+
+When `.worktrees/` grows past 10 trees or 5 GB, startup prints a one-line
+notice pointing at these commands.
+
+### Plugin management
+
+The `hermes plugins` commands manage native Hermes plugins and portable Agent
+Plugins v1 packages through the same opt-in workflow:
+
+```bash
+hermes plugins install owner/repository --no-enable
+hermes plugins list
+hermes plugins enable <plugin-name>
+hermes plugins disable <plugin-name>
+hermes plugins update <plugin-name>
+hermes plugins remove <plugin-name>
+```
+
+Portable packages remain disabled until explicitly enabled. Hermes currently
+loads portable Agent Skills and stdio MCP entries. See the
+[plugin developer guide](/developer-guide/plugins#portable-agent-plugins-v1-packages)
+for the exact supported subset and trust boundary.
+
+## Interface Layout
+
+<img className="docs-terminal-figure" src="/docs/img/docs/cli-layout.svg" alt="Stylized preview of the Hermes CLI layout showing the banner, conversation area, and fixed input prompt." />
+<p className="docs-figure-caption">The Hermes CLI banner, conversation stream, and fixed input prompt rendered as a stable docs figure instead of fragile text art.</p>
+
+The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.
+
+### Status Bar
+
+A persistent status bar sits above the input area, updating in real time:
+
+```
+ ☤ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m
+```
+
+| Element | Description |
+|---------|-------------|
+| Model name | Current model (truncated if longer than 26 chars) |
+| Token count | Context tokens used / max context window; `~` marks an estimate |
+| Context bar | Visual fill indicator with color-coded thresholds |
+| Cost | Estimated session cost (or `n/a` for unknown/zero-priced models) |
+| 🗜️ N | **Context compression count** — how many times the running session has been auto-compressed. Appears once the first compression fires. |
+| ▶ N | **Active background tasks** — how many `/bg` prompts are still running in the current session. Appears whenever at least one task is in flight. |
+| Duration | Elapsed session time |
+| Session title | Once the session has a title, it appears as a gold badge pinned to the far-right edge. Long titles truncate before displacing the essential model and context fields. |
+| ⚠ YOLO | **YOLO mode warning** — shown whenever `HERMES_YOLO_MODE` is on (either `hermes --yolo` at launch or `/yolo` toggled mid-session). Mirrors the banner-line warning so you can't forget you're in auto-approve mode. |
+
+A `~` before a context count or percentage means it includes a local estimate. This also applies to gateway `/status` and `/context`, the TUI, and the Desktop context gauge. An unchanged provider-usage reading has no `~`; a provider anchor plus unpriced new messages does. `/context` reports the selected source. Category, free-space, skill, and toolset breakdowns are always local estimates, even when the overall occupancy comes from provider usage. These display labels do not change compaction decisions or make extra provider requests.
+
+The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration, plus the YOLO badge when active) below 52.
+
+**Context color coding:**
+
+| Color | Threshold | Meaning |
+|-------|-----------|---------|
+| Green | < 50% | Plenty of room |
+| Yellow | 50–80% | Getting full |
+| Orange | 80–95% | Approaching limit |
+| Red | ≥ 95% | Near overflow — consider `/compress` |
+
+Use `/usage` for a detailed breakdown including per-category costs (input vs output tokens).
+
+On the `openai-codex` provider, `/usage` also shows any banked usage-limit resets on your ChatGPT account ("You have N resets banked - use /usage reset to activate"). `/usage reset` redeems one banked reset, fully restoring your 5-hour and weekly limits. Hermes refuses to redeem while your limits aren't exhausted (a banked reset restores the full allowance, so spending it early wastes it) — pass `/usage reset --force` to redeem anyway.
+
+### Session Resume Display
+
+When resuming a previous session (`hermes -c` or `hermes --resume <id>`), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of the conversation history. See [Sessions — Conversation Recap on Resume](sessions.md#conversation-recap-on-resume) for details and configuration.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send message |
+| `Alt+Enter`, `Ctrl+J`, or `Shift+Enter` | New line (multi-line input). `Shift+Enter` requires a terminal that distinguishes it from `Enter` — see below. On Windows Terminal, `Alt+Enter` is captured by the terminal (fullscreen toggle); use `Ctrl+Enter` or `Ctrl+J` instead. |
+| `Alt+V` | Paste an image from the clipboard when supported by the terminal |
+| `Ctrl+V` | Paste text and opportunistically attach clipboard images |
+| `Ctrl+B` | Start/stop voice recording when voice mode is enabled (`voice.record_key`, default: `ctrl+b`) |
+| `Ctrl+G` | Open the current input buffer in `$EDITOR` (vim/nvim/nano/VS Code/etc.). Save and quit to send the edited text as the next prompt — ideal for long, multi-paragraph prompts. |
+| `Ctrl+X Ctrl+E` | Emacs-style alternate binding for the external editor (same behavior as `Ctrl+G`). |
+| `Ctrl+S` | **Stash the prompt.** Parks the current draft and clears the composer so you can send something else first. Press `Ctrl+S` again on an empty composer to bring the draft back (cursor at the end, attached images restored). Repeated presses build a stack rather than overwriting, so an earlier draft is never silently lost — with two or more stashed, `Ctrl+S` opens a browse panel (`↑`/`↓` to navigate, `Enter` to restore, `D` to discard, `Esc` or `Ctrl+S` to close). A `📌 N` badge in the status bar shows how many drafts are parked. Multi-line drafts round-trip exactly, including blank lines. The stash lives in memory for the session only — nothing is written to disk, since drafts often contain secrets. |
+| `Ctrl+C` | Interrupt agent (double-press within 2s to force exit) |
+| `Ctrl+T` / `F6` | Open the full-screen live subagent monitor without losing the composer draft. The live dock appears automatically above the status bar; arrows select a worker, `Enter` shows its recent log, `s` steers, and `x` requests stop with confirmation. See [Monitoring subagents](/user-guide/features/delegation#monitoring-running-subagents-agents). |
+| `F7` | Toggle the live subagent dock between its multi-row preview and a single summary line without moving composer focus. |
+| `Ctrl+D` | Exit |
+| `Ctrl+Z` | Suspend Hermes to background (Unix only). Run `fg` in the shell to resume. |
+| `Tab` | Accept auto-suggestion (ghost text) or autocomplete slash commands |
+| `!<command>` | **Shell mode** — run a shell command yourself without spending a model turn (e.g. `!git status`, `!pytest -x`). See below. |
+
+**Multiline paste preview.** When you paste a multi-line block, the CLI echoes a compact single-line preview (`[pasted: 47 lines, 1,842 chars — press Enter to send]`) instead of dumping the whole payload into the scrollback. The full content is still what gets sent; this is just display polish.
+
+### `!` Shell Mode
+
+Start a line with `!` to run it as a shell command instead of sending it to the agent:
+
+```
+> !git status
+> !ls -la
+> !pytest -x tests/hermes_cli
+```
+
+- **Zero cost.** The model is never invoked — no API call, no tokens, no latency.
+- **Nothing enters the conversation.** The command and its output are not added to history, so your context stays clean and the prompt cache is untouched.
+- **Runs where the agent's `terminal` tool runs.** Uses the session working directory, so `!pwd` matches what the agent would see.
+- **Approvals still apply.** A dangerous command (`rm -rf`, writes to `~/.hermes/config.yaml`, etc.) goes through the same approval prompt the agent's `terminal` tool uses. `!` is a cost/latency shortcut, not a security bypass.
+- **Non-zero exits are shown.** A failing command prints `! exited <code>` after its output.
+- `!` on its own prints a one-line usage reminder.
+
+Shell mode is CLI-only. Gateway platforms (Discord, Telegram, Slack) and cron runs ignore it — those users already have their own shells.
+
+**Markdown stripping in final responses.** The CLI strips the most verbose markdown fences and `**bold**` / `*italic*` wrappers from *final* agent replies so they render as readable terminal prose rather than raw source. Code blocks and lists are preserved. This does not affect gateway platforms or tool results — they keep their markdown for native rendering.
+
+## Slash Commands
+
+Type `/` to see the autocomplete dropdown. Hermes supports a large set of CLI slash commands, dynamic skill commands, and user-defined quick commands.
+
+Common examples:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show command help |
+| `/model` | Show or change the current model |
+| `/tools` | List currently available tools |
+| `/skills browse` | Browse the skills hub and official optional skills |
+| `/bg <prompt>` | Run a prompt in a separate background session |
+| `/btw <question>` | Ask a side question about the current conversation without interrupting it |
+| `/skin` | Show or switch the active CLI skin |
+| `/voice on` | Enable CLI voice mode (press `Ctrl+B` to record) |
+| `/voice tts` | Toggle spoken playback for Hermes replies |
+| `/reasoning high` | Increase reasoning effort |
+| `/title My Session` | Name the current session |
+| `/status` | Show session info — model/profile/tokens/duration — followed by a local **Session recap** block (recent turn counts, top tools used, files touched, latest user prompt + assistant reply). Pure local compute; no LLM call. |
+| `/context [all]` | Visual context-usage breakdown — glyph block grid + per-category token table (system prompt / tools / skills / memory / conversation / free space). `/context all` adds per-skill and per-toolset costs. |
+| `/sessions` | Open an interactive session picker right inside the classic CLI (same surface the TUI uses). Type to filter, arrow keys to navigate, Enter to resume. |
+
+For the full built-in CLI and messaging lists, see [Slash Commands Reference](../reference/slash-commands.md).
+
+For setup, providers, silence tuning, and messaging/Discord voice usage, see [Voice Mode](features/voice-mode.md).
+
+:::tip
+Commands are case-insensitive — `/HELP` works the same as `/help`. Installed skills also become slash commands automatically.
+:::
+
+## Quick Commands
+
+You can define custom commands that run shell commands instantly without invoking the LLM. These work in both the CLI and messaging platforms (Telegram, Discord, etc.).
+
+```yaml
+# ~/.hermes/config.yaml
+quick_commands:
+  status:
+    type: exec
+    command: systemctl status hermes-agent
+  gpu:
+    type: exec
+    command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
+  restart:
+    type: alias
+    target: /gateway restart
+```
+
+Then type `/status`, `/gpu`, or `/restart` in any chat. See the [Configuration guide](/user-guide/configuration#quick-commands) for more examples.
+
+## Preloading Skills at Launch
+
+If you already know which skills you want active for the session, pass them at launch time:
+
+```bash
+hermes -s hermes-agent-dev,github-auth
+hermes chat -s github-pr-workflow -s github-auth
+```
+
+Hermes loads each named skill into the session prompt before the first turn. The same flag works in interactive mode and single-query mode.
+
+### Persistent auto-load via config
+
+To have the same skills active at the start of **every** new session — CLI, TUI, gateway, cron and API sessions alike — set `skills.auto_load` in `config.yaml`:
+
+```yaml
+skills:
+  auto_load:
+    - hermes-agent-dev
+    - github-pr-workflow
+```
+
+Each entry is a skill name. The list is resolved once when a session's system prompt is first built and the rendered bytes are reused for the life of the conversation (model switches, compression), so prompt caching stays intact; config edits take effect in the next session. Missing or disabled skills log a warning and are skipped. `-s` names that overlap the list are loaded once.
+
+`--ignore-rules` (equivalently `HERMES_IGNORE_RULES=1`) skips auto-load together with AGENTS.md, SOUL.md, `.cursorrules` and memory injection; explicit `-s` skills still load. The setting is profile-scoped: each profile's `config.yaml` controls its own list.
+
+## Skill Slash Commands
+
+Every installed skill in `~/.hermes/skills/` is automatically registered as a slash command. The skill name becomes the command:
+
+```
+/gif-search funny cats
+/axolotl help me fine-tune Llama 3 on my dataset
+/github-pr-workflow create a PR for the auth refactor
+
+# Just the skill name loads it and lets the agent ask what you need:
+/excalidraw
+```
+
+## Personalities
+
+Set a predefined personality to change the agent's tone:
+
+```
+/personality pirate
+/personality kawaii
+/personality concise
+```
+
+Built-in personalities include: `helpful`, `concise`, `technical`, `creative`, `teacher`, `kawaii`, `catgirl`, `pirate`, `shakespeare`, `surfer`, `noir`, `uwu`, `philosopher`, `hype`.
+
+To go back to the default (no overlay), use `/personality none` — `default` and `neutral` work too.
+
+You can also define custom personalities in `~/.hermes/config.yaml`:
+
+```yaml
+personalities:
+  helpful: "You are a helpful, friendly AI assistant."
+  kawaii: "You are a kawaii assistant! Use cute expressions..."
+  pirate: "Arrr! Ye be talkin' to Captain Hermes..."
+  # Add your own!
+```
+
+## Multi-line Input
+
+There are two ways to enter multi-line messages:
+
+1. **`Alt+Enter`, `Ctrl+J`, or `Shift+Enter`** — inserts a new line
+2. **Backslash continuation** — end a line with `\` to continue:
+
+```
+❯ Write a function that:\
+  1. Takes a list of numbers\
+  2. Returns the sum
+```
+
+`Ctrl+J` and backslash continuation are enabled by default, matching Claude Code / Codex / OpenCode multiline shortcuts. On supported terminals such as iTerm2, Hermes also requests extended key reporting so `Shift+Enter` arrives as a distinct newline key. If your terminal sends LF for plain `Enter` and you need the legacy `Ctrl+J`-as-submit fallback, opt out:
+
+```yaml
+# ~/.hermes/config.yaml
+display:
+  cli_multiline_shortcuts: false
+```
+
+:::info
+Pasting multi-line text is supported — use any of the newline keys above, or simply paste content directly.
+
+In terminals using the Kitty keyboard protocol, `Alt+Enter` on the numeric keypad also inserts a newline, including next to a collapsed paste. Modified keypad navigation keys follow their non-keypad equivalents.
+:::
+
+### Shift+Enter compatibility
+
+Most terminals send the same byte sequence for `Enter` and `Shift+Enter` by default, so applications cannot distinguish them. Hermes recognises `Shift+Enter` only when the terminal sends a distinct sequence via the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) or xterm's `modifyOtherKeys` mode.
+
+| Terminal | Status |
+|---|---|
+| Kitty, foot, WezTerm, Ghostty | Distinct `Shift+Enter` enabled by default |
+| iTerm2 (recent), Alacritty, VS Code terminal, Warp | Supported once the Kitty protocol is enabled in settings |
+| Windows Terminal Preview 1.25+ | Supported once the Kitty protocol is enabled in settings |
+| macOS Terminal.app, stock Windows Terminal (stable) | Not supported — `Shift+Enter` is indistinguishable from `Enter` |
+
+Where the terminal cannot distinguish them, `Alt+Enter` and `Ctrl+J` continue to work by default. **On Windows Terminal specifically, `Alt+Enter` is captured by the terminal (toggles fullscreen) and never reaches Hermes — use `Ctrl+Enter` (delivered as `Ctrl+J`) or `Ctrl+J` directly for a newline.**
+
+## Redirecting the Agent Mid-Turn
+
+While the agent is working, you can send a correction without starting a new turn:
+
+- **Type a new message + Enter** — redirects the active turn using your correction
+- **`Ctrl+C`** — interrupt the current operation (press twice within 2s to force exit)
+- Completed tool work and reasoning already shown stay in context
+- A running tool reaches its safe boundary before the correction is applied
+
+### Busy Input Mode
+
+The `display.busy_input_mode` config key controls what happens when you press Enter while the agent is working:
+
+| Mode | Behavior |
+|------|----------|
+| `"interrupt"` (default) | Your message redirects the active turn. Model generation restarts with displayed reasoning and completed work preserved. A running foreground terminal command is moved to the background (not killed — you get a completion notification) so your message is read immediately; other running tools finish first |
+| `"queue"` | Your message is silently queued and sent as the next turn after the agent finishes |
+| `"steer"` | Your message is injected into the current run via `/steer`, arriving at the agent after the next tool call — no interrupt, no new turn |
+
+```yaml
+# ~/.hermes/config.yaml
+display:
+  busy_input_mode: "steer"   # or "queue" or "interrupt" (default)
+```
+
+`"queue"` mode prepares a separate follow-up turn. `"steer"` always waits for the next tool-result boundary. The default `"interrupt"` mode responds sooner during model generation while avoiding cancellation of a running tool; a long foreground `terminal` command (a build, a poller) is handed to the background so the agent sees your message right away instead of after the command exits. Use `/stop` when you want to cancel the turn and its foreground work. Unknown values fall back to `"interrupt"`.
+
+`"steer"` has two automatic fallbacks: if the agent hasn't started yet, or if images are attached, the message falls back to `"queue"` behavior so nothing is lost.
+
+You can also change it inside the CLI:
+
+```text
+/busy queue
+/busy steer
+/busy interrupt
+/busy status
+```
+
+:::tip First-touch hint
+The first time you press Enter while Hermes is working, Hermes prints a one-line reminder explaining the `/busy` knob. It only fires once per install; `onboarding.seen.busy_input_prompt` in `config.yaml` records that it was shown. Delete that key to see the tip again.
+:::
+
+### Suspending to Background
+
+On Unix systems, press **`Ctrl+Z`** to suspend Hermes to the background — just like any terminal process. The shell prints a confirmation:
+
+```
+Hermes Agent has been suspended. Run `fg` to bring Hermes Agent back.
+```
+
+Type `fg` in your shell to resume the session exactly where you left off. This is not supported on Windows.
+
+## Tool Progress Display
+
+The CLI shows animated feedback as the agent works:
+
+**Thinking animation** (during API calls):
+```
+  ◜ (｡•́︿•̀｡) pondering... (1.2s)
+  ◠ (⊙_⊙) contemplating... (2.4s)
+  ✧٩(ˊᗜˋ*)و✧ got it! (3.1s)
+```
+
+**Tool execution feed:**
+```
+  ┊ 💻 terminal `ls -la` (0.3s)
+  ┊ 🔍 web_search (1.2s)
+  ┊ 📄 web_extract (2.1s)
+```
+
+Cycle through display modes with `/verbose`: `off → new → all → verbose`. This command can also be enabled for messaging platforms — see [configuration](/user-guide/configuration#display-settings).
+
+### Tool Preview Length
+
+The `display.tool_preview_length` config key controls the maximum number of characters shown in tool call preview lines (e.g. file paths, terminal commands). The default is `0`, which means no limit — full paths and commands are shown.
+
+```yaml
+# ~/.hermes/config.yaml
+display:
+  tool_preview_length: 80   # Truncate tool previews to 80 chars (0 = no limit)
+```
+
+This is useful on narrow terminals or when tool arguments contain very long file paths.
+
+## Session Management
+
+### Resuming Sessions
+
+When you exit a CLI session, a resume command is printed:
+
+```
+Resume this session with:
+  hermes --resume 20260225_143052_a1b2c3
+
+Session:        20260225_143052_a1b2c3
+Duration:       12m 34s
+Messages:       28 (5 user, 18 tool calls)
+```
+
+Resume options:
+
+```bash
+hermes --continue                          # Resume the most recent CLI session
+hermes -c                                  # Short form
+hermes -c "my project"                     # Resume a named session (latest in lineage)
+hermes --resume 20260225_143052_a1b2c3     # Resume a specific session by ID
+hermes --resume "refactoring auth"         # Resume by title
+hermes --resume latest                     # Resume the most recent session (same as -c)
+hermes --resume latest --in ./my-project   # Latest session for ./my-project's workspace
+hermes -r 20260225_143052_a1b2c3           # Short form
+```
+
+Resuming restores the full conversation history from SQLite. The agent sees all previous messages, tool calls, and responses — just as if you never left.
+
+Use `/title My Session Name` inside a chat to name the current session, or `hermes sessions rename <id> <title>` from the command line. Use `hermes sessions list` to browse past sessions.
+
+### Session Storage
+
+CLI sessions are stored in Hermes's SQLite state database under `~/.hermes/state.db`. The database keeps:
+
+- session metadata (ID, title, timestamps, token counters)
+- message history
+- lineage across compressed/resumed sessions
+- full-text search indexes used by `session_search`
+
+Some messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store.
+
+### Context Compression
+
+Long conversations are automatically summarized when approaching context limits:
+
+```yaml
+# In ~/.hermes/config.yaml
+compression:
+  enabled: true
+  threshold: 0.50    # Compress at 50% of context limit by default
+
+# Summarization model configured under auxiliary:
+auxiliary:
+  compression:
+    model: ""  # Leave empty to use the main chat model (default). Or pin a cheap fast model, e.g. "google/gemini-3-flash-preview".
+```
+
+When compression triggers, middle turns are summarized while the first 3 and last 20 turns are always preserved.
+
+## Background Sessions
+
+Run a prompt in a separate background session while continuing to use the CLI for other work:
+
+```
+/bg Analyze the logs in /var/log and summarize any errors from today
+```
+
+Hermes immediately confirms the task and gives you back the prompt:
+
+```
+🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..."
+   Task ID: bg_143022_a1b2c3
+```
+
+### How It Works
+
+Each `/bg` prompt spawns a **completely separate agent session** in a daemon thread:
+
+- **Isolated conversation** — the background agent has no knowledge of your current session's history. It receives only the prompt you provide.
+- **Same configuration** — the background agent inherits your model, provider, toolsets, reasoning settings, and fallback model from the current session.
+- **Non-blocking** — your foreground session stays fully interactive. You can chat, run commands, or even start more background tasks.
+- **Multiple tasks** — you can run several background tasks simultaneously. Each gets a numbered ID.
+
+### Results
+
+When a background task finishes, the result appears as a panel in your terminal:
+
+```
+╭─ ☤ Hermes (background #1) ──────────────────────────────────╮
+│ Found 3 errors in syslog from today:                         │
+│ 1. OOM killer invoked at 03:22 — killed process nginx        │
+│ 2. Disk I/O error on /dev/sda1 at 07:15                      │
+│ 3. Failed SSH login attempts from 192.168.1.50 at 14:30      │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+If the task fails, you'll see an error notification instead. If `display.bell_on_complete` is enabled in your config, the terminal bell rings when the task finishes.
+
+### Use Cases
+
+- **Long-running research** — "/bg research the latest developments in quantum error correction" while you work on code
+- **File processing** — "/bg analyze all Python files in this repo and list any security issues" while you continue a conversation
+- **Parallel investigations** — start multiple background tasks to explore different angles simultaneously
+
+:::info
+Background sessions do not appear in your main conversation history. They are standalone sessions with their own task ID (e.g., `bg_143022_a1b2c3`).
+:::
+
+## Quiet Mode
+
+By default, the CLI runs in quiet mode which:
+- Suppresses verbose logging from tools
+- Enables kawaii-style animated feedback
+- Keeps output clean and user-friendly
+
+For debug output:
+```bash
+hermes chat --verbose
+```