**Duration:** ~50 minutes reading
**Prerequisites:** Module 3 (Configuration)
**Goal:** Master Hermes Agent as a daily driver — from interactive chat to cron jobs, delegation, and multi-agent orchestration.
4.1 Interactive Chat vs. Single Query Mode
Hermes Agent has two main interaction modes.
Interactive Chat (Default)
hermes
This launches the full terminal UI with:
- A Rich-formatted banner showing the active model, provider, and profile
- A persistent text input area at the bottom (prompt_toolkit)
- Split-pane output with streaming responses
- A status bar showing model, tokens, and session ID
- Full tab-completion for slash commands
Inside interactive mode, you type normally and Hit `Enter` to send. The agent can chain multiple tool calls — searching the web, reading files, writing code, running terminals — all in a single turn.
Single Query Mode
hermes chat -q "List all files in /root"
# Or equivalently:
hermes -q "List all files in /root"
This sends one query, waits for the response, prints it, then exits. Use this for:
- **Shell scripts:** `result=$(hermes chat -q "What's the weather?")`
- **Cron jobs:** `hermes -p daily cron run daily-report`
- **Batch processing:** Pipe queries from a file list or CI pipeline
The single-query mode sets `HERMES_YOLO_MODE=1` internally so dangerous commands auto-approve — ideal for automation.
# Named session (persists for follow-ups)
hermes chat -q "Write a Python script" --continue my-session
Key Flags
| Flag | Effect |
|---|---|
| `-q "..."` | Single query mode |
| `-p |
Use a specific profile |
| `-w` | Worktree mode (isolated git worktree) |
| `--continue |
Resume a named session |
| `--resume` | Resume the last session |
| `--ignore-user-config` | Skip `config.yaml`, use defaults |
| `--list-tools` | Print all tool schemas and exit |
| `--voice` | Start with voice input enabled |
4.2 Slash Commands Master List
Inside an interactive session, everything starts with `/`. Here's every command organized by category.
Session Management
| Command | Aliases | What It Does |
|---|---|---|
| `/new [name]` | `/reset` | Start a completely fresh session |
| `/retry` | — | Resend your last message to the agent |
| `/undo` | — | Remove the last exchange (you + agent) |
| `/title [name]` | — | Name the current session for resumption |
| `/compress [topic]` | — | Manually trigger context compression |
| `/save` | — | Dump the current conversation to a file |
| `/history` | — | Show the full conversation so far |
| `/resume [name]` | — | Jump back into a named session |
| `/sessions` | — | Browse all past sessions |
| `/branch [name]` | `/fork` | Fork the current conversation |
| `/snap create` | — | Snapshot config/state (exportable) |
| `/rollback [N]` | — | Restore filesystem to checkpoint N |
| `/stop` | — | Kill all agent background processes |
| `/agents` | `/tasks` | List active subagents and tasks |
| `/background |
`/bg`, `/btw` | Run a prompt in a background thread |
| `/queue |
`/q` | Queue input for next turn |
| `/steer |
— | Inject a message after the next tool call |
| `/goal [text/pause/resume/clear/status]` | — | Persistent cross-turn objective |
| `/subgoal [text/remove N/clear]` | — | Extra criteria on the active goal |
| `/status` | — | Session info (model, tokens, uptime) |
| `/profile` | — | Show active profile name and path |
Configuration
| Command | Aliases | What It Does |
|---|---|---|
| `/model [name]` | `/provider` | Switch provider or model mid-session |
| `/personality [name]` | — | Set a predefined personality |
| `/verbose` | — | Cycle tool progress verbosity |
| `/yolo` | — | Toggle YOLO mode on/off |
| `/reasoning [level]` | — | Set reasoning effort |
| `/voice [on/off/tts]` | — | Toggle voice mode |
| `/fast [normal/fast]` | — | Toggle priority processing (OpenAI/Anthropic) |
| `/skin [name]` | — | Change the CLI theme |
| `/indicator [style]` | — | Change the busy indicator animation |
Tools & Skills
| Command | Aliases | What It Does |
|---|---|---|
| `/tools [list/enable/disable]` | — | Manage tools (CLI only) |
| `/toolsets` | — | List available toolsets |
| `/skills [search/inspect/install]` | — | Browse and manage skills |
| `/bundles` | — | List skill bundles |
| `/cron [subcommand]` | — | Manage scheduled tasks |
| `/curator [run/pause/pin]` | — | Background skill maintenance |
| `/kanban [subcommand]` | — | Multi-agent coordination board |
Information & Help
| Command | What It Does |
|---|---|
| `/help` | Show all commands |
| `/usage` | Show token usage and cost |
| `/insights [--days N]` | Analyze recent usage patterns |
| `/limits` | Check per-provider rate limits |
| `/whoami` | Show your access level (admin/user) |
4.3 Switching Models Mid-Session with `/model`
One of Hermes's most powerful features: you can change models **without losing your conversation context**.
# Inside a session, switch models mid-conversation:
/model "gemini/gemini-3-flash-preview"
# Switch provider entirely:
/model --provider anthropic
/model --provider openai
# Set the new model as default (persists to config.yaml):
/model "openrouter/anthropic/claude-sonnet-4" --global
**Use cases:**
- Start brainstorming with a cheap/fast model, then `/model` to a reasoning model for deep analysis
- Hit a rate limit? `/model` to a different provider
- Need vision? Switch to Gemini for image analysis, then back
The full conversation history is preserved across model switches — only the inference backend changes. All active toolsets remain unchanged.
4.4 Context Compression
Long conversations consume tokens and degrade quality. Hermes has two compression strategies.
Automatic Compression (Default)
# In config.yaml:
compression:
enabled: true
threshold: 0.50 # Compress at 50% of the model's context limit
When the conversation approaches the model's context window, Hermes automatically summarizes earlier turns into a compact form. This happens transparently — you just keep chatting.
Manual Compression
# Trigger compression immediately
/compress
# Compress around a specific topic
/compress "focus on the database schema decisions"
The `/compress` command:
1. Takes the conversation so far
2. Asks an auxiliary LLM to summarize it
3. Replaces the full history with the summary
4. Keeps the most recent N turns intact (so you don't lose the current thread)
The `/usage` command shows your current context usage:
/usage
# Output:
# Tokens: 12,847 / 200,000 (6.4%)
# Cost this session: $0.04
4.5 Subagent Delegation
The `delegate_task` tool spawns **isolated child agents** with their own context, tools, and terminal sessions. The parent blocks until all children complete and only sees their summary results — never intermediate tool calls.
How Delegation Works
You ──> Hermes (parent) ──> delegate_task("Write unit tests for parser.py")
│
┌───────┴───────┐
▼ ▼
Child Agent 1 Child Agent 2
(writes tests) (verifies they pass)
│ │
└───────┬───────┘
▼
Summary back to parent
Configuring Delegation
# In config.yaml:
delegation:
max_iterations: 45 # Max turns per child
model: "" # Child model (empty = inherit parent)
provider: "" # Child provider (empty = inherit parent)
auto_approve: true # Auto-approve dangerous commands in children
Using Delegate in Conversation
You: Implement a REST API for the todo app. Delegate the database layer
to one subagent and the route handlers to another.
Hermes: I'll split this into parallel workstreams.
🔄 Delegating: Database schema & models...
🔄 Delegating: Route handlers & middleware...
✅ Database layer complete (child: 8 turns)
- Created models.py with SQLAlchemy schema
- Added migration script
✅ Route handlers complete (child: 12 turns)
- Created routes.py with CRUD endpoints
- Added input validation
Both branches finished. Here's the full implementation...
Batch Delegation
The delegate tool also supports batch mode for processing multiple independent tasks in parallel — perfect for code review, file analysis, or bulk operations.
# Behind the scenes, delegation uses ThreadPoolExecutor
# with configurable max_workers (default: half your CPU cores)
4.6 Session Management
Every conversation is a **session** — persisted to SQLite with full-text search.
Naming and Resuming Sessions
# Start a named session
hermes chat --continue "code-review-session"
# Inside the session, give it a title
/title "Implementing the payment module"
# Later, resume it
hermes --continue "Implementing the payment module"
# Or via the session browser
hermes sessions list
hermes --continue <session-id>
Session Persistence
Sessions are stored in `~/.hermes/state.db` (SQLite with FTS5). Each session records:
- Full message history
- Model and provider used
- Token usage and cost
- Timestamps
- Title (if set)
Session Search
The `/sessions` command opens an interactive browser:
/sessions
# Lists all sessions with: title, model, date, token count
# Type a number to resume, or filter by date/model
The `session_search` tool inside conversations lets the agent search past sessions to recall decisions, code patterns, or facts from weeks ago.
Branching
/branch "try-with-postgres"
# Creates a fork of the current conversation
# You now have two diverging threads from the same starting point
4.7 Cron Jobs
Hermes has a built-in cron scheduler that runs inside the gateway. Jobs execute as agent conversations with full tool access.
Creating Cron Jobs
# Inside a session, ask the agent:
"Create a daily summary cron job that runs at 8 AM"
# Or use the cron tool directly:
/cron create
# Interactive prompt:
# Name: daily-report
# Schedule: 0 8 * * * (cron expression)
# Prompt: "Summarize yesterday's activity in /root/logs"
# Platform: cli (or telegram, discord, etc.)
Cron Commands
# List all jobs
/cron list
# Pause/resume
/cron pause daily-report
/cron resume daily-report
# Run immediately (one-shot)
/cron run daily-report
# Edit a job's prompt or schedule
/cron edit daily-report
# Remove a job
/cron remove daily-report
Cron Schedule Format
Standard cron expressions with 5 fields:
┌───────── minute (0-59)
│ ┌──────── hour (0-23)
│ │ ┌─────── day of month (1-31)
│ │ │ ┌────── month (1-12)
│ │ │ │ ┌───── day of week (0-7, 0/7 = Sunday)
│ │ │ │ │
0 8 * * 1-5 # Weekdays at 8 AM
Cron Safety Features
- **Prompt injection scanning** — every assembled job prompt is scanned for injection before execution
- **Auto-approval** — cron agents run with auto-approved dangerous commands (set `delegation.auto_approve: false` to disable)
- **Tool filtering** — cron uses the `hermes-cron` toolset, which you configure independently of the CLI toolset
- **Output delivery** — cron results are sent to the configured platform (Telegram, email, Slack, etc.)
Cron with Platforms
hermes cron create \
--name "weekly-audit" \
--schedule "0 9 * * 1" \
--prompt "Audit /var/log for errors in the last week and summarize findings" \
--platform telegram # Deliver results to Telegram
4.8 Webhooks
The webhook platform lets external systems trigger Hermes agents via HTTP POST requests.
Setting Up Webhook Endpoints
# Start the gateway with webhook support
hermes gateway start
# The webhook listener runs on the gateway port
# Default: http://localhost:8290/webhook
Webhook Payload Format
POST /webhook HTTP/1.1
Content-Type: application/json
{
"message": "A new deployment is ready for review",
"platform": "webhook",
"metadata": {
"source": "github-actions",
"repo": "myorg/myapp",
"commit": "abc123"
}
}
Use Cases
- **CI/CD pipelines** — trigger agent to review deployment output
- **Monitoring alerts** — agent diagnoses and responds to system alerts
- **GitHub webhooks** — agent reviews PRs, comments on issues
- **IoT events** — agent processes sensor data and takes action
# Example: GitHub Actions workflow
curl -X POST https://hermes.myserver.com/webhook \
-H "Content-Type: application/json" \
-d '{"message": "Deploy to prod completed. Verify health endpoints.", "platform": "webhook"}'
4.9 Goal Mode
Goals persist across conversation turns, giving the agent a standing directive it keeps working toward.
Setting a Goal
/goal "Refactor the database layer to use async SQLAlchemy"
# Add sub-goals
/subgoal "Add connection pooling"
/subgoal "Rewrite all CRUD operations as async"
/subgoal "Update tests"
How Goals Work
When a goal is active:
1. The goal text is appended to the system prompt on every turn
2. The agent autonomously works toward the goal across multiple user messages
3. Completing a sub-goal triggers the agent to move to the next one
4. Interleaving unrelated questions doesn't reset progress
Managing Goals
/goal status # See current goal + sub-goal progress
/goal pause # Temporarily suspend goal pursuit
/goal resume # Re-activate the goal
/goal clear # Remove the current goal completely
Goals are not persisted across sessions — they're session-scoped.
4.10 Worktree Mode
The `-w` flag creates an **isolated git worktree** for the current session, letting you run multiple Hermes instances in the same repository without conflicts.
# Start a session in worktree mode
hermes -w
# Creates: ~/my-repo/.worktrees/hermes-<uuid>/
# The session's CWD is inside this worktree
Why Worktrees Matter
Without worktrees, two Hermes sessions modifying the same files race against each other. Worktrees give each session:
- Its own working directory (a detached HEAD copy of the repo)
- No interference between parallel sessions
- Clean isolation — changes in one worktree don't affect others
- The original repository remains untouched until you merge
Worktree Lifecycle
# Create a worktree session
hermes -w
# Inside the session, you can:
# - Edit files
# - Run tests
# - Create branches
# All isolated from other sessions
# On exit, the worktree is cleaned up automatically
# Uncommitted changes are lost (by design — commit before exiting!)
Multi-Agent Worktree Workflows
# Terminal 1
hermes -w -q "Refactor the auth module"
# Terminal 2 (same repo, different worktree)
hermes -w -q "Write tests for the auth module"
# Terminal 3 (gateway, providing chat access)
hermes gateway start
# Both Telegram and CLI sessions get their own worktrees
4.11 Checkpoints & Rollback
Checkpoints let you rewind the **filesystem state** to a previous point — like undo for your whole project.
Creating Checkpoints
Checkpoints are created automatically by the `terminal` and `file` tools. Every file write, patch, or terminal command that modifies files records a snapshot.
# List all checkpoints for this session
/rollback
# Shows:
# [0] Just now - Initial state
# [1] 2 min ago - After creating routes.py
# [2] 30 sec ago - After modifying database.py
Restoring a Checkpoint
# Restore to checkpoint 1
/rollback 1
# Files are reverted. Cannot be undone (but you can restore forward too).
Snapshot System (Portable)
# Create a named snapshot (exportable)
/snap create "pre-refactor"
# Saved to ~/.hermes/checkpoints/<name>/
# Restore from a snapshot
/snap restore "pre-refactor"
# List all snapshots
/snap ls
# Prune old snapshots
/snap prune
Snapshots capture:
- Files in the working directory (configurable scope)
- Active conversation context
- Agent memory state
This is useful for:
- **Experiment before big refactors** — explore freely, revert instantly
- **Teaching/demos** — create snapshots at different stages
- **Reproducible debugging** — save the exact state before a bug occurs
4.12 Multi-Agent Coordination with tmux and Kanban
For complex workflows, Hermes supports running multiple agents in parallel with structured coordination.
tmux Integration
Hermes can be used inside tmux sessions for persistent, detachable agent instances:
# Create a tmux session for each agent
tmux new-session -s dev-agent 'hermes -p developer'
tmux new-window -t dev-agent -n test-agent 'hermes -p tester'
tmux new-window -t dev-agent -n deploy-agent 'hermes -p deploy'
# Detach and reattach later
tmux detach
tmux attach -t dev-agent
Kanban Board
The kanban system provides structured multi-agent coordination with a shared task board:
# Initialize the kanban board (first time)
/kanban init
# Create a task on the board
/kanban create "Refactor payment processor" --assignee coder
# List all tasks
/kanban list
# Shows: ID, Title, Assignee, Status, Priority
# Link tasks to show dependencies
/kanban link 5 --depends-on 3
# Complete a task
/kanban complete 5 --result "...summary..."
Kanban Worker Profiles
When an agent is spawned as a kanban worker (via the kanban dispatcher in the gateway), it automatically receives tools to:
- Show assigned tasks (`kanban_show`)
- Mark tasks complete with structured handoffs (`kanban_complete`)
- Block for human input (`kanban_block`)
- Heartbeat during long operations (`kanban_heartbeat`)
- Comment on task threads (`kanban_comment`)
Multi-Profile Orchestration
# ~/.hermes/config.yaml in the kanban orchestrator profile:
kanban:
dispatch_in_gateway: true
workers:
- name: coder
description: "Full-stack development and code writing"
- name: reviewer
description: "Code review, security audit, best practices"
- name: sysadmin
description: "Server management, deployment, monitoring"
The kanban decomposer automatically breaks incoming tasks into subtasks and routes them to the most appropriate worker profile based on their descriptions.
4.13 Power User Tips
1. Chain Multiple Commands
# Use single-query mode in pipelines
curl -s https://api.github.com/repos/user/repo/issues \
| hermes chat -q "Summarize these GitHub issues and prioritize them"
2. Background Processing
# Inside a session, do work without blocking
/background "Download the dataset and preprocess it"
# Keep chatting while the background task runs
# The agent interrupts when done
3. Session Context Files
# Create ~/.hermes/context-files/ for persistent project context
# The agent loads these into system prompt automatically
4. Custom Persona Files (SOUL.md)
# ~/.hermes/SOUL.md defines your agent's core personality
# It's loaded into every session across all profiles
5. Keyboard Shortcuts in CLI
| Shortcut | Action |
|---|---|
| `Ctrl+C` | Interrupt current agent task |
| `Ctrl+L` | Clear screen |
| `Ctrl+R` | Reverse search command history |
| `Tab` | Autocomplete slash commands |
| `Shift+Enter` | New line (multi-line input) |
| `Ctrl+Enter` | Send multi-line input |
| `Up/Down` | Navigate command history |
6. Daily Workflow Example
# Morning: start the gateway for mobile access
hermes gateway start
# Check in from CLI
hermes chat -q "Summarize what I was working on yesterday"
# Start a focused session
hermes --continue "payment-refactor"
# During session:
/model "openrouter/deepseek/deepseek-chat-v3-0324" # Switch to cheaper model
/verbose 2 # Show intermediate tool calls
/goal "Refactor the payment module to use Stripe"
# After session: schedule daily report
hermes cron create \
--name "daily-ticket-summary" \
--schedule "0 17 * * 5" \
--prompt "Summarize this week's GitHub activity" \
--platform telegram
4.14 Quick Reference: Common Task Cheatsheet
| Task | Command |
|---|---|
| Start chatting | `hermes` |
| Ask one question | `hermes chat -q "question"` |
| Use a specific profile | `hermes -p work` |
| Resume last session | `hermes --resume` |
| Switch model in-session | `/model "provider/model"` |
| Check usage | `/usage` |
| Compress context | `/compress` |
| Set a goal | `/goal "objective"` |
| Schedule a task | `hermes cron create` (or `/cron create` in-session) |
| Enable browser | `hermes tools enable browser` |
| Toggle YOLO | `/yolo` |
| Rollback file changes | `/rollback |
| Fork conversation | `/branch "exploration-name"` |
| See all sessions | `hermes sessions list` |
| Send webhook | `curl -X POST |
| Create a profile | `hermes profile create |
| Manage credentials | `hermes auth` |
Key Takeaways
- **Two modes**: Interactive (`hermes`) for deep work, single-query (`hermes -q`) for automation
- **Slash commands** are your interface to session management, model switching, and tools
- **Context compression** keeps long conversations efficient — both automatic and manual (`/compress`)
- **Subagent delegation** parallelizes work without contaminating parent context
- **Session management** gives you named, searchable, resumable conversations
- **Cron jobs** let the agent work unattended on schedules
- **Webhooks** bridge external systems into agent conversations
- **Goal mode** gives the agent persistent cross-turn objectives
- **Worktrees** isolate parallel agent instances in the same git repo
- **Checkpoints** provide filesystem undo for safe experimentation
- **Kanban + tmux** enable full multi-agent orchestration for complex workflows
- **The `/model` command** is arguably Hermes's killer feature — switch inference backends mid-conversation without losing context
**Next Steps:** Explore the Skills System (Module 5) to create procedural knowledge that makes your agent smarter with every interaction.