Hermes Starter Guide

IMPORTANT SECURITY RULES

⌄

1. Secrets go in ~/.hermes/.env or Hermes auth storage, not in notes, prompts, docs, screenshots, or Obsidian.
2. Config goes in ~/.hermes/config.yaml.
3. Reusable procedures go in Hermes skills.
4. Durable human-readable documentation goes in Obsidian or Markdown notes.
5. Temporary task state belongs in sessions, cron output, or a Kanban/todo system, not long-term memory.
6. If you create multiple agents/profiles, each profile should have its own isolated ~/.hermes/profiles/<name>/ directory, its own .env, and its own gateway/service.

1. INSTALL AND FIRST-RUN BASELINE

⌄

Install Hermes:

CODE

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Run setup:

CODE

hermes setup
hermes doctor

Common commands:

CODE

hermes                       # interactive CLI
hermes chat -q "hello"       # one-shot query
hermes model                 # choose provider/model
hermes config edit           # edit config.yaml
hermes config path           # print config path
hermes config env-path       # print .env path
hermes tools                 # enable/disable tools
hermes gateway status        # check messaging gateway

Recommended starting toolsets for a technical owner:

CODE

web
browser
terminal
file
code_execution
vision
skills
memory
session_search
delegation
cronjob
messaging

Terrell’s default profile is configured around:

CODE

model.provider: openai-codex
model.default: gpt-5.5
agent.reasoning_effort: minimal
memory.memory_enabled: true
memory.user_profile_enabled: true
compression.enabled: true
security.redact_secrets: true
gateway.bind_address: 0.0.0.0
platforms.api_server.enabled: true

You do not need to copy those exact model choices. Copy the structure and reliability patterns.

2. WHERE THINGS LIVE

⌄

Default Hermes home:

CODE

~/.hermes/

Key files and folders:

CODE

~/.hermes/config.yaml          Main non-secret config
~/.hermes/.env                 API keys and secret environment variables
~/.hermes/auth.json            OAuth credentials / credential pools
~/.hermes/skills/              Installed/custom skills
~/.hermes/logs/                Gateway, dashboard, scheduler logs
~/.hermes/state.db             Session database
~/.hermes/sessions/            Session/routing artifacts
~/.hermes/cron/                Cron job state/config, depending on install version
~/.hermes/profiles/<name>/     Isolated profile homes for additional agents

Rule of thumb:

CODE

config.yaml = behavior
.env = secrets
skills/ = reusable procedures
state.db/sessions = conversation history
logs/ = debugging
Obsidian = durable human-readable operating notes, never secrets

3. API KEYS AND SECRETS

⌄

Put provider/API keys in:

CODE

~/.hermes/.env

Example .env shape:

CODE

OPENROUTER_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_API_KEY=...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...
XAI_API_KEY=...
HF_TOKEN=...
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
API_SERVER_KEY=...
OBSIDIAN_API_KEY=...
GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...

Use OAuth-backed providers through Hermes auth when available:

CODE

hermes auth
hermes auth add openai-codex
hermes auth add nous
hermes auth list

Recommended security setting:

CODE

hermes config set security.redact_secrets true

Restart the CLI/gateway after changing security or tool config.

Never paste real API keys into prompts asking the agent to “remember” them. Instead say:

CODE

“I placed OPENROUTER_API_KEY in ~/.hermes/.env. Verify that Hermes can see it without printing the value.”

4. MEMORY SYSTEM

⌄

Hermes has a persistent memory system that can remember compact, stable facts across sessions.

Recommended config:

CODE

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  flush_min_turns: 6
  nudge_interval: 10

Use memory for:

CODE

- User preferences
- Stable environment facts
- Permanent naming conventions
- Long-lived project structure
- “Don’t do this again” corrections

Do not use memory for:

CODE

- Temporary task progress
- PR numbers
- Issue numbers
- Completed task logs
- One-off command outputs
- Anything likely stale in a week

Prompt to give your agent:

PROMPT

Please use Hermes persistent memory carefully. Save compact durable facts that will help future sessions, especially my preferences, stable environment details, and repeated corrections. Do not save temporary task progress, stale IDs, one-off logs, or secrets. Write memories as declarative facts, not commands.

Good memory examples:

CODE

User prefers concise actionable technical summaries.
Project X uses Docker Compose with services api, worker, postgres, and redis.
The production server runs Ubuntu 24.04 and uses systemd services.

Bad memory examples:

CODE

Fixed bug today.
PR #123 was opened.
Run pytest tomorrow.
API key is sk-...

5. SKILLS SYSTEM

⌄

Skills are reusable procedural memory. They are better than normal memory for workflows.

Use skills for:

CODE

- Multi-step setup procedures
- Debugging recipes
- Project-specific deployment workflows
- Reusable scripts and templates
- Anything learned after a tricky 5+ step task

Commands:

CODE

hermes skills list
hermes skills browse
hermes skills search "docker"
hermes skills install <skill-id>
hermes skills check
hermes skills update

Prompt to give your agent:

CODE

When you solve a complex or reusable problem for me, offer to save the workflow as a Hermes skill. If you load a skill and discover it is outdated or missing a pitfall, patch the skill immediately instead of leaving it stale.

Recommended custom skill categories:

CODE

devops/
github/
email/
note-taking/
project-specific/<project-name>/
debugging/

6. INTER-AGENT COMMUNICATIONS

⌄

If you create multiple Hermes profiles/agents, do not have them talk through Telegram, shared text files, or polling cron jobs.

Use the built-in inter_agent_message tool.

Pattern:

CODE

inter_agent_message(
  action="send",
  to_profile="default",
  subject="Technical escalation: short title",
  message="Profile: <name>\nProblem: <what failed>\nLogs/errors: <redacted excerpts>\nWhat I tried: <steps>\nImpact: <user impact>"
)

Terrell’s setup pattern:

PROMPT

- The default profile is the technical lead / systems engineer.
- Other profiles escalate technical failures to default/Hermon.
- Agent-to-agent conversations create normal Hermes sessions, so they can be searched later.
- Profiles should include inter_agent in toolsets where they need escalation.

Enable inter-agent toolset where appropriate:

CODE

hermes tools enable inter_agent

Or in config.yaml, depending on Hermes version/profile surface:

CODE

toolsets:
  - hermes-cli
  - web
  - inter_agent

CODE

platform_toolsets:
  cli:
    - hermes-cli
    - inter_agent

Prompt to give each non-primary agent:

CODE

If you hit a technical problem you cannot safely resolve — gateway failure, model/provider issue, cron failure, missing credential, broken script, API problem, database issue, or uncertainty about infrastructure — escalate to the default Hermes profile using inter_agent_message. Include exact error text, log paths/snippets, what you tried, and whether the user is impacted. Do not use Telegram, shared files, or cron jobs for internal agent messaging.

7. PROFILES: MULTIPLE AGENTS WITH ISOLATION

⌄

Profiles let you run multiple independent Hermes agents with separate configs, memory, skills, sessions, and credentials.

Commands:

PROMPT

hermes profile list
hermes profile create <name>
hermes -p <name> config edit
hermes -p <name> gateway setup telegram
hermes -p <name> gateway install
hermes -p <name> gateway start
hermes -p <name> gateway status

Recommended profile design:

CODE

default       Technical lead / infrastructure / escalation
email         Email processing and triage
calendar      Calendar/scheduling assistant
research      Web research and notes
dev           Coding and GitHub helper
obsidian      Knowledge-base steward

Each profile should have:

CODE

~/.hermes/profiles/<name>/config.yaml
~/.hermes/profiles/<name>/.env
~/.hermes/profiles/<name>/skills/
~/.hermes/profiles/<name>/logs/

If using Telegram bots, give each profile its own Telegram bot token. Do not reuse a token across multiple running gateways.

Profile Telegram setup pattern:

CODE

hermes -p <profile> gateway setup telegram --bot-token <token>

Practical convention:

CODE

~/.hermes/profiles/<profile>/.env                  # TELEGRAM_BOT_TOKEN=...
~/.hermes/profiles/<profile>/telegram_bot_token.txt # raw token if you use helper scripts

Do not store the token in Obsidian.

8. GATEWAY: KEEP HERMES AVAILABLE FROM CHAT

⌄

The gateway is what keeps Hermes connected to Telegram/Discord/Slack/etc.

Commands:

CODE

hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status

On macOS, Hermes installs a launchd service similar to:

CODE

~/Library/LaunchAgents/ai.hermes.gateway.plist

Useful checks:

CODE

launchctl list | grep hermes
tail -100 ~/.hermes/logs/gateway.log
tail -100 ~/.hermes/logs/gateway.error.log

Terrell’s primary gateway pattern:

CODE

- The gateway runs as a launchd service.
- It uses --replace so restarts replace stale instances cleanly.
- gateway.bind_address is set to 0.0.0.0 for LAN accessibility where needed.
- API server is enabled for local dashboard/integrations.

Config snippet:

CODE

gateway:
  bind_address: 0.0.0.0
  port: 9119

CODE

platforms:
  api_server:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8642

If exposing beyond localhost/LAN, add real authentication, firewall rules, TLS/reverse proxy, and do not bind sensitive interfaces publicly without a reason.

9. HERMES DASHBOARD

⌄

Hermes has a dashboard for monitoring/interaction depending on your install/version.

Basic command:

CODE

hermes dashboard

Terrell’s pattern is to run the dashboard as its own launchd service so it survives gateway restarts and login sessions.

Example macOS launchd service:

CODE

~/Library/LaunchAgents/ai.hermes.dashboard.plist

Example plist:

CODE

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.hermes.dashboard</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USER/.hermes/hermes-agent/venv/bin/hermes</string>
        <string>dashboard</string>
        <string>--tui</string>
        <string>--skip-build</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--insecure</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USER</string>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USER/.hermes/logs/dashboard-stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USER/.hermes/logs/dashboard-stderr.log</string>
</dict>
</plist>

Load/start it:

PROMPT

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.hermes.dashboard.plist
launchctl enable gui/$(id -u)/ai.hermes.dashboard
launchctl kickstart -k gui/$(id -u)/ai.hermes.dashboard

Check it:

CODE

launchctl list | grep ai.hermes.dashboard
tail -100 ~/.hermes/logs/dashboard-stdout.log
tail -100 ~/.hermes/logs/dashboard-stderr.log

Why separate dashboard from gateway?

CODE

- Gateway restarts should not kill dashboard.
- Dashboard can be independently supervised and restarted.
- Logs are separate and easier to debug.

Security note:

CODE

--host 0.0.0.0 and --insecure are convenient for LAN testing, not for internet exposure. Put it behind a reverse proxy with auth/TLS if exposing outside your machine.

Prompt to give your agent:

PROMPT

Enable the Hermes dashboard as a separate supervised service, not as a fragile foreground process. On macOS use launchd with KeepAlive and RunAtLoad. Keep dashboard logs separate under ~/.hermes/logs. Verify the process with launchctl and verify the port responds. Do not expose it publicly without auth/TLS.

10. CRON JOBS / SCHEDULED AUTOMATION

⌄

Hermes cron jobs are durable scheduled tasks. They can run an agent prompt, a script, or a script-only watchdog.

Commands:

PROMPT

hermes cron list
hermes cron create "0 9 * * *"
hermes cron pause <job_id>
hermes cron resume <job_id>
hermes cron run <job_id>
hermes cron remove <job_id>
hermes cron status

Schedule examples:

CODE

every 15m
every 2h
0 17 * * *
2026-06-01T09:00:00

Terrell’s useful cron patterns:

CODE

1. Daily Hermes update check at 5 PM
   - Loads hermes-agent skill
   - Reviews changelogs/updates/breaking changes
   - Sends concise action-required summary

CODE

2. Gateway health check every 15 minutes
   - Script-only no-agent watchdog
   - Quiet when healthy
   - Alerts only when something is wrong

CODE

3. Dashboard/plugin health check every 2 hours
   - Script-only no-agent watchdog
   - Checks dashboard/plugin availability

CODE

4. Obsidian/Kanban sync every 5 minutes
   - Script-only sync job
   - Quiet unless there is a real problem or configured output

CODE

5. Email bridge/poller where needed
   - Script-only polling is acceptable for external email bridge checks
   - Do not use polling cron for local inter-agent messaging

Recommended cron design:

CODE

- Use no-agent script mode for simple watchdogs.
- Print nothing when healthy.
- Print concise alert text when unhealthy.
- Use agent-driven cron when reasoning/summarization is needed.
- Include all context in the cron prompt because future cron runs start fresh.
- For recurring reports, make them actionable: changed, risk, action needed, recommended next step.

Prompt to create a daily update check:

PROMPT

Create a Hermes cron job that runs every day at 5:00 PM. It should load the hermes-agent skill, check for Hermes updates/release notes/changelog items, identify breaking changes or useful new capabilities, and send me a concise actionable summary with recommended backup/upgrade steps. Deliver it to this chat.

Prompt to create a quiet health watchdog:

PROMPT

Create a script-only Hermes cron watchdog that checks my Hermes gateway and dashboard health every 15 minutes. It should print nothing when everything is healthy. It should only deliver a concise alert when a process is down, a port is not responding, or logs show repeated recent errors. Store the script under ~/.hermes/scripts/ and verify it manually before scheduling it.

11. EMAIL SETUP

⌄

Hermes can interact with email through built-in platform integrations, provider CLIs, scripts, or IMAP/SMTP tooling.

Recommended design:

PROMPT

- Create a dedicated email profile/agent.
- Give it only the email-related tools/credentials it needs.
- Keep personal/work email separated if the risk profile differs.
- Use labels/folders instead of destructive deletes by default.
- Require approval before sending sensitive replies or forwarding private content.
- Store OAuth/API credentials in ~/.hermes/.env, ~/.hermes/auth.json, or profile-specific equivalents.
- Document routing rules in Obsidian without secrets.

Possible approaches:

CODE

A. Gmail/Google Workspace via gws CLI or Google APIs
B. IMAP/SMTP via Himalaya or another CLI
C. Platform-specific Hermes email gateway if configured
D. Custom Python script using IMAP/SMTP libraries or provider APIs

Example .env variables:

CODE

EMAIL_IMAP_HOST=imap.example.com
EMAIL_IMAP_USER=you@example.com
EMAIL_IMAP_PASSWORD=app-specific-password
EMAIL_SMTP_HOST=smtp.example.com
EMAIL_SMTP_USER=you@example.com
EMAIL_SMTP_PASSWORD=app-specific-password

Gmail/Google best practice:

CODE

- Prefer OAuth over raw password auth.
- If IMAP is used, use an app-specific password, not your main account password.
- Use least privilege scopes where possible.

Prompt to give your agent:

PROMPT

Set up a dedicated Hermes email profile. Keep email credentials profile-local, do not print secrets, and document non-secret routing rules. Use approval-only mode for sending, forwarding, archiving, or deleting until I explicitly approve a safer automation policy. Create quiet cron checks for urgent mail categories and summarize only important items.

Example email triage categories:

CODE

- urgent human email
- invoices/receipts
- calendar/scheduling
- newsletters/promotions
- security alerts
- family/school/kids
- work/client email

Reliability pattern:

PROMPT

- Dry-run first.
- Fetch latest N messages.
- Classify but do not mutate.
- Show proposed rules.
- Then enable labels/filters/actions one category at a time.

12. OBSIDIAN INTEGRATION

⌄

Use Obsidian as major memory / human-readable operations docs. Hermes memory is compact; Obsidian can hold larger structured context.

Recommended vault layout:

CODE

Vault/
  Agents/
    Agent Directory.md
    default/
    email/
    calendar/
    obsidian/
    shared/
      systems/
      procedures/
      standards/
  Businesses/
    <workspace>/
  Projects/
    <project>/

Terrell’s pattern:

CODE

- Each agent/profile gets its own folder under Agents/<agent-name>/.
- Shared cross-agent standards go under Agents/shared/.
- Business/workspace operations go under Businesses/<workspace>/.
- Search before creating notes.
- Update existing notes instead of making duplicates.
- Never put secrets in Obsidian.
- Use wikilinks for navigation.

Config currently supports plugins; Terrell’s setup has an obsidian-memory plugin enabled:

CODE

plugins:
  enabled:
    - obsidian-memory

Generic prompt to integrate Obsidian:

PROMPT

Integrate this Hermes setup with my Obsidian vault as a durable major-memory system. Search before creating notes. Create an Agents/Agent Directory.md index if one does not exist. Put profile-specific notes under Agents/<profile>/, shared procedures under Agents/shared/procedures/, shared systems under Agents/shared/systems/, and workspace notes under Businesses/<workspace>/. Never store secrets. After writing or editing notes, read them back to verify.

Prompt for an Obsidian steward agent:

PROMPT

Create a dedicated Obsidian steward Hermes profile. Its job is to search, organize, and update my vault safely. It may create and edit notes, but it must never delete or destructively reorganize without explicit approval. It should maintain an Agent Directory and shared standards/procedures indexes. It should escalate technical issues to the default profile through inter_agent_message.

13. SESSION SEARCH AND CONTINUITY

⌄

Hermes stores sessions in a searchable local database.

Use session search for:

PROMPT

- “What did we decide about X?”
- “Find the session where we set up Y.”
- “Where did we leave off?”
- Debugging prior agent behavior

Prompt to give your agent:

CODE

When I refer to something from a prior conversation, use session_search before asking me to repeat myself. Summarize what you found and cite the relevant session/context in plain English.

14. DELEGATION AND SUBAGENTS

⌄

Hermes can spawn subagents for parallel or isolated work.

Use delegation for:

PROMPT

- Independent research streams
- Code review + implementation in parallel
- Debugging multiple hypotheses
- Having a specialist inspect a subsystem

Config pattern:

CODE

delegation:
  max_concurrent_children: 3
  max_spawn_depth: 1
  child_timeout_seconds: 600
  orchestrator_enabled: true

Prompt to give your primary agent:

CODE

Use delegation intelligently. For complex tasks, split work into specialist subagents such as Docker, networking, backend, frontend, database, or security review. Pass each subagent complete context. Verify their claims before reporting success, especially for file writes, external API actions, or deployments.

15. MONITORING AND HEALTH CHECKS

⌄

Minimum reliable Hermes monitoring:

CODE

- Gateway process running
- Dashboard process running
- API server responding
- Cron scheduler healthy
- Disk space not full
- Recent logs do not show repeated errors
- Telegram/Discord/etc. bot polling not conflicted
- Provider credentials not expired
- Memory/config files readable

Useful commands:

CODE

hermes status --all
hermes doctor
hermes gateway status
hermes cron status
hermes cron list
hermes profile list
launchctl list | grep hermes
tail -100 ~/.hermes/logs/gateway.log
tail -100 ~/.hermes/logs/gateway.error.log

Prompt for a robust health system:

CODE

Build a quiet Hermes health monitoring setup. It should check gateway, dashboard, cron, API server, disk space, and recent logs. It should run on a schedule, print nothing when healthy, and alert me only when there is a real issue. Use script-only cron jobs for mechanical checks. Document the checks and verification steps in Obsidian without storing secrets.

16. GITHUB / WEB DEVELOPER WORKFLOW

⌄

For a web developer, Hermes is strongest when it has project-specific instructions.

Create repo-level files such as:

CODE

AGENTS.md
CLAUDE.md
README.md
.env.example
docker-compose.yml
Makefile

AGENTS.md should tell Hermes:

CODE

- How to install dependencies
- How to run tests
- How to run lint/typecheck
- How to start dev server
- Project architecture
- Deployment process
- Branch/PR conventions
- Safety rules

Example AGENTS.md snippet:

CODE

# Agent Instructions

CODE

## Setup
- Use pnpm install for Node dependencies.
- Use uv for Python tooling.
- Copy .env.example to .env.local; never print or commit secrets.

CODE

## Verification
- Run pnpm lint before commits.
- Run pnpm test for unit tests.
- Run pnpm build before deployment changes.

CODE

## Architecture
- frontend/ is Next.js.
- backend/ is FastAPI.
- db migrations live in backend/migrations/.

CODE

## Safety
- Do not run destructive database migrations without explicit approval.
- Do not commit .env files.

Prompt to give Hermes in a repo:

PROMPT

Inspect this repository and create an AGENTS.md file that teaches future Hermes sessions how to work here. Include install, dev server, tests, linting, build, deployment, environment variables, architecture overview, and safety rules. Verify commands where possible and avoid secrets.

17. API SERVER AND INTEGRATIONS

⌄

Hermes can expose an API server for dashboard, automation, webhooks, and external integrations.

Example config:

CODE

platforms:
  api_server:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8642

For LAN/external integration, consider:

CODE

- Bind host intentionally
- Use API_SERVER_KEY or equivalent bearer auth
- Use reverse proxy with TLS
- Restrict firewall rules
- Use stable session keys for automation continuity
- Log requests and failures

Do not expose a local agent with full terminal/file access to the public internet without strong auth and network controls.

Prompt:

PROMPT

Enable Hermes API server for local integrations only. Bind to 127.0.0.1 unless I explicitly request LAN access. If LAN access is needed, require bearer auth, document the endpoint, and verify it with a safe health request. Do not expose it publicly without TLS and authentication.

18. RELIABILITY PRINCIPLES TO GIVE YOUR FUTURE AGENT

⌄

Copy/paste this into your agent’s system/profile instructions:

CODE

You are my technical operations assistant. Prioritize reliability over cleverness. Verify assumptions with tools. Do not fabricate results. When configuring Hermes, use Hermes-native config and commands. Keep secrets out of memory, notes, logs, and replies. Use ~/.hermes/.env or profile-local .env files for credentials. Use config.yaml for behavior. Use skills for reusable procedures. Use memory only for compact durable facts. Use Obsidian for long-form human-readable operating docs. Search before creating notes. Never delete or destructively reorganize without approval. Use cron jobs for durable scheduled automation. Use script-only no-agent cron jobs for quiet mechanical watchdogs. Use inter_agent_message for profile-to-profile communication. Escalate infrastructure failures to the default technical lead profile with exact logs and what was tried. After making changes, verify with real commands and report actual output, not guesses.

19. INITIAL “MAKE MY HERMES ROBUST” PROMPT

⌄

Copy/paste this to a new Hermes agent:

PROMPT

I want you to harden and organize my Hermes setup. First inspect my current Hermes version, config path, env path, enabled tools, gateway status, cron status, profile list, and logs. Do not print secrets. Then propose and implement a safe baseline:

PROMPT

1. Enable persistent memory and user profile memory.
2. Enable useful toolsets for technical work: web, browser, terminal, file, code_execution, skills, memory, session_search, delegation, cronjob, messaging.
3. Configure secret redaction if available.
4. Set up or verify the messaging gateway as a supervised service.
5. Set up or verify the dashboard as a separate supervised service so gateway restarts do not kill it.
6. Create quiet health-check cron jobs for gateway/dashboard/API/cron/log errors.
7. Create a daily Hermes update-check cron job.
8. If I use multiple profiles, enable inter_agent_message and define escalation to the default profile.
9. Set up Obsidian as durable major memory with safe folder structure and no secrets.
10. Document everything in a readable setup note.

CODE

Work methodically. Verify each change. If something is risky, ask before doing it. If something fails, show the exact error and try a safe alternative.

20. INITIAL PROFILE CREATION PROMPT

⌄

Copy/paste:

PROMPT

Help me create isolated Hermes profiles for specialized agents. I want a default technical lead, an email agent, an Obsidian/notes agent, and a dev/code agent. Each profile should have its own ~/.hermes/profiles/<name>/ directory, config.yaml, .env, logs, memory, and gateway if needed. Do not reuse Telegram bot tokens across running gateways. Enable inter_agent_message so non-primary agents can escalate technical issues to default. Document non-secret profile responsibilities and paths in Obsidian.

21. INITIAL EMAIL AGENT PROMPT

⌄

Copy/paste:

PROMPT

Set up a dedicated Hermes email agent/profile. Keep credentials profile-local and never print secrets. Start in read-only/dry-run mode. Inspect what email integration method is safest for my provider: OAuth/API, Gmail/Google Workspace tooling, IMAP/SMTP, or Hermes gateway email support. Create triage categories, propose routing rules, and require my approval before sending, forwarding, archiving, deleting, or creating calendar events. Add quiet cron checks only for important mail. Document non-secret rules in Obsidian.

22. INITIAL OBSIDIAN PROMPT

⌄

Copy/paste:

PROMPT

Set up Obsidian as my long-form durable memory for Hermes. Search before creating notes. Create or update an Agents/Agent Directory.md, Agents/shared/systems/, Agents/shared/procedures/, and per-profile folders. Store no secrets. Use wikilinks. Keep local Hermes memory compact and put larger operating docs in Obsidian. After any write, read the file back and summarize what changed.

23. INITIAL DASHBOARD PROMPT

⌄

Copy/paste:

PROMPT

Enable the Hermes dashboard and make it durable. Run it as a separate supervised service, not as a child of the gateway. On macOS, use a launchd plist with RunAtLoad and KeepAlive. Bind to 127.0.0.1 by default unless I ask for LAN access. If LAN access is enabled, explain security risks and recommend auth/TLS. Verify with launchctl, logs, and a local HTTP check.

24. INITIAL CRON PROMPT

⌄

Copy/paste:

PROMPT

Review my Hermes cron setup and create a reliable baseline. I want a daily Hermes update check, a quiet gateway health watchdog, a quiet dashboard/API watchdog, and any needed email/Obsidian sync jobs. For script-only watchdogs, print nothing when healthy and only alert on real problems. For agent-driven jobs, make the prompt self-contained and concise. Verify each job manually once before relying on it.

25. WEB DEVELOPER JOB EXAMPLES

⌄

Here are practical things a web developer can set up with Hermes so it becomes useful at work, not just as a chatbot.

A. Repo onboarding assistant

Goal:

PROMPT

Hermes can inspect any repo and explain how to work in it.

Set up:

CODE

- Add an AGENTS.md file to each important repo.
- Include install, test, lint, build, dev server, deployment, and safety rules.
- Tell Hermes to verify commands instead of guessing.

Copy/paste prompt:

PROMPT

Inspect this web app repository and create or update AGENTS.md. Include stack overview, install commands, dev server commands, test/lint/build commands, environment variable names using placeholders only, deployment notes, common pitfalls, and safety rules. Verify as many commands as possible and report real output.

Useful outcome:

CODE

Your agent can jump into a Next.js, React, Vue, Laravel, Rails, Django, FastAPI, Node, or monorepo project and know how to operate without asking the same setup questions every time.

B. Pull request builder

Goal:

PROMPT

Hermes can create a branch, implement a change, test it, commit it, push it, and open a PR.

Set up:

CODE

- Install and authenticate GitHub CLI: gh auth login
- Store GITHUB_TOKEN in ~/.hermes/.env only if CLI auth is not enough.
- Add repo-specific PR conventions to AGENTS.md.

Copy/paste prompt:

PROMPT

Implement this change using a safe GitHub PR workflow. Start from main, create a feature branch, inspect the codebase, write or update tests first where appropriate, make the smallest correct change, run lint/tests/build, commit with a conventional commit message, push, open a draft PR, and summarize the diff and verification output. Do not merge without my approval.

Good examples:

CODE

- Add a new API endpoint and tests.
- Fix a login redirect bug.
- Add a feature flag.
- Refactor a component while preserving behavior.
- Add a missing validation rule.

C. CI failure fixer

Goal:

CODE

Hermes watches a failed GitHub Actions run, reads logs, fixes the issue, pushes a commit, and re-checks CI.

Copy/paste prompt:

PROMPT

Diagnose and fix the failing CI for this branch. Use gh if available. Read the failed job logs, identify the root cause, make the minimal fix, run the relevant command locally, commit and push the fix, then watch CI again. Stop after three failed attempts and ask me with a concise summary.

Useful for:

CODE

- TypeScript type errors
- ESLint failures
- broken tests
- missing env var examples
- build failures
- dependency/version mismatches

D. Test-driven bug fixing

Goal:

CODE

Hermes reproduces a bug with a failing test before fixing it.

Copy/paste prompt:

PROMPT

Fix this bug using test-driven development. First write a failing test that reproduces the bug and run it to prove it fails for the expected reason. Then implement the minimal fix, rerun the specific test, then run the relevant full test suite. Do not change unrelated behavior.

Useful examples:

CODE

- Form validation bug
- API response edge case
- auth/session bug
- date/timezone bug
- pagination bug
- race condition around async data fetching

E. Frontend component generator

Goal:

CODE

Hermes builds UI components consistent with your project’s existing patterns.

Copy/paste prompt:

PROMPT

Build a reusable frontend component for <feature>. First inspect existing components for styling, state management, naming, testing, and accessibility patterns. Then create the component, add Storybook stories if this repo uses Storybook, add tests if the repo has component tests, and verify lint/build. Keep it consistent with the existing design system.

Examples:

CODE

- Pricing card component
- Dashboard metric tile
- Modal/dialog component
- User profile dropdown
- Search/filter toolbar
- Empty/error/loading states

Ask Hermes to check:

CODE

- accessibility labels
- keyboard navigation
- responsive layout
- dark mode behavior
- loading/error states
- reusable props API

F. API integration assistant

Goal:

CODE

Hermes wires third-party APIs into a web app safely.

Copy/paste prompt:

PROMPT

Integrate <API name> into this project. Read the official docs, identify auth requirements, add environment variable placeholders to .env.example, implement a typed client/wrapper, add tests with mocked network calls, handle errors/retries/rate limits, and document usage. Do not print or commit real API keys.

Examples:

CODE

- Stripe checkout/subscriptions
- Resend/Postmark email
- Twilio SMS
- OpenAI/OpenRouter API
- Google Maps
- Airtable/Notion
- Slack/Discord webhooks

Reliability pattern:

CODE

- Use typed request/response shapes.
- Centralize API client code.
- Add retry/backoff only where safe.
- Log useful metadata, not secrets.
- Add .env.example placeholders.

G. Database migration reviewer

Goal:

CODE

Hermes reviews DB migrations before they break production.

Copy/paste prompt:

PROMPT

Review this database migration for safety. Check for destructive operations, locks, missing indexes, backfill risks, rollback strategy, and production impact. If safe, explain why. If risky, propose a safer expand-contract migration plan. Do not run destructive migrations without explicit approval.

Useful for:

CODE

- Prisma migrations
- Drizzle migrations
- Alembic migrations
- Rails migrations
- Laravel migrations
- raw SQL migrations

Ask for:

CODE

- rollback plan
- zero-downtime plan
- index strategy
- backfill strategy
- staging verification

H. Performance and Core Web Vitals helper

Goal:

CODE

Hermes finds performance bottlenecks and proposes measurable fixes.

Copy/paste prompt:

CODE

Audit this web app for performance. Check bundle size, large dependencies, image optimization, lazy loading, caching, server/client rendering boundaries, database/API waterfalls, and Core Web Vitals risks. Give prioritized fixes with expected impact and verification commands.

Examples:

CODE

- Reduce Next.js bundle size
- Replace heavy client dependency
- Add image optimization
- Fix N+1 API/database calls
- Improve caching headers
- Split large routes/components

I. Security review assistant

Goal:

CODE

Hermes reviews web app changes for common security issues.

Copy/paste prompt:

PROMPT

Perform a security review of this change. Check authentication, authorization, input validation, output encoding, secret handling, SSRF, XSS, CSRF, SQL injection, dependency risks, and unsafe logging. Give findings by severity and include concrete fixes. Do not run destructive commands.

Good targets:

CODE

- auth flows
- payment endpoints
- admin dashboards
- file uploads
- webhook handlers
- API routes

J. Webhook builder and tester

Goal:

CODE

Hermes builds robust webhook endpoints and tests them.

Copy/paste prompt:

CODE

Build a robust webhook endpoint for <provider>. Verify signature validation, idempotency, replay protection where possible, event routing, safe logging, and tests using sample payloads. Add .env.example placeholders. Do not store real signing secrets in code or docs.

Examples:

CODE

- Stripe webhooks
- GitHub webhooks
- Clerk/Auth0 webhooks
- Shopify webhooks
- Slack events

Reliability checklist:

CODE

- signature verification
- idempotency key/event ID storage
- safe failure behavior
- retry awareness
- structured logs
- fixture payload tests

K. Local dev environment bootstrapper

Goal:

CODE

Hermes makes local setup easy for future you and teammates.

Copy/paste prompt:

PROMPT

Create a local development bootstrap for this project. Inspect the stack and add or improve .env.example, README setup steps, Docker Compose if appropriate, Makefile/package scripts, seed data instructions, and health checks. Verify the app starts locally if dependencies are available.

Artifacts Hermes can create:

CODE

- .env.example
- docker-compose.yml
- Makefile
- scripts/dev-check.sh
- docs/local-development.md
- seed script
- health endpoint

L. Documentation generator

Goal:

CODE

Hermes turns project knowledge into useful docs.

Copy/paste prompt:

CODE

Generate developer documentation for this project. Include architecture overview, request/data flow, important directories, environment variables, local setup, deployment, testing, troubleshooting, and known gotchas. Keep it accurate by reading the repo, not guessing.

Good docs to ask for:

CODE

- onboarding guide
- API docs
- deployment runbook
- incident/debugging runbook
- architecture diagram
- feature flag guide
- environment variable reference

M. Release manager

Goal:

CODE

Hermes prepares releases without forgetting steps.

Copy/paste prompt:

PROMPT

Prepare a release checklist for this repo. Inspect recent commits/PRs, summarize changes, check tests/build status, identify migration or env var changes, update changelog if applicable, and produce a deployment checklist with rollback steps. Do not deploy without my approval.

Useful outputs:

CODE

- release notes
- changelog entry
- deployment checklist
- rollback plan
- risk summary

N. Daily developer briefing cron

Goal:

CODE

Hermes sends a morning summary of what matters for work.

Copy/paste prompt:

PROMPT

Create a weekday morning cron job that gives me a concise developer briefing: open PRs needing my review, my failing CI runs, urgent GitHub issues, production alerts if integrated, and calendar focus blocks if available. Keep it short and actionable. Do not include noise.

Possible integrations:

CODE

- GitHub CLI/API
- Linear/Jira
- Slack/Discord summaries
- Sentry/Datadog alerts
- Google Calendar

O. Codebase map / architecture report

Goal:

CODE

Hermes maps an unfamiliar app quickly.

Copy/paste prompt:

PROMPT

Create a codebase map for this repo. Identify languages/frameworks, important directories, entry points, routes, APIs, database models, background jobs, config files, test structure, build pipeline, and deployment clues. Save a concise architecture report to docs/codebase-map.md and verify it against actual files.

Good for:

CODE

- starting a new job
- inheriting a legacy codebase
- onboarding contractors
- planning refactors

P. Design-to-code helper

Goal:

CODE

Hermes turns screenshots, Figma notes, or written requirements into UI code.

Copy/paste prompt:

PROMPT

Implement this UI from the attached screenshot/requirements. First inspect the existing design system and components. Then build the UI using existing patterns, responsive layout, accessible markup, and realistic loading/error states. Add tests/stories if this project uses them. Verify lint/build.

Best practice:

CODE

Give Hermes screenshots, current component paths, and the exact route/component where the UI belongs.

Q. Production incident assistant

Goal:

PROMPT

Hermes helps diagnose incidents methodically without making things worse.

Copy/paste prompt:

PROMPT

Help debug this production issue methodically. Gather evidence first: logs, recent deploys, error traces, metrics, affected endpoints, and reproduction steps. Do not make destructive changes. Propose the safest mitigation, then root-cause analysis, then a durable fix and postmortem notes.

Use for:

CODE

- outage triage
- high error rate
- slow endpoint
- failed deploy
- broken auth/payment flow

R. Personal reusable automations

Goal:

CODE

Hermes handles repetitive developer chores.

Ideas:

PROMPT

- “Summarize this PR diff for my manager.”
- “Turn these rough notes into a ticket.”
- “Create Linear/Jira tickets from this feature spec.”
- “Check if any dependencies have security advisories.”
- “Generate curl examples for this API endpoint.”
- “Convert this JSON response into TypeScript types.”
- “Write Playwright tests for this user flow.”
- “Make a seed script for demo data.”
- “Find dead routes/components.”
- “Compare staging vs production env var names without printing values.”

S. Recommended work profile setup for a web developer

If he wants multiple profiles, a good work-oriented setup is:

CODE

default / lead:
  technical lead, system health, escalation, architecture

CODE

dev:
  coding, PRs, tests, repo work

CODE

reviewer:
  code review, security review, CI failure analysis

CODE

notes:
  Obsidian/docs/runbooks

CODE

email-calendar:
  work email triage, calendar summaries, meeting prep

CODE

monitor:
  quiet cron watchdogs for CI, deploys, uptime, alerts

Each non-default profile should know:

CODE

- what it owns
- what it must not touch
- when to escalate to default
- where credentials live
- where to document non-secret durable facts

26. TROUBLESHOOTING CHECKLIST

⌄

When Hermes acts weird:

CODE

1. Run hermes doctor.
2. Check hermes status --all.
3. Check gateway status.
4. Check cron status/list.
5. Check logs in ~/.hermes/logs/.
6. Verify .env exists and required keys are present without printing values.
7. Verify toolsets are enabled.
8. Restart gateway after config/tool changes.
9. Start a new session after tool/skill changes.
10. Search prior sessions before repeating old debugging.

Commands:

CODE

hermes doctor
hermes status --all
hermes gateway status
hermes cron status
hermes cron list
hermes tools list
hermes config check
tail -100 ~/.hermes/logs/gateway.log
tail -100 ~/.hermes/logs/gateway.error.log

27. FINAL RECOMMENDED BASELINE

⌄

For a strong first Hermes setup, ask your agent to deliver these artifacts:

CODE

- Verified Hermes install and doctor output
- Enabled memory and user profile memory
- Enabled core technical toolsets
- Secrets in ~/.hermes/.env, never in notes
- Gateway installed as service
- Dashboard installed as separate service
- API server enabled locally if needed
- Daily update-check cron
- Quiet gateway/dashboard health-check crons
- Inter-agent escalation pattern if using profiles
- Obsidian vault integration with safe folder structure
- Dedicated email agent/profile if using email automation
- Repo-level AGENTS.md files for important codebases
- Documented troubleshooting checklist

If your future agent claims something is done, ask it:

CODE

“Show me the command you ran to verify it and the real output.”

That one sentence prevents a lot of fake confidence.

END OF GUIDE