Hermes Claude Code RC: Remote Control Claude Code via Telegram

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

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

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

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

# Or manually
hermes gateway restart

How It Works

Architecture

The sources provide this architecture diagram:

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).

Requirements and Limitations

• Requires Hermes Agent with Telegram configured.
• Requires Claude Code CLI installed and authenticated (claude auth login).
• Requires a Claude Pro/Max/Team/Enterprise subscription (required for Remote Control).
• The plugin requires a small patch to hermes_cli/plugins.py to add gateway slash command support. This patch adds register_command() method on PluginContext, _commands dict on PluginManager, and get_plugin_command_handler() module-level function.
• Cloud sessions (iOS app, web, Routines) cannot access your local filesystem, local MCP servers, local databases, or any tools installed on your machine. Only Remote Control provides full local access.
• The plugin is designed for local machine execution; it does not move computation to the cloud.

Troubleshooting

Plugin not responding after installation

If sending /cc help to your Hermes Telegram bot does not return the command listing, verify that the Hermes patch was applied correctly. Check that the plugin directory is present at ~/.hermes/plugins/claude-code-rc and that Hermes was restarted using one of the provided commands:

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

# Or manually
hermes gateway restart

Shell commands blocked

Dangerous commands (rm -rf, sudo, mkfs, fork bombs, etc.) are blocked by default with a warning. To force-execute a blocked command, prefix it with !:

/cc shell ! sudo brew services restart nginx

Session URL not received

If /cc start does not return a URL, check the CC_URL_TIMEOUT environment variable (default 30 seconds). The background thread scans stdout for the session URL; if the session takes longer to start, increase this timeout. Also verify that CC_CLAUDE_PATH points to a valid Claude Code binary and that claude auth login has been run successfully.

Orphaned Claude processes

Use /cc status to check for any orphaned Claude processes. The status command shows active sessions, system uptime, disk usage, and any orphaned Claude processes. You can stop a session by name with /cc stop <name>.

Timeouts

All commands have configurable timeouts to prevent hangs. Adjust CC_SHELL_TIMEOUT (default 30 seconds) for shell commands, CC_RUN_TIMEOUT (default 120 seconds) for headless Claude commands, and CC_URL_TIMEOUT (default 30 seconds) for session URL waiting.

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 (prefix with !).
• 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.