Home

Caduceus

Your agent does the thinking. Caduceus does the paperwork.

Caduceus is a Hermes Agent plugin that runs the boring half of GitHub issue automation so you don't have to. It polls your watched repositories for labeled issues, claims them one at a time, runs your worker against them in an isolated worktree, and sees the job through — commit, push, pull request, comment — with every step checkpointed before it happens. A crash mid-PR resumes from the last checkpoint instead of re-running side effects and double-posting.

One Rust binary, one Python bridge, one Hermes plugin. Small on purpose: the supervisor contract is the design, not a framework. Your worker is a black box that reads a few CADUCEUS_* environment variables and exits with a code — and it never, ever receives a GitHub credential.

Get it running

hermes plugins install barkley-assistant/caduceus --enable
hermes caduceus setup          # builds the binary, seeds your bridge
hermes caduceus cron-install   # a 2-minute no-agent job
hermes caduceus status         # confirm it's alive

That's the whole install. The full story, including the standalone (no-Hermes) path, is on the Installation page.

The one rule

Never edit Caduceus's state files, claim files, or transcripts by hand. The crash-safety guarantees only hold for the programmatic API — the moment you hand-edit a state file, you're on your own. When something is corrupt or wedged, use State Recovery, not a text editor.

Start here

Page	What you get
Installation	Get it running on your Hermes in about five minutes — plus the standalone path, updates, and uninstall.
Configuration	The settings that actually matter, then everything else.
The Bridge	Make the worker yours: the env contract, the result file, the rules.
State Recovery	When things go wrong — the one rule, and the recovery paths that respect it.
Troubleshooting	Symptom → cause → fix, from install problems to hung workers.
FAQ	The questions everyone asks, answered without the hedge.

What Caduceus is not

• Not an agent. It doesn't read issues, plan fixes, or write code. That's your worker's job — Caduceus just makes sure the job runs and lands.
• Not a GitHub Actions replacement. It doesn't build, test, or deploy. It automates the issue → PR loop on the repos you point it at.
• Not a cloud service. It runs on your machine, next to your Hermes, with your token. Your state is on your disk; your credentials never leave your host.