From 76badfed6360646e8aea474a4d2376135ea74e65 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Wed, 25 Feb 2026 23:04:08 -0800 Subject: [PATCH] Enhance CLI documentation and functionality for session resumption - Updated README and CLI documentation to include new commands for resuming sessions: `--continue` for the most recent session and `--resume ` for specific sessions. - Added examples in the CLI help output and detailed instructions on resuming sessions in the documentation. - Improved user experience by automatically displaying the resume command upon exiting a session. --- README.md | 16 +++++++ docs/cli.md | 44 ++++++++++++++++--- hermes_cli/main.py | 3 ++ .../hermes-agent/SKILL.md | 28 +++++++++--- 4 files changed, 78 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 585af51c5..ea67de7da 100644 --- a/README.md +++ b/README.md @@ -339,6 +339,8 @@ HERMES_TOOL_PROGRESS_MODE=all # or "new" for only when tool changes # Chat hermes # Interactive chat (default) hermes chat -q "Hello" # Single query mode +hermes --continue # Resume the most recent session (-c) +hermes --resume # Resume a specific session (-r) # Provider & model management hermes model # Switch provider and model interactively @@ -577,8 +579,22 @@ All CLI and messaging sessions are stored in a SQLite database (`~/.hermes/state - **FTS5 search** via the `session_search` tool -- search past conversations with Gemini Flash summarization - **Compression-triggered session splitting** -- when context is compressed, a new session is created linked to the parent, giving clean trajectories - **Source tagging** -- each session is tagged with its origin (cli, telegram, discord, etc.) +- **Session resume** -- pick up where you left off with `hermes --continue` (most recent) or `hermes --resume ` (specific session) - Batch runner and RL trajectories are NOT stored here (separate systems) +When you exit a CLI session, the resume command is printed automatically: + +``` +Resume this session with: + hermes --resume 20260225_143052_a1b2c3 + +Session: 20260225_143052_a1b2c3 +Duration: 12m 34s +Messages: 28 (5 user, 18 tool calls) +``` + +Use `hermes sessions list` to browse past sessions and find IDs to resume. + ### 📝 Session Logging Every conversation is logged to `~/.hermes/sessions/` for debugging: diff --git a/docs/cli.md b/docs/cli.md index 65a675518..76a50e573 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,20 +6,24 @@ The Hermes Agent CLI provides an interactive terminal interface for working with ```bash # Basic usage -./hermes +hermes # With specific model -./hermes --model "anthropic/claude-sonnet-4" +hermes --model "anthropic/claude-sonnet-4" # With specific provider -./hermes --provider nous # Use Nous Portal (requires: hermes login) -./hermes --provider openrouter # Force OpenRouter +hermes --provider nous # Use Nous Portal (requires: hermes login) +hermes --provider openrouter # Force OpenRouter # With specific toolsets -./hermes --toolsets "web,terminal,skills" +hermes --toolsets "web,terminal,skills" + +# Resume previous sessions +hermes --continue # Resume the most recent CLI session (-c) +hermes --resume # Resume a specific session by ID (-r) # Verbose mode -./hermes --verbose +hermes --verbose ``` ## Architecture @@ -238,6 +242,34 @@ This allows you to have different terminal configs for CLI vs batch processing. - **Conversations**: Use `/save` to export conversations - **Reset**: Use `/clear` for full reset, `/reset` to just clear history - **Session Logs**: Every session automatically logs to `logs/session_{session_id}.json` +- **Resume**: Pick up any previous session with `--resume` or `--continue` + +### 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) +``` + +To resume: + +```bash +hermes --continue # Resume the most recent CLI session +hermes -c # Short form +hermes --resume 20260225_143052_a1b2c3 # Resume a specific session by ID +hermes -r 20260225_143052_a1b2c3 # Short form +hermes chat --resume 20260225_143052_a1b2c3 # Explicit subcommand form +``` + +Resuming restores the full conversation history from SQLite (`~/.hermes/state.db`). The agent sees all previous messages, tool calls, and responses — just as if you never left. New messages append to the same session in the database. + +Use `hermes sessions list` to browse past sessions and find IDs. ### Session Logging diff --git a/hermes_cli/main.py b/hermes_cli/main.py index f91f542ce..2c3ef96a8 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -767,6 +767,8 @@ def main(): Examples: hermes Start interactive chat hermes chat -q "Hello" Single query mode + hermes --continue Resume the most recent session + hermes --resume Resume a specific session hermes setup Run setup wizard hermes login Authenticate with an inference provider hermes logout Clear stored authentication @@ -776,6 +778,7 @@ Examples: hermes config set model gpt-4 Set a config value hermes gateway Run messaging gateway hermes gateway install Install as system service + hermes sessions list List past sessions hermes update Update to latest version For more help on a command: diff --git a/skills/autonomous-ai-agents/hermes-agent/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/SKILL.md index f2e6f2a5f..467109568 100644 --- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md +++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md @@ -42,6 +42,20 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri This installs uv, Python 3.11, clones the repo, sets up the venv, and launches an interactive setup wizard to configure your API provider and model. See the [GitHub repo](https://github.com/NousResearch/hermes-agent) for details. +## Resuming Previous Sessions + +Resume a prior CLI session instead of starting fresh. Useful for continuing long tasks across process restarts: + +``` +# Resume the most recent CLI session +terminal(command="hermes --continue", background=true, pty=true) + +# Resume a specific session by ID (shown on exit) +terminal(command="hermes --resume 20260225_143052_a1b2c3", background=true, pty=true) +``` + +The full conversation history (messages, tool calls, responses) is restored from SQLite. The agent sees everything from the previous session. + ## Mode 1: One-Shot Query (-q flag) Run a single query non-interactively. The agent executes, does its work, and exits: @@ -145,13 +159,13 @@ For scheduled autonomous tasks, use the `schedule_cronjob` tool instead of spawn ## Key Differences Between Modes -| | `-q` (one-shot) | Interactive (PTY) | -|---|---|---| -| User interaction | None | Full back-and-forth | -| PTY required | No | Yes (`pty=true`) | -| Multi-turn | Single query | Unlimited turns | -| Best for | Fire-and-forget tasks | Iterative work, reviews, steering | -| Exit | Automatic after completion | Send `/exit` or kill | +| | `-q` (one-shot) | Interactive (PTY) | `--continue` / `--resume` | +|---|---|---|---| +| User interaction | None | Full back-and-forth | Full back-and-forth | +| PTY required | No | Yes (`pty=true`) | Yes (`pty=true`) | +| Multi-turn | Single query | Unlimited turns | Continues previous turns | +| Best for | Fire-and-forget tasks | Iterative work, steering | Picking up where you left off | +| Exit | Automatic after completion | Send `/exit` or kill | Send `/exit` or kill | ## Known Issues