Hermes + Claude Code Dual-Stack Orchestrator

Hermes Agent v0.13 from Nous Research runs as a persistent daemon on a VPS, managing Telegram-based command-and-control, cron jobs, and multi-channel message routing. Claude Code from Anthropic handles local in-repo coding tasks on the developer's machine, connected to Hermes via the Model Context Protocol (MCP) bridge. The agentic reasoning step occurs inside Hermes when it evaluates incoming Telegram messages and decides whether to execute built-in tools directly or delegate to Claude Code via MCP for file editing, code generation, or test execution. This is not simple automation: Hermes maintains session memory across conversations, auto-generates reusable skills from repeated patterns, and manages a full FTS5-indexed persistent memory store. The dual-stack design means the VPS never stores source code and the local machine never exposes a public attack surface. Developers using this split architecture report reclaiming 15-25 hours per week by shifting background operations, research, and report generation to the VPS daemon while keeping hands-on coding inside Claude Code's native environment.

BUSINESS PROBLEM

A solo developer or small team maintains a VPS for background automation, deploys cron jobs for monitoring, and uses Claude Code for local coding tasks. Without a dual-stack bridge, these systems operate in isolation. The developer switches between Telegram, terminal, email, and browser to check outputs from different tools. A 2025 Port.io survey found that 75% of developers lose 6-15 hours weekly to tool-switching overhead (Source: Port.io State of Internal Developer Portals, 2025). This fragmentation compounds with every new automation: each tool has its own notification method, authentication flow, and output format. The developer spends more time context-switching than producing work. Hourly, that is $75-$150/hour in lost productivity for a senior developer. Annually, a team of three burns $46,000-$93,000 in salary on tool overhead alone. The dual-stack architecture solves this by centralizing all background operations under Hermes with Telegram as the single control surface, while keeping Claude Code isolated for coding work.

WHO BENEFITS

Solo SaaS founders running 5+ automated services on a VPS who currently monitor outputs across separate dashboards, Telegram bots, and email alerts. This workflow consolidates all oversight into one Telegram conversation. Freelance full-stack developers managing 3-7 client projects who need background task execution (server monitoring, log analysis, report generation) without context-switching away from active coding sessions. Engineering teams of 2-5 where one member handles infrastructure and the rest focus on feature work — the dual-stack design lets the infra person manage everything via Telegram while the team uses Claude Code normally.

HOW IT WORKS

1. Intake and Routing: Telegram channel receives a user message. Hermes Agent v0.13 checks the message content against FTS5-indexed session memory to determine if it references a prior task. Output: a parsed intent object with task_type and priority fields.
2. Decision Point (Agentic Reasoning): Hermes evaluates the intent against its 40+ built-in tools and installed MCP server list. If the task involves code changes, file system operations, or test execution, Hermes flags it for Claude Code delegation. Output: routing decision stored in session context.
3. Local MCP Bridge Activation: Hermes sends a structured task payload to the Claude Code MCP server running on the developer's machine via the hermes mcp serve stdio transport. Input: JSON with task_type, file_paths, instructions. Output: a session ID confirming the bridge is active.
4. Claude Code Execution: Claude Code reads project files, analyzes the requested change, writes code, runs tests, and commits. Input: the task instructions from step 3. Output: a structured result with diff, test results, commit hash.
5. Result Relay: Claude Code sends the result back through the MCP bridge to Hermes. Hermes formats the response for Telegram including the diff summary, pass/fail status, and any error logs. Output: formatted Telegram message.
6. Human Review Checkpoint: The developer reviews the Telegram summary and approves or rejects via a reply command (e.g., /approve or /reject). If rejected, Hermes appends feedback and re-routes to Claude Code. Output: approval token or revision request.
7. Memory Consolidation: If approved, Hermes extracts the task pattern, file paths, and Claude Code's approach and writes it as a reusable skill in MEMORY.md. Output: newly generated skill available for future similar tasks.
8. Cron Scheduling (Optional): If the task is recurring, the developer sends /schedule and Hermes registers it as a cron job in its built-in scheduler. Output: confirmed schedule entry with next run time.

TOOL INTEGRATION

Hermes Agent v0.13: The core orchestrator. Runs as a persistent daemon on a Linux VPS (Ubuntu 22.04+). API keys are configured via hermes setup which writes to ~/.hermes/config.yaml. Required scopes: filesystem (for skill storage), network (for MCP and Telegram API). Rate limit: depends on your LLM provider's tier. Gotcha: Hermes installs via a curl script, but the default install does NOT include MCP support. You must run the MCP extras install separately, otherwise hermes mcp serve will fail with a module-not-found error.

Claude Code: Handles all local code operations. Installed via npm globally on the developer's machine. Authentication uses the Anthropic API key set in ANTHROPIC_API_KEY environment variable. Rate limits at 80-100 requests per minute on the API tier. Permission scope: local filesystem within the project directory. Gotcha: Claude Code's MCP integration requires the claude mcp add command to register Hermes as a server, but if you have an existing ~/.claude.json, the command silently fails to overwrite — delete or backup the file first.

Telegram Bot API: Acts as the user interface. Create a bot via BotFather at t.me/BotFather. The bot token is configured in Hermes via hermes gateway setup. Permission scope: can read messages (for commands) and send messages (for responses). Rate limit: 30 messages/second per bot. Gotcha: Telegram bots in groups require Privacy Mode to be disabled via BotFather's /setprivacy command, otherwise the bot will not see group messages that do not mention it.

ROI METRICS

1. Tool-switching overhead: 10-15 hrs/week managing separate dashboards and notifications → consolidated into 1-2 hrs/week via single Telegram interface.
2. Background task execution: 5-10 hrs/week of manual cron monitoring and log checking → fully automated with Hermes cron + alerting, measurable in week 1.
3. Code context-switch cost: 15-20 min per task (average context restoration time) × 8-12 tasks/day → eliminated by keeping Claude Code focused while Hermes handles non-coding tasks.
4. Skill compounding: 0 hrs/year of knowledge reuse without the system → 40-80 hrs/year saved as Hermes auto-generates reusable skills from completed tasks.
5. Cost at $100/hr developer rate: $1,500-$2,500/week lost to fragmentation → $150-$250/week in API and VPS costs.

CAVEATS

1. VPS compromise risk: If your VPS is breached, an attacker could send commands through the Telegram bridge. Mitigate by using Hermes's allowlist feature (allowFrom) to restrict Telegram access to specific user IDs.
2. MCP bridge disconnection: Hermes and Claude Code communicate over stdio — if the developer's machine sleeps or loses network, the bridge drops silently. Hermes does not auto-retry; it returns a tool unavailable error. You need a keepalive script or Tailscale mesh.
3. API cost spikes: Hermes's cron jobs can trigger dozens of LLM calls per hour. Without a per-skill budget limit, a misconfigured research task could cost $50+ in a single night. Set max_tokens and max_calls per skill in config.yaml.
4. This workflow does NOT handle multi-repo projects or cross-VPS file synchronization. Each Claude Code instance is tied to one local project directory.