caduceus@localhostrust / unix / hermes

Your agent thinks.
Caduceus does the paperwork.

A single-host Rust daemon that watches labelled GitHub issues, claims the work, gives your AI harness an isolated place to operate, enforces the boring deterministic rules, then turns the result into the branch, push, pull request and issue lifecycle around it.

View source ↗Operator manual ↗

install.shbash · 80×24

$hermes plugins install barkley-assistant/caduceus --enable

FIG. 01PROCESS SUPERVISOR

OUTBOUND ONLYMIT · v1.0.0

single rust binary∷isolated worktrees∷hard worker timeouts∷zero inbound networking∷harness agnostic∷human-reviewed pull requests

01 / EXECUTION PATH

From issue label
to pull request.

The daemon owns the machinery that should never depend on model vibes: polling, claims, worktrees, process supervision, Git, GitHub, retries and finalisation. The worker gets the code problem and a narrow contract. That's the whole trick.

~/caduceus/run.graph[readonly]

[01]GitHub issuelabel matched

──▶

[02]claimper-issue lease

──▶

[03]worktreeisolated repo state

──▶

[04]your bridgeAI harness

──▶

[05]supervisortimeout + result

──▶

[06]pull requesthuman review

┌───────────────────────────────────────────────────────────────────────────────┐
│ github ── claim ── worktree ── worker-bridge.py ── supervisor ── pull request │
└───────────────────────────────────────────────────────────────────────────────┘

02 / DESIGN DOCTRINE

Opinionated where
surprises hurt.

Caduceus is deliberately not an autonomous software company in a box. It is operator infrastructure around an agent: explicit boundaries, boring failure modes, inspectable state and a human at the merge button.

RULE_01determinism

Keep infrastructure outside the non-deterministic loop.

The daemon owns polling, queueing, claims, Git, GitHub and timeouts. The harness owns the reasoning. Neither side quietly steals the other's job.

RULE_02network

Pull-only by design.

No inbound listener. The daemon polls GitHub outbound and keeps credentials away from the worker environment instead of exposing a webhook-shaped attack surface.

RULE_03ownership

The bridge is yours.

Point it at Codex, Claude Code, pi or your own harness. Plugin updates never overwrite your edited bridge; upstream changes arrive as a sibling candidate instead.

03 / THE BOUNDARY

One narrow seam.
No magic side channel.

Caduceus and your AI harness meet through a sanitised environment contract and one result file. That keeps the worker replaceable and the daemon testable without teaching either half too much about the other.

DAEMON / RUST

Owns certainty.

GitHub polling + ETags
scheduler leadership
claims + parallelism
worktree lifecycle
process supervision
commit / push / PR

sanitised env──────▶CADUCEUS_*

⋮

worker-result.json◀──────bounded result

WORKER / YOUR HARNESS

Owns judgement.

inspect repository
understand the issue
edit the code
run the right checks
explain the result
never needs GitHub creds

04 / PROCESS CONTROL

Agent freedom.
Unix supervision.

Workers are allowed to think for a while. They are not allowed to become immortal. Caduceus wraps each run in the kinds of constraints boring daemons have been using forever, then adds optional OCI isolation when the host boundary is not enough.

Hard timeout

The Rust supervisor owns the worker lifetime and terminates the process tree when the run exceeds its configured boundary.

Isolated worktree

Each claimed issue gets its own Git worktree instead of letting concurrent workers stampede through the same checkout.

Bounded transcript

stdout and stderr are captured into a per-run transcript with an explicit byte cap and truncation marker.

Dry-run first

Exercise the whole path without commit, push, comments, labels, PR creation or issue closure, and inspect the report before trusting it.

executor://trusted-hostDEFAULT

Run directly on the machine.

The simplest mode: isolated Git worktree, sanitised environment and supervised child process on a host you already trust.

executor_mode: trusted_host
worker_parallelism: 1
poll_interval_seconds: 120

executor://ociOPTIONAL

Put the worker in a container.

Docker or Podman execution with an immutable image reference, resource ceilings, explicit network policy and bounded stop/reconcile behaviour.

executor_mode: oci
sandbox:
  engine: docker
  image: worker@sha256:…
  resources:
    cpus: 2.0
    memory_mb: 2048
    pids: 256
  network: none

05 / OPERATOR SURFACE

State you can inspect.
Failure you can recover.

This is daemon software, not a vibes dashboard. Runs leave transcripts. State has supported migration paths. JSON is the default backend, SQLite is optional, writes are validated and atomic, and `status` / `doctor` are meant to tell you when something is actually wrong.

operator sessiontty0

$ hermes caduceus status
status read complete

$ caduceus migrate-state --to-sqlite --dry-run
validate       ok
write          skipped # dry-run

$ hermes caduceus doctor
configuration  check
scheduler      check
worker bridge  check

$ _

06 / OPERATOR, NOT SPECTATOR

        .----------------.
 issue  |    CADUCEUS    |  pull request
------> |  [ automated ] | --------------->  [ HUMAN ]
        '----------------'                      |
                                                +---> merge?

THE LAST STEP IS INTENTIONALLY BORING

Caduceus opens the PR.
A person decides what ships.

It exists to remove operator toil, not the operator. The daemon surfaces the run, the evidence and the failure state; maintainers still own the decision that actually changes production.

Automate the paperwork.
Keep the engineering legible.

Caduceus is open source, MIT licensed, Linux-first and deliberately small enough that the operator can understand the process wrapping their agent.