Home

Caduceus

Caduceus is a Hermes Agent plugin that runs the boring half of GitHub issue automation so you don't have to.

Here's the deal: your Hermes agent is great at thinking — at reading an issue, figuring out what's wrong, and writing the fix. What it's not great at is choreography — noticing the issue exists, claiming it before anyone else does, running the worker without letting it hang forever, pushing the branch, opening the PR, and remembering where it was when the machine crashed halfway through.

That's Caduceus. It's the choreographer. Your agent does the thinking; Caduceus does the paperwork.

Concretely, Caduceus:

• Polls your watched repositories for issues wearing the trigger labels (by default 🤖 auto-fix for code tickets, 🤖 auto-fix-investigate for investigations).
• Claims issues one at a time — a single repository never runs two workers at once, and a bounded number run in parallel per tick.
• Runs your worker — your script, with a hard timeout, its stdout/stderr captured, and no GitHub credential in its environment, ever.
• Sees the job through — commit, push, pull request, comment, close-detect. Every step is checkpointed before it happens, so a crash mid-PR resumes from the last checkpoint instead of re-running side effects and double-posting.

It's one Rust binary plus one Python bridge. It is 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.

The one rule

Never edit Caduceus's state files, claim files, or transcripts by hand. Not state.json, not state.db, not the .corrupt markers, not the run logs. The daemon's crash-safety guarantees only hold for the programmatic API — the moment you hand-edit a state file, you're on your own.

If something is corrupt or wedged, there's a recovery path that doesn't involve poking files: State Recovery.

Start here

• Installation — get it running on your Hermes in about five minutes.
• Configuration — the settings that actually matter.
• The Bridge — make the worker yours.
• Troubleshooting — something broke; here's the fix.
• FAQ — the questions everyone asks.

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 data stays yours.