hermes-claude-code-rc

A Hermes Agent plugin that lets you remotely control Claude Code sessions from Telegram (or any Hermes-connected platform).

Start a Claude Code remote session from your phone, run headless commands, execute shell commands on your machine, and manage everything through simple /cc slash commands.

Where This Fits

As of April 2026, Claude Code offers several ways to work remotely:

Cloud sessions (iOS app, web, Routines) are great for GitHub-connected work, but they can't access your local filesystem, local MCP servers, local databases, or any tools installed on your machine.

Remote Control is the only option that runs on your machine with full local access — but it requires a terminal to start the session.

This plugin bridges that gap. Message your Hermes Telegram bot from anywhere, it starts the Remote Control session on your machine, and sends you the URL to open in the Claude app. Full bidirectional control over your local environment from your phone.

Three tiers of remote access

1. Quick cloud task — Open the Claude iOS app, describe the task, done. No setup needed. But no local machine access.
2. Local session from phone — /cc start my-feature via Telegram, open the URL in Claude app. Full local access. (This is what this plugin enables.)
3. Automated/scheduled — Routines (cloud) for recurring tasks, or /cc run (local) for one-shot commands on your machine.

Commands

Prerequisites

• Hermes Agent with Telegram configured
• Claude Code CLI installed and authenticated (claude auth login)
• Claude Pro/Max/Team/Enterprise subscription (required for Remote Control)

Installation

1. Apply the Hermes patch

This plugin uses register_command() which requires a small patch to hermes_cli/plugins.py. This patch adds gateway slash command support to the Hermes plugin system.

cd ~/.hermes/hermes-agent
git apply /path/to/hermes-claude-code-rc/hermes-plugin-commands.patch

Or apply manually — the patch adds three things:

• register_command() method on PluginContext
• _commands dict on PluginManager
• get_plugin_command_handler() module-level function

2. Install the plugin

# Clone or copy into your Hermes plugins directory
cp -r hermes-claude-code-rc ~/.hermes/plugins/claude-code-rc

Or symlink for development:

ln -s /path/to/hermes-claude-code-rc ~/.hermes/plugins/claude-code-rc

3. Restart Hermes

# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway

# Or manually
hermes gateway restart

4. Verify

Send /cc help to your Hermes Telegram bot. You should see the command listing.

Configuration

All configuration is via environment variables (set in ~/.hermes/.env or your launchd plist):

Usage

Start a remote session

/cc start my-feature

Returns a claude.ai/code/... URL. Tap it on your phone to open in the Claude iOS app with full bidirectional control.

Run a quick command

/cc run check if the tests pass in ~/projects/myapp

Runs Claude Code headless (claude -p) and returns the result.

Run a shell command

/cc shell ls -la ~/Desktop
/cc shell df -h
/cc shell brew update

Dangerous commands (rm -rf, sudo, mkfs, etc.) are blocked with a warning. To force-execute:

/cc shell ! sudo brew services restart nginx

Check status

/cc status

Shows active sessions, system uptime, disk usage, and any orphaned Claude processes.

Adding New Commands

Adding a subcommand is two steps:

1. Write the handler function

def _handle_ping(args):
    """Check if the bot is alive."""
    return f"pong ({int(time.time())})"

2. Add it to the routing table

SUBCOMMANDS = {
    "start": _handle_start,
    "run": _handle_run,
    "shell": _handle_shell,
    "status": _handle_status,
    "stop": _handle_stop,
    "help": _handle_help,
    "ping": _handle_ping,  # <-- add here
}

Restart Hermes and /cc ping is live.

Safety

• Auth: Hermes enforces TELEGRAM_ALLOWED_USERS at the gateway level — only authorized users can invoke /cc commands
• Shell safety: Dangerous patterns (rm -rf, mkfs, fork bombs, sudo, etc.) are blocked by default with a force-bypass option
• Process isolation: Claude sessions are spawned with start_new_session=True (detached from the gateway process)
• Timeouts: All commands have configurable timeouts to prevent hangs
• No secrets in code: Configuration is via environment variables only

Architecture

Phone (Telegram) --> Hermes Gateway --> /cc plugin --> claude remote-control
                                                          |
                                                          v
Phone (Claude app) <-- claude.ai session URL <-- stdout scan

The plugin registers a /cc slash command with Hermes. When invoked:

1. Hermes dispatches the command directly (no LLM call needed)
2. The plugin routes to the appropriate subcommand handler
3. For /cc start, it spawns claude remote-control --name <name> as a detached subprocess
4. A background thread scans stdout for the session URL
5. The URL is sent back to the user via Telegram

How Remote Control Works

Claude Code's Remote Control feature (claude remote-control) starts a local server that:

• Keeps your machine as the execution environment (nothing moves to the cloud)
• Exposes a session URL accessible from the Claude iOS/Android app or any browser
• Supports full bidirectional control (send prompts, see results, approve tool use)
• Uses TLS over the Anthropic API (no inbound ports needed)

License

MIT