Installation

Installation

Get Caduceus running on your Hermes in about five minutes — or standalone, if that's your thing.

Caduceus is one binary, one Python bridge, one Hermes plugin. There are two ways in: the Hermes plugin path (the one you almost certainly want) and standalone. Both end up running the exact same daemon — the difference is only who does the plumbing.

What you need first

• Hermes Agent — v0.18.2 or newer for the plugin path.
• Rust (1.97 or newer) — only needed to build the binary; setup does this for you on the plugin path.
• Python 3.11+ — for the worker bridge.
• Git with non-interactive credentials configured for the repos you want automated. Caduceus shells out to git; it doesn't reimplement it.
• A fine-grained GitHub PAT — Metadata: read, Contents: read/write, Issues: read/write, Pull requests: read/write.

Path 1: Hermes plugin (recommended)

Five minutes, most of it waiting for the Rust build:

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

What each step does:

• setup — the only command that touches your filesystem beyond the plugin source. It verifies the prerequisites, builds the release binary, installs it, creates the state directories, and seeds your user-owned bridge at ~/.hermes/caduceus/worker-bridge.py. It's idempotent — run it as many times as you like. If the shipped bridge template changed since you installed, it writes a sibling .new file and tells you; it never overwrites your edits.
• cron-install — wires up one named caduceus no-agent cron job that runs the binary every 2 minutes. Idempotent: zero matches creates, one match reuses, multiple matches fails loudly. The Hermes gateway needs to be running for the job to fire.
• status — what the daemon thinks is happening: queue phases, last poll, rate-limit status. doctor does a deeper diagnostic pass and tells you what to fix.

Updating

hermes plugins update caduceus   # refresh the source
hermes caduceus setup            # rebuild the binary

setup is what moves the new binary into place. Plugin source updates never rebuild themselves — that's deliberate; Hermes doesn't run build steps.

Uninstalling

hermes caduceus cron-remove      # removes the cron job and wrapper
hermes plugins remove caduceus   # tears down the plugin

Your state directory, your bridge, your config section, and your watched repositories all survive. Reinstall against the same state and the daemon resumes where it left off.

Path 2: Standalone (no Hermes)

For containerised worker hosts, CI runners, or people who just don't want Hermes. You lose the plugin's skill, the chat status command, and the Hermes cron integration — you keep the daemon, which is the whole product.

git clone https://github.com/barkley-assistant/caduceus
cd caduceus
cargo build --release --locked
install -m 0755 target/release/caduceus ~/.local/bin/caduceus

# write your config at ~/.config/caduceus/config.yaml
# (see Configuration — the worker_command line is mandatory here)

# then cron it yourself; caduceus won't do it for you
# crontab:  */2 * * * *  ~/.local/bin/caduceus run \
#             >> ~/.local/share/caduceus/cron.log 2>&1

One rule that trips people up: a standalone install must set worker_command explicitly. The daemon refuses to start without it. This is on purpose — the Hermes plugin has a default bridge path; you don't, so the daemon makes you say it out loud.

The cron contract (both paths)

The daemon's expectation of whoever schedules it:

• Cron runs caduceus run (a bare caduceus is rewritten to run automatically).
• Success is silent: processed, idle, concurrent, cadence-gated, rate-limited, cancelled — all exit 0 with nothing on stdout. Diagnostics go to stderr.
• Exit 1 means something is genuinely wrong: configuration, corruption, invariant, or unrecovered pipeline failure.
• The whole-tick flock makes it safe to run from multiple schedulers at once (Hermes cron and system cron and a manual run). Only one tick wins the lock; the rest exit 0 with the "concurrent tick" outcome. You cannot double-claim by accident.

Supported hosts

• Linux — tier 1. CI, the release canary, and every documented behaviour run here.
• macOS — works, supported. Same paths, same behaviour. Not exercised in CI before a release; filed regressions are accepted.
• Windows — no. The supervisor depends on POSIX process-tree semantics that Windows job objects don't provide. No roadmap. WSL2 if you must.

If a host isn't listed, it isn't supported.