Reference

Complete reference documentation for configuration and CLI commands.

See Touched test worker sizing for automatic case-count limits, CI configuration, collection failures and startup evidence.

See Focused proof CPU worker limits for focused test dispatch, automatic CPU quota and affinity caps, configuration and diagnostics.

See Cancelled watcher after the gate change for the dated stale group diagnosis, historical and current gate rules, read only evidence commands and configuration ownership.

Pages in this section

Page What it covers
Swarm elapsed thresholds Idle and input timing, retirement, dispatch and autoscale windows, cadence examples, legacy settings, holds and ledger probe limits
Semgrep feature tests One dated rule per operator ordered feature, regression and passing fixtures, and required CI proofs
Feature map Feature map origins and keys, the test marker, live check targets and the pull request validation
Feature live checks The feature map, how the Doctor runs each live check on its timer, the feature regressed finding with the operator’s words, the front door login check, measuring and troubleshooting
Local test guard Source and symbol inspection, prose mentioning runners, execution refusals, configuration and troubleshooting
Process environment reads Credential guard refusals of process environment files under /proc, commands that still pass, leak free alternatives, configuration and troubleshooting
Host process guard Which piled up processes the workstation guard ends, the agent session wrapper and tick exclusions, configuration, install and drift check, log lines and troubleshooting several agent sessions ending together
Configuration All environment variables across every integration, in one place
Deployed swarm host capacity Worker namespace quota and pool budgets, autoscale inspection, configuration and disabled host pressure alerts
Git maintenance and object counts Register managed primary checkouts, repair missing registrations, configure discovery, read loose object and pack counts and diagnose failures
Tool dependency synchronization Update the editable source checkout and its running tool environment, check missing requirements and recover failed installs
CLI Commands All agentihooks subcommands and flags: init, uninstall, claude, ignore
Developer account login Claude and Codex login, managed shell tokens, OpenBao paths and key names, refresh authority and token stores
Scheduled tick delivery guard When the systemd tick timer is retired or restored, the delivery record and its reasons, the wait pass supervisor guard, why the supervisor a wait pass starts outlives the pass, supervisors started off the installed code that exit with their starter, the Doctor scheduled tick finding, inspection commands and troubleshooting
Task scope authorizations Record master or operator scope, retrace a plan, interpret authorized pieces and configure enforcement
Follow ups on a task How followup add records the session’s task, routing to the task’s owning master, the schema and domain checks with their refusals, an inspection command and troubleshooting
Master inbox intent grouping Settings, how a pooled item is matched to a master, token cost per item, fallbacks to round robin, Redis keys and troubleshooting
Task notices when a seat changes tasks Automatic routing to task comments, relocation of indexed seat notices, successor and master fallback rules, inspection commands and troubleshooting
Filters Condition files that catch unrequested text: filename grammar, schema and defaults, finders and _finders, synthetic tools, actions, the round cap, fail open, the answer cache and condition_set with language="filter", with the capacity line as the worked example
Decision classifier hooks.classifier: typed questions to the LiteLLM decision models, failover, down cache, decision log, classify and classifier stats
Tick adapters The empty registry integration, its group order, context, completion limits and equivalence evidence; Deadlines on every tick tool call with the test that walks every adapter method for its deadline.live() check, the ClientLedger and StoreCoordination adapters with the controller epoch on ledger writes, the provider neutral source control records and the GitHubSourceControl adapter, the swarm commands that reach GitHub through it, the Semgrep gate and its shrink only exception list for gh commands, the StoreInbox, ApiLlm, SpoolMetrics, JobHost, RouterRuntime and PassProcesses adapters with local_host, the one process scan each tick pass shares with the reaper, the one live names listing each tick pass shares between its fenced runtimes and drops after a spawn, collect, expire, retire, reap, close or resume, the one placement scan each placement pass shares between its launch threads with the fenced spawn’s timed rows, the timed rows inside spawn order for the running agent filter and focus budget placement, the lease heartbeat each tick pass holds, declared effects through Tools.for_effects with effects in a tick pass, declaring and testing a step’s effects and finding a refused write, the fakes for tests, the test that keeps tick steps off the adapted modules and troubleshooting
Tick ledger view The stored view of each swarm ledger’s tasks, metadata and phases that a tick pass patches from one export read of the changes since its generation, its file under the scheduler runtime folder, the full read fallbacks, the export parts field and its change window, how steps read the ledger through pass_state, one ledger read per pass plus at most one per write with the phase pass projected from the pass document, the shrink only gate on whole ledger state reads, checking the stored views and troubleshooting
Observability with Langfuse Every telemetry path and where it goes, turning Langfuse on per profile, other OTLP backends, checking a trace arrived, traces in another project and the keys app-server Codex launches pin, how the Doctor reads traces through the internal ingress, host configuration and connection checks, its read budget and read failure lines, the wait history budget and its live agents first order, how a hive agent’s start is resolved, what to check when Langfuse and the swarm Redis time out together, and how trace coverage is judged
Tick engine steps The shared helpers in scripts.tick.steps.common re-exported by the tick module and patched through it; measured step budgets and declared intervals, interval enforcement and the steps that rest inside their interval, late worker behavior, the writes and cache saves a late step drops, and overlap limits, the swarm_tick_step_abandoned journal line naming the writes an abandoned step dropped, the critical, slow and closing lanes, the closing group that stamps last tick and the heartbeat and publishes the tick status from the pass finally on every ending, which steps run slow (the report steps, fleet red notice, lost runner, time left) and how a parallel pass hands them off, including the steps of a later group that wait on a handed off step, the status publish reusing the health findings the pass already found, the conditional forty second spawn bound, the tick engine registry and group run, the flat pass graph the tick runs its pass as, with its site edges, joins, site gates and hooks, CallStep and the pass state, the order of the tick group sites, the task passes, placement and close steps with their conditions, the spawn-due marker, steps that return guarded writes the engine applies with compare and set and the dropped write recomputed next pass, how a held exception still leaves the pass at its site, adding a step, the feature and scenario catalogue check with its scenario index and shrink only unmapped list, the tests and troubleshooting
Tick step catalogue Every registered tick step by group and name with its lane, budget floor, interval, needs, effects and feature, rendered from the registry by python -m scripts.tick.catalogue render and held to the registry by a docs test
Tick pattern gate python -m scripts.tick_pattern: the tick module definitions, step budget rows and intervals, the six declared step fields and the banned adapted imports it records, the shrink only tests/TICK_PATTERN_ALLOWLIST.json, grading only the files a pull request touches against the base allowlist and measurement, the CI step and protected grader, the second run in the tick equivalence workflow and the inputs that select it, threshold pins, adding a step that passes, removing offences and troubleshooting
Tick step skill and rule The tick-step skill and the tick pattern rule every role persona carries, python -m scripts.tick.new_step with its options, the five artefacts it writes, its refusals and --check, filling the body against its declared ports, the local pattern, catalogue and feature map checks, the run ids a move cites, the master’s tick task spec, the tests that hold the skill and rule, and troubleshooting
Tick step scaffold python -m scripts.tick.new_step: the step stub, budget row, feature test, scenario index row and feature map entry it writes, scripts.tick.steps.MODULES, every option with an example, --check, refusals, limits, tests and troubleshooting
Fleet red notice When the swarm holds an open task whose pull request is red only from checks failing on most other open pull requests, the claim filter and the notice the tick posts each pass, the open pull request listing in pages of twenty five up to two hundred, the ten minute per swarm and repository listing cache that keeps a failed listing too and that the tick claim filter reads before it lists live, the notice step’s measured thirty second budget that keeps its listing save, the notice step on the slow lane with preempt and spawn waiting on it, usage, configuration, limits, tests and troubleshooting
Fencing records Per record fencing keys for a migrated swarm, the records port and its Redis and whole document adapters, the Lua fenced batch with its lease and revision checks, the capped fence log stream, how a fenced write becomes a batch, the one time migration command and the dual read window, inspection commands, the measured bytes per change, limitations, tests and troubleshooting
Tick report swarm <id> tick-report: its output lines, the per lane CPU share and the forty percent critical lane threshold, the late, abandoned, held, skipped and dropped write columns with the critical lane end, the tick:passes, tick:steps and tick:records records it reads, the step budgets, pass budget hold and load budget built on the same records, the scale proof at six, ten and fifteen agents with its stage table and what the scale proof task delivered, and troubleshooting
Tick load budget The simulated tick pass over fifteen agents and nine hundred tasks on a virtual clock, its ledger, runtime and Redis latencies, the 384 second pass budget that may only shrink against origin/dev, the 300 second slowdown test, lowering the budget, the swarm-tick-pass-budget feature map entry with its tick report live check, limits and troubleshooting
Quota prober The tick pass reading quota from the caches only, the agentihooks-quota-prober service probing every account once a minute through capacity.probe, the stale reading line the quota notice step adds after three minutes, checking the prober, limits, tests and troubleshooting
Presentation layer architecture The ledger pages, HOME and BIN as a product: constraints, today’s architecture, limits, target (static pages, /api/v1, server-sent events, SQLite behind a repository) and the migration order
Ledger server watch loop Automatic scheduler failure fallback, lock location, configuration, container log inspection and CI proof
Ledger slow notice When the ledger slow alert raises and clears, its wording and recipients, how the newest dev merge is aged from the pull request merge time with the origin dev reflog fallback, inspection commands, troubleshooting and CI proof
Ledger watcher replay verification Heartbeat frames, replay assertions, test configuration and first-attempt CI evidence
Inbox reconnect alarm and the mcp SDK Why the reconnect alarm broke mcp.server.stdio for a whole worker, the mcp_sdk preload contract, the alarm probe tests, CI verification and troubleshooting
Ledger design with Impeccable live Start an Impeccable live session against a scratch ledger server; the rules that keep it away from the shared server
Headless profile runs agentihooks headless run: one full profile run unattended on Claude or Codex with flags, examples, the JSON report and exit codes, the run folder and transcript, model tiers, worker mode, limitations and troubleshooting
Headless clamps Exact Claude Code and codex-cli flags for sealed and read only headless runs, the canaries that prove them, hooks in each clamp and the Codex shell and sandbox residuals
Grafana bottleneck alerts How the swarm tick reads bottleneck alert state from Grafana through the gateway, its two settings, the alert label contract, upgrading from the removed push intake, verification and troubleshooting
Spawn holds in the stage report Who a held spawn sample names (host, hive placement or a lane pin), how a hold is charged to at most its held spawn count of waiting tasks, when the bottleneck remedy moves a pinned lane back to Claude, inspection commands, measured effect and troubleshooting
Redis command map and grant check python -m scripts.swarm.redis_commands: the Redis commands and scheduler keys each swarm consumer reaches, how they are read from code, and the antoncore Swarm Redis privileges job that refuses a Redis user missing one; refusal lines, configuration, limits and troubleshooting
Swarm scoped bus credentials Member NATS credentials limited to their own swarms: the member_swarms signer field, AGENTIHOOKS_BUS_SCOPED, per swarm stream and subject names, the JetStream grants, the two shared slot buckets, existing swarms through the subject change, migrating retained state, queue and dead letter work, a refusal check, the retired shared hive user, the antoncore grant check and troubleshooting
Deployment modes AGENTIHOOKS_DEPLOYMENT: the local, compose and distributed modes, where the controller, ledger and Redis run, and the regulated site recipe
Hives Joining machines, settings, repos and checkouts, placement and master placement, launches on a hive and their refusal causes, failover timing, fencing and worker hive pods
Shared ledger database sessions The writer lock on the shared Postgres ledger database, the lock wait, idle transaction and statement limits and TCP keepalives every connection sends, the three-wait retry and its refusal, inspecting holders, measuring stuck holders, the writer floor that refuses ledger servers on old code and its writer alert, the Writer lock CI scenario and troubleshooting
Swarm LAN services MetalLB and k3s service ownership, the LAN connection reset incident, server configuration and activation, read only diagnostics, counted errors and evidence limits
Hosted ledger auth SWARM_AUTH_MODE: local page tokens, or edge with the Cloudflare Access operator and agent tokens from SWARM_SECRET; configuration, usage and troubleshooting
Pull request mutation gate Individual tests for statistics, line contexts in the dependency manifest, paired selection proof, whole file fallbacks and measured selection limits, Covering tests through production helpers, unreadable coverage record retry and every test fallback, graded lines and bases, continuation preflight runs, statistics and shard worker sizing from the runner CPU quota, shard planning from the batch runner CPU quota, single shard plans in the statistics job, planning input reuse with configuration, inspection and paired timing evidence, plan job dependencies, suite speed contracts in the branch preflight, push preflight reuse, planned test selection and older heads, forwarded reports, measured shard costs, pricing from recorded killing tests, test durations adjusted for statistics contention, split mutants, combined grades, CI proof examples, evidence inspection, survivor clearances, clean baseline failures that name each failing test, and planner tests that check behaviour with their measured failure counts
Stop gates and a declared wait Which pull request the claim-stop gate grades under a checks wait on another pull request or an Actions run, the merge wait that lets the push-stop gate pass, refusal texts, the gate log query and troubleshooting
One push per pull request The one-push gate: opening a pull request only after both reviewers ran and the work is on origin, refused pushes while checks run or the pull request is queued, the red check exception, gate modes, lifts and troubleshooting
Delivery tiers The three CI tiers (pull request, queue, promotion), why a red integration branch keeps merging, promotion owning the slow checks, fixer tasks for a red promotion, which pull requests run the suite speed checks, queueing a green head without merging dev first, sizing merge group unit shards to the queue runner pool, Python 3.12 timing research and its twelve shard floor ruling, how concurrent merge groups share that pool and lengthen the queue tier, the early required queue verifier and the shared runner loss reader that it and the rerun classifier call, the historical cancelled watcher diagnosis, stalled run recovery timestamps and measurements, the queue journal that records each swarm merge queue mutation, where coverage is graded and clearing a line the coverage ratchet reports lost
Step timeout limits The queue shard planner and the shard budget reading their limits from the Run tests and Run the selected tests step timeouts, the elapsed time records both test steps write, running the budget by hand on a selected leg, the tests that pin the limits, troubleshooting and delivery evidence
Grouped test files in the unit shard planner One xdist_group file placed whole on one unit shard with its summed time charged to the shard’s group load, the even shard share cap, collection order inside the group, where unmeasured tests go, a placement check command, troubleshooting and delivery evidence
Merge queue churn measurement One day of cancelled dev merge group runs split into ejections of the entry and rebuilds caused by another entry, their runner and wall minutes, rebuilds per merged pull request, why entries were queued again at an unchanged head, the fixes it led to and the gh commands to repeat it
Stored duration coverage The dev push refresh and the split job pricing every collected test without a stored duration at the median of its map, the one in ten coverage check, the measured unknown duration share and unit shard spread before and after over ten dev push runs, a script that measures a window, troubleshooting and delivery evidence
Sonar skip on test only pull requests The select output that skips Sonar when only tests/ changed, the required gate form, run checks, troubleshooting and delivery evidence
Sonar shard coverage merge Distinct-arc merging, preserved test contexts and coverage inputs, workflow configuration, CI inspection, startup measurements and troubleshooting
Resource sampling and stop condition checks Whole tree resource warning ownership, condition timing budgets, fixture configuration, focused CI proof commands and failure diagnostics
Protected provenance checkout The select job’s protected base checkout, its 60 second low speed bound and the actions/checkout fetch retry inside the five minute job timeout, the unit test, gate and probe that guard it, proof runs, a run check command and troubleshooting
Mutation preflight legs on the batch pool Per run concurrency groups for the stats and shard legs, the anton-oss-batch ceiling, per branch cancellation, checking shard pickup, measured waits and troubleshooting
Confirmed runner waits Stale snapshot rereads, confirmed pickup, unconfirmed queue age, one finding per wait, retractions, concurrency limits, inspection, configuration and delivery evidence
Doctor verdict history The per Doctor verdict event log beside the latest finding record, its Redis keys and seven day retention, doctor <slug> verdict-log with its JSON report for counting a day’s false positives, inspection commands, limitations and troubleshooting
Doctor CI speed reads Completed jobs retained between incomplete passes, same attempt reuse, reader budgets, long gaps read in ten minute slices, settle reads for lagging active run counts, which runs count toward tier wall time, the wall time order and the tests that cover each step, run and class window measurement, journal examples, failure diagnosis and delivery proof
One CI speed finding id across windows Runner wait, queue age and tier wall time ids that carry only the label set or tier, verdicts on older window ids covering the stable ids, settled and open members, measuring stable and window prefixed ids, refusals and notice counts over six hours before and after
Branch workflow lanes compatibility Current and exact legacy mutation group examples, trusted workflow and runner requirements, refusal of jobs without lanes and CI diagnosis
Standing CI budget report One CI overrun finding, per-stage counts and worst times, openable run links, retention, configuration and watched swarm isolation
OCI runner migration measurements Named UTC cohorts, gate and image timings, hourly pickup wait, cordons, infrastructure loss, CPU requests and evidence limits
Registry lookups lost to a node address conflict Why k8s-worker-1 failed lookup ghcr.io on 20 October 2026, the router lease timeline, the antoncore LAN address plan, the router_lan.py drift check, the lan-ip-conflict alert, read only checks and troubleshooting
Ledger load gate The Ledger server load workflow and its ledger-load job: ninety seconds of writes and reads on a full size scratch ledger, write latency and CPU budgets, the server thread and memory growth check, limits graded from the base, manual dispatch and failure diagnosis
Hierarchy CPU proof at promotion Automatic dev push proof, release prerequisite, runner isolation, pending run replacement, base selection, dispatch examples, inspection and delivery evidence limits
Hierarchy CPU Redis acquisition Delivered public ECR service image repair, unchanged pull retries, current runner Redis setup, CI dispatch, readiness checks and acquisition proof limits
Swarm smoke Redis acquisition Public ECR Redis pulls with the existing bounded retries, mirror name tags for the scenarios, skipped steps after a failed pull, CI dispatch, contract tests and troubleshooting
Hierarchy paired load false reds Why the paired load comparison went red on a workflow only head, the runs that excluded node noise and a dev regression, the current pair matrix, ratio and margins, why write p50 replaced write p95, the same code record and its bound, every paired red, the measured result, the ledger load compare mode with its five pair matrix, 1.4 margin, same code record, evidence and troubleshooting, a same code control and troubleshooting
Hierarchy CPU grading The halving assertion that failed on identical code and why it was replaced rather than retired, the base resolution, four alternating pairs from an aligned start, the geometric mean ratio and margin, the same code record and its tests, every hierarchy red, regrading and recording runs, delivery evidence for pull request 5129 and troubleshooting
Ledger request metrics The request metrics command and /api/v1/metrics: per write wall, CPU and lock wait records grouped by route for a fixed window, the summary view, coverage and lost spans, the journal that keeps timings across a reload or restart, limits and troubleshooting
Publish fallback gate The swarm publish gate for repositories without their own scripts.ci_prepush: lint and format on changed lines, size and complexity on functions whose logic changed, the shrink only tests/SIZE_ALLOWLIST.json read from the merge base, ignored # noqa, and the messages it prints with how to fix each
Pre push gate python -m scripts.ci_prepush: lint, format and the size grader on HEAD, the allowlist and grader read at the merge base so untouched units never fail a push, where CI still refuses growth against current dev, the --base flag and troubleshooting
Test count floor The test-count job: the base revision grades, trusted dev suite records, exact base matching, collection fallback, collection across processes, configuration, diagnostics, lost test admission and proof
Promotion and releases How a green dev push run of Tests rebase merges its graded revision into main through a snapshot branch, tags a patch release with generated notes, what blocks it, reruns and manual release.yml runs
Promotion controller without git Automatic repository identity fallback, shared checkout configuration, missing git crash diagnosis and the successful helm kind recovery proof
CI result cache and in place retry The design for one CI algorithm: reuse a check’s green result while its real inputs are unchanged, retry a failed test in place, retry durations downloads and uploads in place, before numbers and slices
Helm kind proof input keys Declared chart and image inputs, due decisions, dispatch examples, cache misses and proof measurements
Old file fetch in the remap The one batch fetch of changed files’ old text in a partial clone, before and after times, the proof, reading the remap step time and troubleshooting
Unusable coverage databases The coverage database check before reuse and before upload, its errors, a manual check and troubleshooting
A crashed xdist worker and coverage data Why a replacement worker used to delete the live workers’ coverage files, the tests.browser_coverage fix, where it loads, the crash probe test, before and after runs and troubleshooting
Shard summary The ran, reused and flaky counts each shard-check leg prints, the line naming a shard that fell back, reading it on a run and troubleshooting
Helm kind registration to readiness Preserved recovery checks, parallel work, kind probe settings, CI dispatch and measured intervals
Codex CLI cache in unit jobs Seed the CLI on main, configure its release, diagnose cache misses and verify installation and shard timings
Worker hive pod image build Reuse of the published worker base, the base inputs and rebuild decisions, build output, measurements and troubleshooting
Parallel launches in one process The per swarm lock on execution history writes, the five watched attempts and their errors, writers in another process, reading a failed spawn line and the tests
Current execution reads Hive routing and roster reads of current executions without the archive, the published copy and its Redis keys, the older writer fallback, checking the copy, measuring tick passes and the tests
Execution reads through the records port Each ExecutionRegistry read on the records and document layouts, and when the published copy serves it
Hive placement reads The hosts projection hash, its cleanup after a failed projection write, the default on SWARM_HOST_PROJECTION_ENABLED read and its off values, the rollout order, checking a host field, measuring scope.readings, tests and troubleshooting
Retries after a fencing conflict The 1 to 32 millisecond jittered sleep between the 16 fenced write attempts on both layouts
Refused worker startup diagnostics Startup log and exit reason kept before a refused worker Pod is removed, the bounded cleanup log retry, pods/log permission, reading the records and troubleshooting
Worker profile proof Offline Codex SessionStart replay, first registry write timing, surviving hook child failures, the session start dependency check, fixed limits and CI evidence
Browser cache Verified Chromium preparation, dev push only saving, restore scope, workflow configuration and cache inspection
Task browser The playwright-cmd proxy: which lane homes mount it, start on first tool call, the shared tool list cache, measured memory effect and troubleshooting
WSL disk reclaim Sparse VHDX so space agentihooks gc frees returns to Windows; why /tmp empties on WSL
CODEX-COMPAT The codex install target: hook contract, shell working folder, surface map, divergences
Profile launch home How init-agent --profile renders one home, records it and mounts it through select-profile --home; home checks, refusals, the canary deadline per harness, limits and troubleshooting
Managed Codex terminals Installed runtime dependencies, connection verification, transport selection, detached server hook identity and no hook event diagnosis, herdr viewer reopening, push master inbox duties, the launch waits inside the spawn timeout, handoffs, retirement closing viewers and removing the runtime home, the lifecycle sweep reclaiming orphan execution homes, and attachment failures
Codex inbox transport The app_server default, the Claude inbox channel against broadcast topics and Bun plugins, qualified versions, canary order, failure diagnosis and rollback

Table of contents