WORKTREEisolated
One issue. One working copy.
Claims and worktrees keep concurrent runs from stepping on the same checkout. The worker gets a focused repository state, not the daemon's entire world.
caduceus@localhostrust / unix / hermes
Review the pull request.
Contain the code.
Caduceus watches your repositories in two directions: it reviews new pull-request revisions in a constrained container, and turns labelled issues into bounded implementation runs and pull requests.
$
hermes plugins install barkley-assistant/caduceus --enable
single rust binary∷read-only PR review∷quarantined fork fetches∷bounded issue implementation∷hard worker timeouts∷harness agnostic∷outbound only
01 / AUTO REVIEW
Every new revision.
One contained review.
Auto Review polls watched repositories, freezes each new head SHA, and gives the worker an OCI review workspace with a read-only root filesystem. It publishes a structured PASS or FAIL result to the pull request, then does it again when the code changes.
~/caduceus/review.graph[read-only]
[01]pull requestnew head SHA
──▶[02]admissionpolicy checked
──▶[03]quarantineforks, if opted in
──▶[04]OCI workerread-only review
──▶[05]verdictPASS or FAIL
──▶[06]PR commentfindings published
02 / AUTO FIX
Label the issue.
Bound the implementation.
Auto Fix is the other half of Caduceus. A label starts a run in its own worktree; the daemon supervises the worker, then owns the predictable Git and GitHub work around the resulting branch and pull request.
BRIDGEoperator owned
The model choice is still yours.
Point the bridge at Codex, Claude Code, pi, or your own harness. Caduceus supplies the contract and supervision, not a hidden model layer.
FINALISEdeterministic
Keep the paperwork deterministic.
The daemon handles timeouts, retries, commits, pushes and pull-request lifecycle. The worker reasons about the code. Those jobs stay separate on purpose.
03 / THE BOUNDARY
The daemon has the keys.
The worker has a job.
Both modes use a narrow worker contract. Caduceus owns GitHub access, state and finalisation. The worker receives only what it needs to review a revision or work on a labelled issue.
Owns the boundary.
- GitHub polling + ETags
- scheduler + parallelism
- claims + worktree lifecycle
- OCI readiness + isolation
- process supervision
- Git + pull-request finalisation
sanitised env──────▶
CADUCEUS_*⋮
worker-result.json◀──────validated resultOwns the judgement.
- inspect the revision or issue
- understand the code
- review or implement
- run the relevant checks
- explain the result
- never receives GitHub credentials
04 / OCI CONTAINMENT
Review untrusted code.
Keep it contained.
Auto Review requires OCI execution. Before a pull request reaches the worker, Caduceus checks the engine and the digest-pinned image, then starts a container with a fixed, deliberately narrow runtime posture.
Read-only rootfs
The review worker cannot write outside the declared workspace and output surfaces. A modified review checkout is treated as a violation, not a successful review.
Nothing listening
With the default network: none policy, review containers have no network. They never receive a runtime socket, host namespaces, devices, or the daemon's GitHub credentials.
Bounded by design
CPU, memory, process count, temporary storage and worker lifetime are capped. The supervisor owns cancellation and cleanup if a run goes wrong.
Forks need consent
External-contributor pull requests are off by default. Opted-in repositories use a disposable, SHA-anchored quarantine clone before the review worktree exists.
review://fork-quarantineOPT-IN
Fetch the fork.
Not into your mirror.
For a repository you explicitly allow, Caduceus clones from the trusted base, fetches the contributor's SHA into a disposable quarantine, and removes it when the review is done.
auto_review:
enabled: true
fork_policy:
allow_fork_prs:
- owner/repoexecutor://ociREQUIRED FOR REVIEW
Review inside
the container.
Auto Review refuses the trusted-host executor. Docker or Podman must be ready, and the worker image must be pinned by digest before a review is admitted.
executor_mode: oci
sandbox:
image: registry.example.com/caduceus-worker@sha256:<64-hex-digest>
network: none
auto_review:
enabled: true05 / OPERATOR SURFACE
See the review.
See the failure.
Auto Review records each repository, pull request and head SHA as a separate piece of work. The same daemon also keeps transcripts, queue state and recovery data for Auto Fix. It is software you inspect with commands, not a dashboard that hides the difficult part.
operator sessiontty0
$ caduceus review status owner/repo
$ caduceus review list --json
$ caduceus review show owner/repo 184
$ caduceus doctor --json
$ caduceus status --json
$ _06 / OPERATOR, NOT SPECTATOR
EVIDENCE, NOT A BLACK BOXCaduceus reports
Caduceus reports
what it found.
For review, that means a clear verdict and findings on the pull request. For Auto Fix, it means an implementation run with a visible branch and lifecycle. Maintainers still decide what belongs in their repository.
// case studyThe thinking
The thinking
behind Caduceus.
Why it exists
I wanted coding agents reviewing pull requests and picking up issues without handing them the keys to my GitHub account or my machine. Most of the tooling I tried let the model do everything, including the parts that really shouldn't be left to something non-deterministic: pushing branches, managing state and deciding when a run has gone on long enough.
Decisions and tradeoffs
- 01The daemon owns the boring parts
Polling, claims, worktrees, timeouts, commits and pull requests all live in Rust. The worker gets a narrow contract and a result file, and it never sees GitHub credentials.
- 02Review only runs in a container
Auto Review refuses the trusted-host executor. Docker or Podman has to be ready, the image has to be pinned by digest, and the default network policy is none.
- 03Bring your own harness
The worker bridge can point at Codex, Claude Code, pi or anything else. I care about the boundary around the model far more than which model sits inside it.
- 04Forks are opt-in
External pull requests are off by default. When a repository allows them, the contributor SHA is fetched into a disposable quarantine clone rather than the trusted mirror.
Two ways to automate.
One process you can read.
Caduceus is open source, MIT licensed and Linux-first. It keeps PR review contained and issue implementation bounded without hiding the machinery from the operator.