Hermes Agent cheat sheet
The stuff you actually need. Updated 2026-04-02.
🚀 Get running in 5 minutes
- 1. Install: npm install -g hermes-agent
- 2. Run: hermes init in your project directory
- 3. Edit the generated hermes.config.json with your API key and model preferences
- 4. Run: hermes 'describe your task here'
- 5. Hermes executes autonomously — check hermes.log for what it did
// daily_workflows
The things you'll actually do every day.
One-shot task execution
basicscliRun a single focused task from the CLI.
hermes 'fix all TypeScript errors in src/' Interactive mode
workflowinteractiveRun Hermes in a REPL-style session for iterative work.
hermes --interactive Dry run — see the plan without executing
safetyplanningGenerate an execution plan without touching any files.
hermes --dry-run 'refactor auth module' Run from a task file
workflowfilesPut complex tasks in a markdown file and pass it as input.
hermes --task tasks/migrate-db.md Limit scope to specific paths
safetyscopingRestrict what files Hermes can read and edit.
hermes --scope src/lib/ 'refactor the utilities' Check what Hermes did
debuggingreviewReview the detailed execution log after a task.
cat hermes.log or hermes log --last ⚡ power_moves
Stuff most people don't know about.
Chain tasks with a pipeline file
Define a sequence of tasks that run in order, with outputs piped as inputs.
hermes --pipeline pipeline.yaml Automate multi-step workflows that normally require manual handoffs.
Use hermes.context.md for persistent instructions
Add a context file at project root with architecture notes and rules.
Create hermes.context.md at project root Hermes injects this into every task's context — better output without repeating yourself.
Capture structured output
Ask Hermes to output JSON you can pipe into another tool.
hermes --output-json 'list all API endpoints as JSON' Useful for generating data, configs, or feeding into scripts.
Parallel task execution
Run multiple independent tasks concurrently.
hermes --parallel tasks/a.md tasks/b.md tasks/c.md Speeds up batch work — each task gets its own context.
🔥 common_gotchas
Save yourself 30 minutes of debugging.
Hermes edits files outside the expected scope
Always use --scope to restrict file access. Or set allowedPaths in hermes.config.json.
API key not found
Set HERMES_API_KEY env var or add it to hermes.config.json. Check with hermes config show.
Task never terminates
Add --max-steps 20 to cap iterations. Check hermes.log to see where it looped.
hermes.context.md not being loaded
Must be at project root (where you ran hermes init). Check hermes config show for contextPath.
📋 cli_flags
----dry-run, --n Show the execution plan without modifying any files.
Validate the plan before committing to changes.
hermes --dry-run 'delete unused imports'
----interactive, --i Start an interactive session with back-and-forth conversation.
Exploratory work and iterative refinement.
hermes --interactive
----scope Restrict file access to a specific path. Hermes cannot read or edit outside this path.
Focused tasks where you want to prevent accidental edits to other parts.
hermes --scope src/api/ 'add input validation to all endpoints'
----task, --t Read the task description from a file (markdown or plain text).
Complex tasks that are easier to write in a file than inline.
hermes --task tasks/refactor.md
----max-steps Maximum number of agent iterations before stopping.
Budget cap for open-ended tasks.
hermes --max-steps 10 'implement login flow'
----model, --m Override the model for this task.
Use a stronger model for complex tasks, cheaper one for quick fixes.
hermes --model claude-opus-4-6 'redesign the architecture'
----output-json Ask Hermes to return structured JSON output.
Piping Hermes output into scripts or other tools.
hermes --output-json 'list all exported functions'
----parallel Run multiple task files concurrently.
Batch parallel execution of independent tasks.
hermes --parallel tasks/a.md tasks/b.md 💡 pro_tips
- › Always run --dry-run first on unfamiliar tasks to validate the plan.
- › Create hermes.context.md immediately on any new project.
- › Use --scope on every task that targets a specific module.
- › For long tasks, break them into a --pipeline of smaller steps.
- › Check hermes.log after every run — it shows exactly what the agent decided and why.
- › Set maxSteps low by default and increase only when needed.
⚙️ configuration
apiKey API key for the configured model provider.
default: reads from HERMES_API_KEY env var
recommended: Use env var in production. Store in hermes.config.json for local dev only.
model Default model to use for all tasks.
default: claude-sonnet-4-6
recommended: Sonnet for most tasks. Opus for long autonomous runs.
contextPath Path to the context file injected into every task.
default: hermes.context.md
recommended: Create this file with project conventions and architecture notes.
allowedPaths Array of paths Hermes is permitted to read and edit. Empty = no restriction.
default: []
recommended: Set to your source directories in production deployments.
maxSteps Default maximum agent iterations per task.
default: 50
recommended: Lower to 20-30 for most tasks to prevent runaway loops.