Hermes Agent

Jimmy's self-built personal AI agent framework: profile + auth pool + IM gateway + skill plugin — the runtime substrate for review-agent / personal-ai-delegate and other in-house products.

1. Core Product / Service

Hermes is a dual-deployment (local + VPS) agent runtime, upstream forked from NousResearch's hermes-agent. Jimmy uses it as "the container for all in-house AI workflows".

Core architecture:

• CLI entry: hermes wrapper, backed by hermes_cli.main (Python venv); installed locally at ~/.hermes/, running as a systemd --user service under a dedicated user on the VPS.
• Profile system: hermes profile create/use/alias manages multiple independent configurations, supports --clone-all for credential copying, used for isolating "OAuth subscription vs cheap provider" setups.
• Auth pool: all provider credentials are centrally stored in ~/.hermes/auth.json as the single source of truth; supports API key / OAuth / PKCE types.
• Model routing tiers (config.yaml):
  • model: primary conversation model (used by hermes chat and the IM gateway)
  • auxiliary.* small tasks (approval / compression / flush_memories / mcp / session_search / skills_hub / web_extract / vision) each specifying provider+model
  • delegation.* subagent invocations routed separately
  • compression.* history compression routed separately
• IM Gateway: native Lark/Feishu integration (~/.hermes/.env configures FEISHU_APP_ID/SECRET/DOMAIN); Telegram and Slack are connected via channel adapters. Allowlist + pair flow + admin-notify, three layers of access control already patched into gateway/run.py.
• Cron: ~/.hermes/cron/jobs.json supports per-job provider/model/base_url override (the CLI doesn't expose these fields; edit the JSON directly).
• Skill plugin: ~/.hermes/skills/<category>/<name>/SKILL.md registers local skills; the scanner doesn't follow symlinks — must rsync real copies.

Provider coverage: native support for Anthropic (including OAuth subscription tokens), Moonshot Kimi (kimi-coding / kimi-coding-cn, K2.5/K2.6 already in the built-in model list), DeepSeek direct, openrouter for all remaining models.

2. Target Users & Pain Points

Main "user": Jimmy himself — a serial entrepreneur doing AI automation post-crypto-exit, running multiple crons, IM channels, and sub-agents daily, needing a tool that wraps all of these in the same shell.

Potential extended users: personal-ai-delegate uses Hermes as an SDK, targeting "senior managing junior" workflows; review-agent uses Hermes as the host runtime — any hermes user can install it after public release.

Pain points / design motivations:

• Claude Code and OpenClaw CLIs are single-session, single-channel, single-model; Jimmy's workflow is multi-channel + multi-cron + multi-model
• Subscription OAuth quota (Anthropic Pro/Max) and pay-per-use need to be burned separately — primary conversation uses the subscription, subagents and compression go to cheap providers
• Multiple IM bots share the same auth pool and skill library, avoiding per-channel reconfiguration
• Upstream patches get blown away by hermes update — so Jimmy writes all patches as idempotent Python scripts with backup + marker

3. Competitive Landscape

Key differentiation: multi-IM channel + cron + multi-model routing combined, with fine-grained routing of personal subscription OAuth quotas. Claude Code and Aider lack this abstraction layer; OpenClaw is more geared toward team multi-user scenarios; the Anthropic Agent SDK is library-level and requires assembly.

4. Unique Observations

• OAuth subscription + auxiliary separation is the key to cost savings: the main model uses Anthropic OAuth (consuming subscription quota); auxiliary/delegation/compression all point to cheap models on openrouter like deepseek / minimax-m2.7. Subagent 8-concurrency × OAuth easily hits rate limits, so routing delegation to cheap providers is a necessary protection.
• Trap of crons defaulting to the main model: if the main model is OAuth, daily crons will burn subscription quota and easily trigger Anthropic anomaly detection — must explicitly override provider/model in jobs.json (the CLI doesn't expose these fields). This is an implicit risk; you don't discover it without stepping in the pit.
• PKCE state = code_verifier trick: hermes stuffs the PKCE code_verifier directly into the OAuth state parameter (agent/anthropic_adapter.py), so the state pasted back from the authorization callback equals the verifier. If the flow dies mid-way you can manually hit the token endpoint to exchange for tokens — a rare but clever implementation.
• Skill scanner doesn't follow symlinks: a skill in development must be rsync'd as a real copy to ~/.hermes/skills/<category>/<name>/ to be recognized; ln -s is silently ignored. The dev flow is: edit dev path → sync → verify.
• Kimi integration with zero source changes: Moonshot Kimi is natively supported, including automatic base-URL switching (a sk-kimi- key prefix → api.kimi.com/coding, regular sk- → configure base_url), and tool schema sanitize runs automatically. hermes auth add kimi-coding is enough to connect K2.5/K2.6.
• Upstream patches get blown away: hermes-agent is the NousResearch upstream repo; local patches (DeepSeek thinking disable / Feishu allowlist / admin notify) will be overwritten by hermes update — so all of Jimmy's patches are written as idempotent scripts kept on the VPS, with marker + backup, to be re-run after updates.
• Tradeoff vs OpenClaw: OpenClaw was Jimmy's early workhorse, better suited for "team multi-user collaboration" scenarios (dmPolicy / allowFrom / multi-user isolation); Hermes came later after he realized "running solo I actually need profile + auth pool + cron more". Both are still in use, with division of labor — see openclaw-hermes-updates.
• Kimi via Hermes path: direct Moonshot connection is cheaper than going through openrouter (OpenRouter may not pass through prompt-caching discounts), but Kimi on OpenRouter is also cheaper than direct Moonshot (third-party providers compete fiercely) — depends on whether the workload is cache-friendly.

5. Financials

N/A — internal personal tool; not monetized, not raising, not commercialized. Functions as the underlying runtime for potentially commercializable products like review-agent / personal-ai-delegate.

6. People & Relationships

• Builder: Jimmy (personal project)
• Upstream: NousResearch hermes-agent (fork, local patches maintained via idempotent scripts)
• Hosted at: local macOS (dev) + personal VPS (systemd --user runs gateway / cron)
• Models routed:
  • Primary conversation: Anthropic Claude (OAuth subscription)
  • Auxiliary / subagent: deepseek / minimax / glm etc. via openrouter
  • Direct: kimi (Moonshot) for coding / long context
• Built on top:
  • review-agent — Hermes skill, pre-meeting material review
  • personal-ai-delegate (PAID) — Hermes plugin paid-v1, senior-managing-junior delegate
• Ecosystem comparison: tinyfish (alternative if not wanting to self-build web automation)

Sources

• local: memory/reference_hermes_config.md — Hermes config architecture, profile, auth pool, OAuth PKCE, cron override risk
• local: memory/reference_hermes_kimi_provider.md — Kimi/Moonshot native support, base-URL auto-switching, tool schema sanitize
• local: memory/reference_hermes_feishu_allowlist.md — Feishu gateway three-layer allowlist + admin-notify patch + upstream-update override issue
• local: memory/feedback_hermes_skill_install.md — Skill scanner doesn't follow symlinks, must rsync
• local: 2026-04-20-summary.md (referenced in original wiki, not found in raw/, questionable)