FAQ

FAQ

Is Caduceus a GitHub App?

No. PAT-only. GitHub App authentication with installation tokens is a future feature.

Does Caduceus replace code review?

No. Every PR it opens is opened for a human to review and merge. There's no auto-merge today, and when policy-gated auto-merge lands it will require a documented policy in plain English first.

Does Caduceus run on Windows?

No. Linux is tier 1; macOS works because the supervisor is portable. Windows lacks the POSIX process-tree semantics the supervisor needs, and there's no roadmap to change that. WSL2 is the answer.

Does Caduceus expose an HTTP API?

No, and it never will. It's pull-only — it polls GitHub on a schedule. If you want push semantics, write a webhook → label-relabel shim in front of it. That shim is your code, not the daemon's.

Can I use Caduceus without Hermes?

Yes — see Installation. You lose the plugin skill, the chat status command, and the Hermes cron integration. The daemon is identical.

Does Caduceus need a database?

It needs a state directory on your disk. JSON files by default; SQLite is a one-command opt-in if you want it (caduceus migrate-state --to-sqlite). Either way it's single-host, local, yours.

Does Caduceus need a hosted backend?

No. One binary on your machine, state on your disk, credentials never leaving your host. Several hosted alternatives exist; Caduceus is not them.

Can I run two Caduceus daemons?

On the same host: yes, against different state directories and different labels. Against the same state directory: technically safe (the whole-tick lock), practically pointless. On different hosts against the same repos: no — both will poll the same issues and one loses every race. Multi-host state is a future feature.

Why is the worker contract Python?

It isn't. The worker is a black box that reads CADUCEUS_* env vars and exits with a code. The reference bridge is Python because Hermes plugins are conventionally Python and it's the lowest-friction harness glue. Write yours in whatever your harness needs — even Bash, for a simple 30-line bridge, though we'd gently suggest not going overboard there.

Why does my comment get rejected for "caduceus" when I didn't write that?

The public-voice rule rejects any outbound comment or PR text containing a forbidden substring (case-insensitive). If the daemon's own name is on the forbidden list, check whether the bridge or harness echoed it into the summary — it's usually a template artefact, not sabotage. The rule exists so the daemon never posts content that embarrasses you; the list is configurable (comment_forbidden_strings), and the FAQ answer is "fix the bridge, don't fight the rule."

Why does caduceus status --json say state_corrupt: true?

The state file failed validation. Do not edit it in place. Follow State Recovery — it's a sequence, not a single command, and skipping steps is how people lose state.

How do I migrate from an earlier Caduceus install?

If your state directory has a JSON state file you want to keep:

caduceus migrate-state --from <path-to-json> --dry-run

Review the dry-run report, then run it without --dry-run. The import is idempotent. The repository README's "Replacing a prior install" section has the full preflight → import → validate → rollback procedure.

How do I switch from JSON state to SQLite?

caduceus migrate-state --to-sqlite --dry-run

Then without --dry-run. It imports the queue, flips state_backend to sqlite in your config, and preserves the JSON files as validated backups.

My worker never seems to get a GitHub token — why?

Because it never will. The daemon deliberately denies GitHub credentials to the worker environment, and that is not configurable. The worker reads the local clone the daemon fetched; if it needs more, the context JSON or the allowlist covers it. This is the security model, not a bug.

Why does the daemon refuse to start when api_base isn't api.github.com?

api_base is a positive allowlist: GitHub.com or a GHES host, nothing else. No http://, no proxies, no shims. It's a security boundary — if you need an internal shim, open an issue so the allowlist can be extended deliberately.

How do I preview Caduceus before letting it touch my repos?

Set dry_run: true (or CADUCEUS_DRY_RUN=1). It does everything except commit, push, comment, change labels, open PRs, and close issues — it writes a .dry-run.md report per run instead. Flip it off and the daemon resumes real work on the next tick. This is the single best way to gain trust in what it's about to do.

How do I contribute?

Open an issue first for anything touching the contract surface, use the conventional commit format with a scope, and pass the canonical gate (fmt, clippy -D warnings, the full test suite). The repo's CONTRIBUTING.md and AGENTS.md are the rules of the house.

How do I report a security issue?

Via the repo's SECURITY.md — not the public issue tracker.