Home

Caduceus

Caduceus is a Hermes Agent plugin daemon that watches your watched GitHub repositories, claims issues, dispatches workers, and finalises the result — commit, push, pull request, comment — with durable checkpoints at every step. A crash mid-work resumes from the last checkpoint instead of re-running side effects.

The daemon is one Rust binary, one Python bridge, one Hermes plugin. It is small on purpose: the supervisor contract is the design, not a framework.

The one rule

Never edit daemon state, claim files, or transcripts directly. State recovery has its own page — follow it when something is corrupt or wedged:

• State Recovery — corruption, migration, queue reset, lock cleanup

The manual

Pick the page that matches what you're trying to do:

• Installation — install on a new host (Hermes plugin path or standalone)
• Configuration — the full config schema
• The Bridge — write or modify worker-bridge.py
• Architecture — internal design
• Plugin Lifecycle — the Hermes plugin lifecycle
• Hermes Integration — cron, gateway, slash commands
• CI — the GitHub Actions matrix and required-check contract
• Troubleshooting — something broke
• FAQ — common questions
• Public Voice — the public-voice rule

The migration procedure for replacing a prior install is in the repository README. Operators with an outage should not have to navigate a docs tree.

Contributing

Contributor guidance lives in the repository: AGENTS.md, CONTRIBUTING.md, and the README.