Diaktoros

Bounded, autonomous software maintenance for Hermes.

A Hermes plugin for bounded GitHub pull-request review: an isolated reviewer posts a verdict; an optional fixer answers changes; deterministic Python controls eligibility, capacity, retries and escalation. The loop never merges.

Start here: Getting started · Documentation map · Commands · Troubleshooting

Before you start

Linux with working bubblewrap (bwrap) and unprivileged user namespaces. Native macOS turns are not supported; run Hermes and the plugin inside Linux instead.
Hermes >=0.21.5 (manifest requirement), a Hermes Git checkout and working virtualenv, Python runtime and Rust toolchain for the isolated runtime. A version number alone does not prove sandbox/provider compatibility: run selftest.
Your own HTTPS-reachable Hermes gateway, and a repository whose hooks you can administer.
Separate reviewer and fixer Hermes profiles; three distinct GitHub accounts and token files: reader, reviewer and fixer. An adjudicator comment account is optional and must be distinct too.

Accounts and permissions explains which token each role needs. See the Hermes documentation for Hermes installation, profiles, model authentication and gateway setup.

Install

Replace quoted angle-bracket placeholders before running examples. ID is the installed loop id; N is a PR number. No shared webhook host is provided.

hermes plugins install diaktoros
hermes dk setup --repo "<owner>/<repository>"

hermes dk is short for hermes diaktoros; either works. Diaktoros was called hermes-review-loop before v0.2.0. An existing install upgrades in a few steps; see Upgrading from hermes-review-loop.

The plugin is in the Hermes plugin catalog, so hermes plugins install diaktoros installs the reviewed release at its pinned commit. Desktop can install it from the catalog too. Catalog updates arrive only through a reviewed pin bump.

The install scanner rates the plugin caution. A catalog install accepts that without a prompt, because the catalog reviewed it at admission. Installing from the repository instead (hermes plugins install coe0718/diaktoros) gets the current main, shows the findings and asks Install anyway? Only continue if you trust the source. [y/N]. Typical findings concern subprocess execution (bwrap, Git, workers and test fixtures), security-probe code, and setup advice mentioning privileged commands. A caution verdict is not a security audit.

setup detects runtime paths, previews init, installs the requested wiring, schedules the watchdog and runs doctor plus selftest --no-model. It asks before arming; decline arming until ready. Name a hook admin to create paused hooks. If that answer is blank and hooks are absent, doctor fails and setup prints stopped before arming, exiting 1; that is expected until you create the hooks manually. Re-running setup on an existing loop keeps its saved settings; use set or apply to change them.

The complete onboarding guide includes a reproducible noninteractive setup and a flag-by-flag init alternative. To preview explicit wiring instead of the wizard:

hermes dk init \
  --repo "<owner>/<repository>" \
  --fixer "<fixer-login>" --reviewer "<reviewer-login>" \
  --fixer-profile "<fixer-profile>" --reviewer-profile "<reviewer-profile>" \
  --read-token "<reader-login>" \
  --token "<reader-login>=~/.hermes/keys/<reader-login>-pat" \
  --token "<reviewer-login>=~/.hermes/keys/<reviewer-login>-pat" \
  --token "<fixer-login>=~/.hermes/keys/<fixer-login>-pat" \
  --host "https://<gateway-host>" --dry-run

Option	What it does
`--repo`	Repository to review; the repository component becomes the default loop id
`--fixer`, `--reviewer`	Distinct GitHub logins admitted for the two roles
`--fixer-profile`, `--reviewer-profile`	Existing, distinct Hermes profiles used to run the seats
`--read-token`	Third GitHub login for trusted reads, not the token itself
Repeated `--token`	`LOGIN=PATH` mappings to separate private PAT files; the plugin expands `~`
`--host`	Your gateway origin, without a path
`--dry-run`	Validate and preview without writing; does not prove live token permissions

This minimal preview does not install repository hooks, a watchdog schedule or the runtime file. Use the annotated complete installation before expecting turns to run.

First run, in order

For a loop already installed with paused hooks:

# setup writes $HERMES_HOME/diaktoros-runtime.json; init alone does not.
hermes dk doctor --loop ID
hermes dk selftest --loop ID --no-model
hermes dk selftest --loop ID --pr N
hermes dk selftest --loop ID --pr N --live-turn
hermes dk arm --loop ID

--no-model skips inference, not GitHub reads. The next two selftests spend model quota; the live-turn verdict is printed, not posted. N must be an eligible open, non-draft, same-repository PR targeting the loop's base. arm activates existing matching hooks and sends a GitHub ping to every hook—a GitHub write—using the reader's token unless --admin-token "<admin-login>" is supplied. It exits 1 if a ping is rejected; inspect the output and hook state before continuing. Full checks and their limitations: Verify and arm.

Upgrading from hermes-review-loop

Hermes knows a plugin by its name, and the name changed. Installing Diaktoros puts it in a new folder, diaktoros, beside your hermes-review-loop. It isn't enabled until you enable it under its new name. Your loops keep running through the old plugin until migrate points them at the new one. Between turns:

hermes plugins disable hermes-review-loop        # so the two don't both claim `hermes review-loop`
hermes plugins install diaktoros                 # from the catalog; or: coe0718/diaktoros --force --ref <sha>
hermes plugins enable diaktoros
hermes dk migrate --dry-run                      # what moves: settings, file names, the watchdog job
hermes dk migrate                                # add --rename-loop OLD=NEW --admin-token LOGIN to rename a loop
hermes dk doctor                                 # green? then:
hermes plugins remove hermes-review-loop

hermes review-loop keeps working as an alias that says it was renamed, for one release. Operations has the details.

Safety model

With a valid private diaktoros-runtime.json and hooks activated by arm, an eligible reviewer turn posts a real GitHub review. Gates answer [SILENT] so a normal credential-owning gateway agent does not handle the event. Agents run in bubblewrap without GitHub/model credentials or direct network access; host processes provide bounded inference and broker writes. Unattended fixer pushes stay off until the host operator explicitly runs hermes dk fixer-push --loop ID --enable --acknowledge-pr-race. A Git ref lease cannot atomically enforce GitHub PR metadata: the PR can close or retarget between the final API check and push. Read the security boundary and push policy before opting in. No seat can merge; uncertain writes are not automatically replayed.

Isolation is not immunity: installed plugins are trusted host code, and a kernel/bubblewrap escape would run as the host user. Tests do not establish provider-policy approval or live credentials. Issue triage/fixing and desktop form rendering have offline coverage, not a claimed live acceptance test here. See security and development.

Advanced: Claude subscription seats (DirectSDK)

The experimental claude-subscription-directsdk-experimental provider runs its native client on the trusted host. Seat GitHub/model credentials still stay outside bubblewrap; model requests cross a bounded per-run inference capability. Native authentication defaults to the OS user's login: distinct Hermes profiles alone do not create separate subscriptions. Configure explicit host-side native account directories if different accounts are required. This integration is not provider-policy approval, and offline tests do not prove native prerequisites or a live completion. See configuration and security before selecting it.

Run and extend

Need	Read or run
Understand seats, rounds and handoffs	Concepts
Inspect an installed loop	`hermes dk status --loop ID`
Explain one stuck PR without changing it	`hermes dk explain --loop ID --pr N`
Pause existing hooks	`hermes dk arm --loop ID --pause`
Add issue triage or maintainer-triggered fixes	Issues — opt-in
Receive transition notices without another agent	Observer feed — opt-in
Change defaults, identities or limits	Settings and configuration
Operate, diagnose or contribute	Operations, troubleshooting, development

The watchdog reports stalls, drains eligible queued work and repairs owned routes; it is not an agent. One shared scheduled job sweeps configured loops. A paused loop does not drain or report ordinary stalls; an unreadable GitHub state is reported as unknown, not assumed safe.

License

MIT. See LICENSE.