Bridge Claude Code and Hermes Agent

Connect two AI agents bidirectionally using the Model Context Protocol.

Introduction

30 Second Summary

The best teams don't have one person doing everything. They have specialists who hand tasks to each other based on who does what best. AI agents work the same way.

In this project, you will connect two AI agents so they can call on each other as tools. Claude Code gains messaging capabilities through Hermes Agent, and Hermes gains the ability to delegate coding tasks back to Claude Code.

What You'll Build

A bidirectional MCP bridge between Claude Code and Hermes Agent, where each agent can invoke the other's tools on demand.

By the end of this project, you'll have:

A working Hermes Agent installation on Windows, powered by your existing Claude Pro subscription.
An MCP connection from Claude Code to Hermes, giving Claude Code access to 10 messaging and conversation tools.
A skill-based delegation path from Hermes to Claude Code, enabling Hermes to hand off coding tasks in print mode.
Secret Mission: Orchestrate a multi-file coding task where Hermes plans the work and delegates code generation to Claude Code.

Are there any prerequisites?

You need Claude Code already installed and authenticated with a Claude Pro subscription. You also need a Windows 10 or 11 machine. Everything else (Hermes, Python, Node.js) gets installed during the project.

Install Hermes Agent on Windows

Claude Code handles coding tasks beautifully on its own. But to build a bidirectional bridge, you need a second agent that brings entirely different capabilities to the table.

Hermes Agent is that second agent. It specializes in messaging and conversation management across platforms. In this step, you'll install Hermes on Windows and configure it to use Claude as its AI backbone.

In this step, get ready to:

Install Hermes Agent using the PowerShell one-liner installer.
Configure Hermes with Claude as the AI provider during setup.
Verify the installation is healthy and test a quick chat.

Run the Hermes installer in PowerShell

Press the Windows key to open your search bar.
Type PowerShell and press Enter to open it.
Install Hermes Agent by running this command:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

What does this command do?

irm downloads the installer script from the Hermes website.
iex executes the downloaded script immediately.
The installer bootstraps uv (Python package manager), Python 3.11, Node.js 22, ripgrep, ffmpeg, and a portable Git Bash. No admin rights required.
Everything installs to %LOCALAPPDATA%\hermes\.

The installer takes a few minutes to download dependencies (approximately 45MB). At the end, it automatically launches the hermes setup wizard.

When prompted for a provider, select anthropic.
When prompted for a model, select claude-sonnet-4-6.
When prompted for authentication, complete the browser OAuth flow using your Claude Pro account.

Why anthropic and claude-sonnet-4-6?

Hermes needs an AI model with at least 64,000 tokens of context window to function properly. Your Claude Pro subscription already gives you access to Claude Sonnet 4.6, so Hermes piggybacks on credentials you already have.

Installer failing or hanging?

Make sure your internet connection is stable. The installer needs to download all dependencies before it can continue.
If Windows Defender or your antivirus flags the download, you may need to temporarily allow the script to run.
The Hermes installer is failing on my Windows machine. How can I troubleshoot this?

Open a new terminal and verify the installation

The installer updates your system PATH, but your current terminal session does not pick up the change. You need a fresh PowerShell window.

Close your current PowerShell window completely.
Press the Windows key, type PowerShell, and press Enter to open a fresh session.
Verify your installation is healthy by running this command:

hermes doctor

What should I see?

hermes doctor runs health checks on your Hermes installation and its dependencies. Confirm it reports no critical issues.

If it flags warnings about "early beta" Windows status, that is expected and non-blocking. The core functionality works.

Seeing 'hermes' is not recognized?

You must close your old terminal completely and open a new one. The PATH update only applies to new sessions.
If a new terminal still does not recognize hermes, the installer may not have completed successfully. Run the install command from the previous substep again.
PowerShell does not recognize the hermes command after installation. How do I fix my PATH?

Test Hermes with a quick chat

Hermes is installed and configured. A quick chat confirms the AI provider connection is working end to end.

Start an interactive Hermes session by running:

hermes

Type a message like Hello, what model are you running on? and press Enter.

Hermes responds using Claude Sonnet 4.6. You should see a natural language reply confirming the model it is running on.

Type /exit to end the session.

Hermes not responding or showing errors?

Make sure you selected anthropic as the provider and claude-sonnet-4-6 as the model during setup. You can reconfigure by running hermes model.
If you see authentication errors, re-run hermes setup to complete the OAuth flow again with your Claude Pro account.
Hermes is not responding to my messages or showing provider errors. How do I fix this?

Hermes is installed and talking. Next up, you'll wire Claude Code to call Hermes's messaging tools through an MCP connection.

Wire Claude Code to Call Hermes (Direction 1)

Hermes Agent is installed and chatting with Claude. Now it's time to connect these two agents so they can work together.

In this step, you'll register Hermes as an MCP server inside Claude Code. This gives Claude Code direct access to Hermes's 10 messaging and conversation tools.

In this step, get ready to:

Register Hermes as an MCP server in Claude Code.
Confirm the server appears in Claude Code's configuration.
Test a live tool call from Claude Code to Hermes.

Add Hermes as an MCP server to Claude Code

MCP servers let one tool expose its capabilities to another tool over a standard protocol. By adding Hermes as an MCP server, you give Claude Code access to all of Hermes's messaging tools.

claude mcp add hermes -- hermes mcp serve

What does this command do?

claude mcp add hermes registers a new MCP server named hermes in Claude Code's configuration.
Everything after -- is the command Claude Code will spawn when it needs Hermes tools: hermes mcp serve.
Communication happens over stdio. Claude Code manages the subprocess lifecycle automatically.

Command not recognized?

Make sure you're using a fresh PowerShell window opened after the Hermes installation from Step 1. Old terminals don't pick up PATH changes.
Verify hermes is in your PATH by running hermes doctor in a new terminal.
If claude is not recognized, confirm Claude Code is installed globally with npm list -g @anthropic-ai/claude-code.

help me fix this MCP registration error

Verify the MCP server is registered

Check that Hermes appears in Claude Code's MCP server list by running:

claude mcp list

You should see hermes in the output, pointing to the hermes mcp serve command.

Don't see hermes in the list?

Re-run the claude mcp add command from the previous substep. Make sure you include the double dash -- separator between the server name and the command.
Check that the full command was claude mcp add hermes -- hermes mcp serve with no extra quotes around the command portion.

help me get hermes to show up in claude mcp list

Test Direction 1 from inside Claude Code

The registration tells Claude Code that Hermes tools exist. Now you'll verify the bridge actually works by asking Claude Code to call one of those tools.

Start Claude Code in interactive mode by running:

claude

Ask Claude Code to use the Hermes tools by typing this prompt:

List the available messaging channels via the hermes MCP tools

Claude Code should call the channels_list tool from Hermes and return a response. The response may be empty if you haven't connected any messaging platforms yet. The tool call itself proves the bridge works.

Try a second prompt to verify conversation access:

List my recent Hermes conversations

This calls conversations_list and should show the test chat session from Step 1.

What should I see?

Claude Code will request permission to use the Hermes MCP tools the first time you ask. Approve the tool use when prompted. You should then see Claude Code display results from the Hermes tool call inline in the conversation.

Tool call failing or timing out?

Make sure you approved the tool use when Claude Code asked for permission. MCP tools require explicit approval on first use.
If you see a connection error, exit Claude Code and re-run claude mcp list to confirm the server is still registered.
Try exiting Claude Code and starting a fresh session with claude. The MCP server process is spawned fresh each session.

help me fix this Hermes MCP tool call error in Claude Code

Claude Code can now reach into Hermes's world. Next, you'll complete the bridge by wiring Hermes to delegate coding tasks back to Claude Code.

Wire Hermes to Delegate Tasks to Claude Code (Direction 2)

In the previous step, you gave Claude Code access to Hermes's messaging tools. Now it's time to complete the bridge in the other direction.

Direction 2 lets Hermes delegate coding tasks to Claude Code. Instead of communicating over MCP, Hermes uses a bundled skill that invokes Claude Code in print mode (claude -p). Print mode runs a single task non-interactively and returns the result.

In this step, get ready to:

Confirm the claude-code skill is available in Hermes.
Delegate a coding task from Hermes to Claude Code.
Verify the delegated file exists on disk with the expected content.

Verify the Claude Code skill is available

The claude-code skill is bundled with Hermes by default. It lives at skills/autonomous-ai-agents/claude-code and gives Hermes the ability to spawn Claude Code in print mode for one-shot coding tasks.

Start a Hermes session by running:

hermes

Ask Hermes about its coding capabilities by typing this message:

What coding agent skills do you have available?

Hermes should mention the Claude Code skill among its capabilities.

What is the claude-code skill?

Skills are pre-packaged abilities that Hermes can use without any extra configuration. The claude-code skill wraps Claude Code's print mode (claude -p), which runs a task non-interactively and exits when done.

This is the preferred orchestration mode on Windows. It produces clean, structured output without needing interactive terminal handling.

Hermes doesn't mention Claude Code?

Make sure your Hermes installation completed successfully. Run hermes doctor in a separate terminal to check for issues.

If the skill still doesn't appear, confirm Claude Code itself is accessible by running claude --version in PowerShell. The skill requires Claude Code to be installed and on PATH.

Help me figure out why Hermes can't find the claude-code skill

Delegate a coding task from Hermes to Claude Code

With the skill confirmed, you can now give Hermes a real coding task to pass along to Claude Code.

While still in the Hermes chat session, type this task:

Use Claude Code to create a file called bridge_test.py in my home directory that prints "Bidirectional bridge working!" and includes the current timestamp.

Hermes invokes Claude Code in print mode, which runs the task and returns the result. You should see Hermes report that Claude Code created the file.

What happens behind the scenes?

Hermes takes your request, formulates it as a coding instruction, and passes it to Claude Code via claude -p. Claude Code generates the Python file, writes it to disk, and reports back to Hermes.

The entire exchange happens in a single non-interactive subprocess. Hermes manages the lifecycle from start to finish.

Hermes hangs or times out?

Print mode tasks can take 10-30 seconds depending on complexity. Give it time before assuming failure.

If it errors out, check that claude -p "hello" works on its own in a separate PowerShell window. This confirms Claude Code's authentication is intact.

Help me debug why Hermes can't delegate to Claude Code

Verify the delegated work

The file should now exist on disk. Time to confirm Claude Code actually did the work.

Exit the Hermes session by typing:

/exit

Check that the file exists and inspect its contents by running:

type %USERPROFILE%\bridge_test.py

You should see a Python script that prints "Bidirectional bridge working!" along with the current timestamp.

What should I see?

The file contains a short Python script using datetime or time to generate a timestamp. The exact code varies because Claude Code writes it dynamically, but the output message and timestamp functionality are the key indicators that delegation worked.

File not found?

If the type command says the file doesn't exist, go back into Hermes and try the delegation task again. Watch for error messages in the Hermes output.

Also verify that %USERPROFILE% resolves correctly by running echo %USERPROFILE% to see the full path. Claude Code may have written the file to a slightly different location.

Help me find the file that Claude Code was supposed to create

Secret mission

Orchestrate a Multi-File Task Through the Bridge

In the main project, you delegated a single-file task from Hermes to Claude Code. But real-world coding involves multiple files that depend on each other. Can Hermes plan a multi-file project and coordinate Claude Code to build it correctly?

Clean Up Your Resources

This project runs entirely through your existing Claude Pro subscription, so there are no ongoing cloud costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

Hermes Agent installation at %LOCALAPPDATA%\hermes\
Hermes configuration at %USERPROFILE%\.hermes\
Hermes MCP server registration in Claude Code.
Test file %USERPROFILE%\bridge_test.py
Project directory %USERPROFILE%\bridge_demo\

Keep everything running

No action needed. Choose this if you plan to keep experimenting with the bidirectional bridge or want to add more MCP connections later.

Hermes stays installed and available from any terminal.
The MCP server registration in Claude Code stays active. Claude Code can call Hermes tools in any future session.
Your test files remain on disk for reference.

Pause - I'll come back to this later

Remove the MCP server registration so Claude Code stops spawning Hermes subprocesses, but keep Hermes installed for later.

Remove the Hermes MCP server from Claude Code by running:

claude mcp remove hermes

Verify the server is removed by running:

claude mcp list

Hermes should no longer appear in the output. You can re-add it later with the same command from Step 2.

Delete - I don't want to use this again

Remove all project resources, uninstall Hermes, and clean up the MCP registration.

Remove the Hermes MCP server from Claude Code by running:

claude mcp remove hermes

Delete the test file and project directory by running:

Remove-Item -Force "$env:USERPROFILE\bridge_test.py"
Remove-Item -Recurse -Force "$env:USERPROFILE\bridge_demo"

Uninstall Hermes Agent and remove all its data by running:

hermes uninstall
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"

What does this remove?

The hermes uninstall command removes the scheduled task, Startup shortcut, hermes.cmd shim, and the agent files. It also trims the User PATH.

The two Remove-Item commands wipe your config directory and the entire Hermes install directory, including the portable Python, Node.js, and Git it bundled.

Nice Work!

You just built a bidirectional bridge between two AI agents using the Model Context Protocol. Claude Code and Hermes Agent can now call each other as tools, proving you can orchestrate multi-agent workflows where each agent handles what it does best.

You've learned how to:

Installed Hermes Agent natively on Windows and connected it to your existing Claude Pro subscription as its AI provider.
Connected Claude Code to Hermes via MCP, giving Claude Code access to 10 messaging and conversation tools through a single hermes mcp serve subprocess.
Connected Hermes to Claude Code via the built-in claude-code skill, enabling Hermes to delegate coding tasks using print mode and validated both directions with end-to-end tests.
Secret Mission: Orchestrated a multi-file Python project through the bridge, with Hermes planning the work and Claude Code generating the code.

Ready to quiz yourself?