Hermes Claude Code RC: Remote Control Claude Code via Telegram
Remotely control Claude Code sessions from Telegram via the Hermes Agent plugin.
- Author
- kevinmarmstrong
- Stars
- 2
- Language
- Python
- License
- MIT
- Upstream updated
- 2026-04-15
Overview
The Claude Code Remote Control plugin for Hermes Agent enables you to start, manage, and interact with Claude Code sessions from a mobile phone using Telegram. It bridges the gap between local machine access and mobile convenience, giving you full access to your local filesystem, MCP servers, databases, and local tools without needing a terminal nearby.
This plugin is designed for situations where you need to start a Claude Code remote session from a phone without terminal access, execute headless Claude Code commands, run shell commands on a host machine, or manage multiple Claude Code sessions remotely.
Prerequisites
Before installing the plugin, ensure the following are in place:
- Hermes Agent with Telegram configured and running.
- Claude Code CLI installed and authenticated (
claude auth login). - Claude Pro, Max, Team, or Enterprise subscription (required for the Remote Control feature).
Without these prerequisites, the plugin will not function. Cloud sessions from the iOS app, web, or Routines cannot access the local filesystem, MCP servers, databases, or local tools. Remote Control requires a terminal to start, and this plugin automates that step.
Installation
1. Install the Hermes Patch
The plugin requires a small patch to hermes_cli/plugins.py to add the register_command() method. Navigate to the Hermes agent directory and apply the patch:
cd ~/.hermes/hermes-agent
git apply /path/to/hermes-claude-code-rc/hermes-plugin-commands.patch
Alternatively, you can manually add the register_command() method on PluginContext, the _commands dict on PluginManager, and the get_plugin_command_handler() module-level function.
If the patch is not applied, /cc commands will not be recognized by Hermes.
2. Install the Plugin
Copy the plugin directory into the Hermes plugins folder:
cp -r hermes-claude-code-rc ~/.hermes/plugins/claude-code-rc
For development, you can create a symlink instead:
ln -s /path/to/hermes-claude-code-rc ~/.hermes/plugins/claude-code-rc
3. Restart Hermes
On macOS (using launchd), restart the gateway:
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway
Or manually:
hermes gateway restart
4. Verify Installation
Send /cc help to your Hermes Telegram bot. If the command listing appears, the installation is successful.
Configuration
All configuration is done through environment variables only. No secrets are stored in code. Set these in ~/.hermes/.env or your launchd plist.
| Variable | Meaning | Required | Default |
|---|---|---|---|
CC_CLAUDE_PATH | Path to the Claude Code binary | No | claude (on PATH) |
CC_WORK_DIR | Working directory for sessions | No | $HOME |
CC_SHELL_TIMEOUT | Shell command timeout in seconds | No | 30 |
CC_RUN_TIMEOUT | Claude run timeout in seconds | No | 120 |
CC_URL_TIMEOUT | Timeout waiting for session URL in seconds | No | 30 |
If environment variables are not set, defaults are used, which may cause unexpected behavior.
Authorization
Hermes enforces Telegram user authorization at the gateway level using the TELEGRAM_ALLOWED_USERS environment variable. Only authorized users can send commands to the bot. Commands from unauthorized users are ignored.
Capabilities
The plugin provides the following capabilities through Telegram slash commands:
- Start Claude Code remote control sessions via Telegram slash commands.
- Full local filesystem and tool access from mobile devices.
- Headless Claude Code command execution (
claude -p) with results returned. - Shell command execution on the host machine with built-in safety filters.
- Session management including status checks, stopping sessions, and listing orphaned Claude processes.
- System information such as uptime and disk usage.
- Custom subcommand support via handler functions and a routing table.
- Configurable timeouts for shell, run, and URL waiting.
Subcommands
All subcommands are invoked by sending /cc <subcommand> [args] to your Hermes Telegram bot. Use /cc help to list all available subcommands.
/cc start <session_name>
Starts a Claude Code remote control session with the given name and returns a claude.ai/code/... URL.
Example:
/cc start my-feature
/cc run <prompt>
Runs Claude Code headless and returns the result. The prompt is passed directly to claude -p.
Example:
/cc run check if the tests pass in ~/projects/myapp
/cc shell <command>
Executes a shell command on the host machine. Dangerous commands are blocked by default. To force-execute a blocked command, prefix it with !.
Blocked commands include: rm -rf, sudo, mkfs, fork bombs, and similar dangerous operations.
Examples:
/cc shell ls -la ~/Desktop
/cc shell ! sudo brew services restart nginx
/cc status
Shows active sessions, system uptime, disk usage, and any orphaned Claude processes.
/cc stop <session_name>
Stops the running session with the given name.
Example:
/cc stop my-feature
/cc help
Lists all available subcommands.
Custom Subcommands
You can add new subcommands by writing a handler function and adding it to the SUBCOMMANDS dictionary.
To add a custom subcommand:
- Write a handler function with the signature
def _handle_ping(args): return f"pong ({int(time.time())})". - Add it to the
SUBCOMMANDSdictionary:SUBCOMMANDS = { ..., "ping": _handle_ping }. - Restart Hermes.
Example:
/cc ping
Returns pong with the current Unix timestamp.
How It Works
When you send a /cc command, the plugin:
- Receives the command through the Hermes Telegram bot.
- Parses the subcommand and arguments.
- For session commands (
start,stop), it spawns Claude sessions detached from the gateway process usingstart_new_session=True. - For
runcommands, it executes Claude Code headless and waits for the result. - For
shellcommands, it runs the command on the host machine after checking safety filters. - Returns the result to you via Telegram.
Claude sessions are spawned detached from the gateway process, so they continue running even if the Telegram connection is interrupted.
Failure Modes
| Issue | Symptom | Resolution |
|---|---|---|
| Patch not applied | /cc commands not recognized | Apply the Hermes patch |
| Claude Code not installed or authenticated | Session start fails | Install and authenticate Claude Code CLI |
| No Claude subscription | Remote Control feature unavailable | Upgrade subscription |
| Telegram user not authorized | Commands ignored | Add user to TELEGRAM_ALLOWED_USERS |
| Timeout exceeded | Shell or run command returns error | Increase timeout or check command |
Session URL not captured within CC_URL_TIMEOUT | User not notified of URL | Increase CC_URL_TIMEOUT |
| Dangerous command blocked | Command fails | Prefix with ! to force execute |
| Environment variables not set | Defaults used, unexpected behavior | Set variables in .env |
Security Considerations
- Dangerous shell commands are blocked by default. The safety filter catches
rm -rf,sudo,mkfs, fork bombs, and similar commands. To override, prefix the command with!. - Telegram authorization is enforced at the gateway level. Only users listed in
TELEGRAM_ALLOWED_USERScan send commands. - Configuration via environment variables only ensures no secrets are stored in code.
- Claude sessions are detached from the gateway process, preventing the gateway from being blocked by long-running sessions.
Example Workflow
- You are away from your computer and need to start a Claude Code session.
- Open Telegram and send
/cc start my-featureto your Hermes bot. - The bot returns a
claude.ai/code/...URL. - Open the URL on your phone to access the full Claude Code remote control interface with local filesystem, MCP servers, databases, and local tools.
- When done, send
/cc stop my-featureto end the session.
Notes
- The plugin uses
register_command()which requires the Hermes patch. - All commands have configurable timeouts to prevent hangs.
- The system was designed in 2026 and continues to be maintained for compatibility with the latest Hermes Agent and Claude Code versions.
Sources & References
This page was researched from 2 independent sources, combined and verified for completeness.
- 1.kevinmarmstrong/hermes-claude-code-rcBlog · primary source
- 2.kevinmarmstrong/hermes-claude-code-rc READMEOfficial documentation
The #1 AI Newsletter
The most important ai updates, guides, and fixes — one weekly email.
No spam, unsubscribe anytime. Privacy policy