anti-hall
llms.txt2 starsChanged 46 days agoMITView on GitHub
A Claude Code marketplace plugin plus a Codex-native port that makes coding agents verify before they claim. It injects a verify-first protocol at session start (re-injected after compaction and into every subagent), a short per-turn nudge, and mechanical guards that cannot be argued with: no AI commit self-credit, no silent force-push, coordinator command/edit delegation, anti-fork-bomb, anti-speculation (lexical, claim-ledger, opt-in LLM judge), task-list discipline, and a TTL'd user-override escape hatch (~/.anti-hall/skip.json). Optional parts: a two-line statusline, an MCP-orphan reaper, the Jev…
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- dogfoodSkill
- engine-debugSkill
- engine-laneSkill
- gh-workSkill
- releaseSkill
- repo-hygieneSkill
The file
We split this llms.txt into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
Verify: ask Claude "is anti-hall working" (the doctor skill), or run ~/.anti-hall/ah-engine/bin/ah-engine doctor --check from a clone.
- Very specific: line 39
Update with /anti-hall:update (Claude) or the anti-hall-update skill (Codex), then /reload-plugins (Claude Code.
- Very specific: line 75
All fail-open. "Codex" = also registered by the Codex port (codex/hooks/hooks.json).
≈ “Common” is an estimate: at least 1 in 5 of the 3,806 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
# anti-hall
> A Claude Code marketplace plugin plus a Codex-native port that makes coding agents verify
> before they claim. It injects a verify-first protocol at session start (re-injected after
> compaction and into every subagent), a short per-turn nudge, and mechanical guards that
> cannot be argued with: no AI commit self-credit, no silent force-push, coordinator
> command/edit delegation, anti-fork-bomb, anti-speculation (lexical, claim-ledger, opt-in
> LLM judge), task-list discipline, and a TTL'd user-override escape hatch
> (`~/.anti-hall/skip.json`). Optional parts: a two-line statusline, an MCP-orphan reaper,
> the Jev classifier, and DevSwarm multi-workspace coordination (dormant unless DevSwarm is
> in use). The core is a Rust engine (`ah-engine`, downloaded once, sha256-pinned), macOS + Linux. No Node.js is needed (the engine is the only runtime). Windows is not supported yet.
anti-hall targets four failure modes of coding agents: eagerness (acting before
investigating), hallucination (unverified facts stated as truth), fix-before-diagnosis, and
fake completion (claiming done without running the check). The always-on protocol text
itself (Iron Law, rationalization table, positive rules, orchestration rules) is mirrored
in [AGENTS.md](https://github.com/talas9/anti-hall/blob/main/AGENTS.md). This file is the condensed catalog of every component; history
is in [CHANGELOG.md](https://github.com/talas9/anti-hall/blob/main/CHANGELOG.md).
## Install
Prerequisite: Node.js >= 22 on PATH (hooks silently no-op without it; Windows is not supported).
```
/plugin marketplace add talas9/anti-hall
/plugin install anti-hall@anti-hall
```
Verify: ask Claude "is anti-hall working" (the `doctor` skill), or run `~/.anti-hall/ah-engine/bin/ah-engine doctor --check` from a clone.
Codex (from a clone; project-local, or add `--global`):
```
git clone https://github.com/talas9/anti-hall.git
cd anti-hall
~/.anti-hall/ah-engine/bin/ah-engine install-codex
```
Update with `/anti-hall:update` (Claude) or the `anti-hall-update` skill (Codex), then `/reload-plugins` (Claude Code; restart only if a hook or skill path still shows the old version).
## Docs
- [README.md](https://github.com/talas9/anti-hall/blob/main/README.md): short landing page (what it does, install, Jev, data).
- [plugins/anti-hall/README.md](https://github.com/talas9/anti-hall/blob/main/plugins/anti-hall/README.md): the plugin directory page (what it does, install, data sent).
- [plugins/anti-hall/codex/README.md](https://github.com/talas9/anti-hall/blob/main/plugins/anti-hall/codex/README.md): the Codex port, hook subset, skills, OMX mapping.
- [docs/README.md](https://github.com/talas9/anti-hall/blob/main/docs/README.md): the documentation start page, a grouped index of every doc.
- [Docs site](https://talas9.github.io/anti-hall/): the same docs as a searchable site (MkDocs, GitHub Pages).
- [docs/REPO-PIPELINES.md](https://github.com/talas9/anti-hall/blob/main/docs/REPO-PIPELINES.md): every GitHub workflow, its trigger and whether it gates, and the repository policies.
- [docs/CONTRACT-1.0.md](https://github.com/talas9/anti-hall/blob/main/docs/CONTRACT-1.0.md): the 1.0 compatibility contract (stable CLIs, hooks, settings, paths).
- [docs/AH-ENGINE.md](https://github.com/talas9/anti-hall/blob/main/docs/AH-ENGINE.md): the ah-engine (the core component): install (pinned sha256), go-live and rollback, failover and self-heal, telemetry, what still runs on Node, pre-release measurements.
- [docs/DEVELOPMENT.md](https://github.com/talas9/anti-hall/blob/main/docs/DEVELOPMENT.md): build, test and release the plugin and the engine.
- [docs/HOOK-LATENCY.md](https://github.com/talas9/anti-hall/blob/main/docs/HOOK-LATENCY.md): measured hook latency (wall p50/p95, CPU).
- [docs/E2E-TESTING.md](https://github.com/talas9/anti-hall/blob/main/docs/E2E-TESTING.md): end-to-end testing guide.
- [docs/TASK-WORK.md](https://github.com/talas9/anti-hall/blob/main/docs/TASK-WORK.md): the task dedup/relate ladder.
- [docs/TASKLIST-GUARD.md](https://github.com/talas9/anti-hall/blob/main/docs/TASKLIST-GUARD.md): the tasklist guard and per-session progress files.
- [docs/KB.md](https://github.com/talas9/anti-hall/blob/main/docs/KB.md): knowledge-base ground truth.
- [docs/GUIDE.md](https://github.com/talas9/anti-hall/blob/main/docs/GUIDE.md): extended guide and per-hook reference.
- [docs/KB-devswarm-hivecontrol.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-devswarm-hivecontrol.md): DevSwarm hivecontrol CLI and the mesh.
- [docs/KB-devswarm-app-db.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-devswarm-app-db.md): the DevSwarm app database.
- [docs/KB-session-handover.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-session-handover.md): session handover design.
- [docs/KB-handover-research.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-handover-research.md): handover research (compaction, triggers).
- [docs/KB-jev-classifier.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-jev-classifier.md): the Jev classifier (opt-in), integrations, metrics.
- [docs/KB-claude-code-hooks.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-claude-code-hooks.md): Claude Code hooks reference.
- [docs/KB-codex-platform-hooks-plugins.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-codex-platform-hooks-plugins.md): Codex platform hooks and plugins.
- [RELEASING.md](https://github.com/talas9/anti-hall/blob/main/RELEASING.md): release checklist and branch flow (work on `dev`, pull request `dev` → `main`).
- [AGENTS.md](https://github.com/talas9/anti-hall/blob/main/AGENTS.md): the protocol for Codex and cross-tool agents.
- [CHANGELOG.md](https://github.com/talas9/anti-hall/blob/main/CHANGELOG.md): version history.
- [CONTRIBUTING.md](https://github.com/talas9/anti-hall/blob/main/CONTRIBUTING.md): how to contribute and run the tests.
- [SECURITY.md](https://github.com/talas9/anti-hall/blob/main/SECURITY.md): how to report a vulnerability.
- [CODE_OF_CONDUCT.md](https://github.com/talas9/anti-hall/blob/main/CODE_OF_CONDUCT.md): expected behaviour and how to report a conduct problem.
- [PRIVACY.md](https://github.com/talas9/anti-hall/blob/main/PRIVACY.md): what data leaves your machine, what stays, and how to turn each off.
## Hooks (plugins/anti-hall/hooks/, registered in the dispatch table; hooks.json is one thin trigger per event generated from it, hooks.registry.json lists the hooks)
All fail-open. "Codex" = also registered by the Codex port (`codex/hooks/hooks.json`).
Switch = the setting (and/or env var) that turns the hook off; every hook has one except the
infrastructure listed under Settings. "safety" = a safety key: `set` to the risky value, and a `reset` whose fallback value is
risky (e.g. resetting an armed `guards.stashGuard`, default off), need `--confirmed` (a human direct command, or the agent asking
and getting a yes); re-arming a guard never does. /config, env and a `settings.json` value all count (normal precedence).
| Event (matcher) | Hook | What it does | Codex | Switch |
|---|---|---|---|---|
| SessionStart | verify-first-full | Injects the verify-first foundation: Iron Law, rationalization table, positive rules, scope & fidelity, output-presentation rule K. | ✓ | context.verifyFirstSession |
| SessionStart | verify-first-orch | Injects the orchestration ruleset (rules A–N, DevSwarm-Primary rule W) inline by default; experimental `context.orchFullOn=spawn` sends compact lines plus a per-session marker instead and orch-on-spawn.js delivers the full text on the first spawn. | ✓ | context.verifyFirstOrchestration |
| PreToolUse (Agent\|Task\|Workflow) | orch-on-spawn | Experimental, opt-in (`context.orchFullOn=spawn`, unverified live): sends the full orchestration rules once per context epoch on the coordinator's first spawn (Claude Code only); silent by default. | — | context.verifyFirstOrchestration |
| SessionStart | version-alert | Tells the user when anti-hall is behind: remote newer → update then reload; plugin-cache mirror newer → reload only. Once per session; 2 h detached refresh. | ✓ | `ANTIHALL_VERSION_ALERT=off` |
| SessionStart | claude-cli-version | Flags Claude Code CLI drift from the version anti-hall's harness KB was verified against. | ✓ | `ANTIHALL_CLAUDE_CLI_VERSION_ALERT=off` |
| SessionStart | devswarm-version | Flags DevSwarm/hivecontrol version drift (DevSwarm only). | ✓ | `ANTIHALL_DEVSWARM_VERSION_ALERT=off` |
| SessionStart | repo-self-drift | Network-free self-check of anti-hall's own repo docs vs. code counts. | ✓ | `ANTIHALL_REPO_SELF_DRIFT=off` |
| SessionStart | fable-availability | Detects Fable model availability from the local model cache; silent unless available. | — | — |
| SessionStart | codex-availability | Caches whether a `codex` executable is on PATH (`~/.anti-hall/codex-availability.json`). | ✓ | — |
| SessionStart | devswarm-child-role | DevSwarm child: reminds it to self-report idleness over the mesh. | ✓ | devswarm.childRole |
| SessionStart | progress-prune | Archives stale per-session progress files into the history ledger, deleting only after the append succeeds; throttled per cwd. | ✓ | maintenance.progressPrune |
| SessionStart | handover-resume | Surfaces the latest `.anti-hall/handovers/` entry after startup, `/clear` or compaction. | ✓ | context.handoverResume |
| SessionStart | emit-dedupe-reset | Marks a context loss so repeated per-turn blocks are re-emitted. | ✓ | — |
| SessionStart | jev-weekly-scorecard | Jev enabled only: once a week names one integration worth promoting (KEEP) or turning off (REMOVE). | ✓ | jev.weeklyNotice |
| SessionStart | jev-review-reminder | Jev enabled only: durable "time to review the Jev shadow numbers" nudge once a shadow integration has run `jev.reviewAfterDays` with `jev.reviewMinDecisions` decisions logged; also the bold "Recommended: enable Jev" notice while Jev is OFF (`jev.recommendNotice`, once, then at most every 30 days). | ✓ | jev.reviewReminder |
| SessionStart | defect-nudge | Once-a-day count of open defect reports (counts only, never reporter text). | ✓ | context.defectNudge |
| SessionStart + UserPromptSubmit | repair-on-reload | When any repair migration isn't stamped for the running version, spawns one detached `ah-engine doctor --repair --migrations-only --quiet` (data migrations only; never writes user config — the legacy migration copies into the project's `.anti-hall/history/legacy/` and never deletes or moves a repo file — the GSD `.planning/` fold is explicit-only, copy-only `migrate-state.js --planning`; lock-guarded; at most once an hour; newest 5 logs kept). | ✓ | maintenance.repairOnReload (`ANTIHALL_REPAIR_ON_RELOAD=off`) |
| UserPromptSubmit | verify-first | Short rotating one-line verify-first nudge. | ✓ | context.verifyFirstTurn |
| UserPromptSubmit | task-tracker | Task-list discipline directive plus a freshness note when tasks are open/stale. | ✓ | context.taskTracker |
| UserPromptSubmit | idle-agent-sweep | Advisory (never blocks), once per user prompt: lists agents that finished but were never stopped (Claude named teammates whose last report has idleReason available/failed, with no later SendMessage or TaskStop; Codex multi_agent_v1 agents completed/errored in wait_agent and never closed), oldest first, up to 10 names, with the exact `TaskStop` / `close_agent` call. Fires at ≥ 3 idle or any idle ≥ 15 min. | ✓ | guards.idleAgentSweep, guards.idleAgentSweepCount (3), guards.idleAgentSweepMin (15) |
| UserPromptSubmit | limit-conserve-inject | Token-conservation nudge at the usage threshold (auto mode reads the OMC usage cache). | ✓ | `ANTIHALL_LIMIT_CONSERVE`, `ANTIHALL_LIMIT_THRESHOLD` |
| UserPromptSubmit | auto-handover | At 93% context by default (known window) or 500000 tokens, whichever comes first; set to fire 5% before auto-compact (Claude auto-compact at 98% on 200k models; `CLAUDE_CODE_AUTO_COMPACT_WINDOW=550000` on 1M): write a handover unasked, tell the user, urge `/compact`/`/clear`; milestone nags every +5 points; unknown window → one soft advisory only. | ✓ | `ANTIHALL_AUTO_HANDOVER_PCT` (`0` = off) |
| UserPromptSubmit | devswarm-parent-inbox | DevSwarm Primary: per-turn workspace table (app titles, sidebar order, finish/PR state, unread, `stale anti-hall <v>`) and neglect nags (after a 120 s grace for fresh unread). | ✓ | devswarm.parentInbox |
| UserPromptSubmit | devswarm-child-turn | DevSwarm child: turn-authored heartbeat, keep-parent-updated reminder, unread-inbox surfacing. | ✓ | devswarm.childTurn |
| TaskCreated, TaskCompleted | task-lifecycle-log | Appends task events to `.anti-hall/history/<date>/<session>.md`. | — | maintenance.taskLifecycleLog |
| SubagentStart | verify-first-subagent | Re-injects the Iron Law and scope rules into every subagent (no orchestration block). | — | context.verifyFirstSubagent |
| PreToolUse (Bash) | git-guard | Blocks AI self-credit in commits (inline, `-F`, whole-command scan for commit-creating verbs) and `gh` PR/issue/release/merge bodies; PostToolUse `--audit` flags recent commits whose trailer came from a git hook/template/editor; resolves git aliases (config, chains, `!shell`) and blocks defining a git/shell alias whose body is a blocked op (`guards.gitAliasResolve`); for a commit with no -m/-F, checks the message it would reuse (-C/-c rev, --amend HEAD, template) before it runs (`guards.gitReusedMessageCheck`); blocks force-push (`--force`, `-f`, `--force-with-lease`, `+refspec`) and remote branch/tag deletion (`--delete`, `-d`, `:ref`, `--prune`); blocks a `git commit` whose paths include a session handover (`guards.handoverCommitGuard`). | ✓ | safety.gitGuard (safety: --confirmed) + named skip only |
| PreToolUse (Bash) | command-guard | Coordinator must delegate heavy commands; blocks DevSwarm destructive verbs and native hivecontrol messaging. | ✓ | safety.commandGuard (safety: --confirmed) |
| PreToolUse + PostToolUse (Bash) | coordinator-work-guard | Main thread: counts successful state-changing Bash calls (git/gh mutations, repo-file writes, script runs, inline code) in a time window; one advisory note at the nudge count, blocks the Nth (recovery commands and loosely matched inline code are counted but never blocked). Claude only. | — | guards.coordinatorWorkWindowMinutes (`0` = off), guards.coordinatorWorkNudgeAt, guards.coordinatorWorkBlockAt |
| PreToolUse + PostToolUse (Bash) | merge-side-pick | Advisory (never blocks): after a conflict is resolved by taking one side wholesale (`--ours`/`--theirs`, `-X ours|theirs`, `-s ours`), a push with no test run since gets one note (run the tests, review the discarded side). Claude and Codex. | ✓ | guards.mergeSidePickAdvisory (default true) |
| PreToolUse (Bash) | merge-gate | Opt-in: blocks auto-merge without a recorded review. | ✓ | `ANTIHALL_MERGE_GATE=on` |
| PreToolUse (Agent/Task/Write/Edit/MultiEdit/NotebookEdit/Bash) | compact-declaration-guard | After a SAFE TO COMPACT declaration in the current turn, blocks new work (spawns, edits, state-changing shell) until the next user message or an explicit `RETRACT SAFE TO COMPACT` line; read-only tools pass. On by default since 0.117.0. | ✓ (Bash only) | guards.compactDeclarationGuard (default true; `false` is the kill switch) |
| PreToolUse (Bash) | scan-throttle | Advises (never rewrites) running user-listed heavy scan commands under `taskpolicy`/`nice` (no built-in patterns). | — | guards.scanThrottle; `ANTI_HALL_THROTTLE_PATTERNS` |
| PreToolUse (TaskStop) | stale-agent-stop-note | Advisory line (never blocks) when the agent being stopped was sent a message or resumed after its last report and has not reported since. | — | guards.staleAgentStopNote; `ANTIHALL_STALE_AGENT_STOP_NOTE=off` |
| PreToolUse (Write/Edit/MultiEdit) | api-guard | Blocks writing a `module.attr` the installed runtime doesn't have (stdlib/builtins by default). | ✓ (apply_patch) | guards.apiGuard; `ANTIHALL_API_GUARD_THIRDPARTY=1` |
| PreToolUse (Write/Edit/MultiEdit) | ship-it-guard | Opt-in: blocks hard-risk code edits with no `PLAN.md`. | ✓ (apply_patch) | `ANTIHALL_SHIPIT_GATE=on` |
| PreToolUse (Write/Edit/MultiEdit/NotebookEdit) | edit-guard | Coordinator must delegate file edits (root-anchored allowlist for docs/state). | ✓ (apply_patch) | safety.editGuard (safety: --confirmed); `ANTIHALL_EDIT_GUARD_ALLOW` |
| PreToolUse (Read) | inbox-read-guard | Blocks a direct Read of a raw DevSwarm inbox file (use the CLI). | — | devswarm.inboxReadGuard |
| PreToolUse (AskUserQuestion) | ask-guard | Optional, off by default: advises or blocks a question call that would hold work waiting for an answer; a first question starting `DESTRUCTIVE:` or `CREDENTIAL:` is allowed. Also adds a note when background agents are in flight. Claude only. | — | guards.noBlockingQuestions (off/advise/block), guards.questionAgentsNote |
| PreToolUse (SendMessage) | devswarm-comms-guard | Blocks `SendMessage` to a peer session that is a registered DevSwarm workspace (mesh only); never blocks subagent steering. | — | devswarm.commsGuard |
| PreToolUse (Agent/Task) | model-routing-guard | Routes spawns to the cheapest fitting model: blocks a mechanical spawn with no model (strict default), advises on flagship + mechanical; blocks a spawn that runs anti-hall's own update (it runs in the main session, guards.updateInSession). | — | guards.modelRouting (strict/advisory/off) |
| PreToolUse (Agent/Task) | swarm-guard | Anti-fork-bomb: spawn-rate cap + real free-memory check. | — | safety.swarmGuard (safety: --confirmed) |
| PreToolUse (Agent/Task) | phase-tracker | Records spawns for the statusline and the Stop guards. | — | — |
| PostToolUse (Bash) | output-verify-guard | Advisory: flags a pass claim next to failing runner output. | — | `ANTIHALL_OUTPUT_VERIFY_GUARD=off` |
| PostToolUse (Bash) | devswarm-parent-reply-tracker | Records replies to child `--question`s for the parent gate. | ✓ | devswarm.parentReplyTracker |
| PostToolUse (Bash) | devswarm-child-drain | DevSwarm child: mid-turn inbox drain (throttled). | ✓ | devswarm.childDrain |
| PostToolUse (TaskCreate\|TaskUpdate) | dispatch-tier | Jev dispatchTier: asks (detached) for a workspace / workflow / subagent recommendation when a task's text changes; task-tracker annotates the DISPATCH NOW line from the cache. Advisory only. | — | jevIntegrations.dispatchTier |
| PostToolUse (Agent) | codex-quota-detect | Records a Codex quota/rate-limit exhaustion from a `codex:codex-rescue` result so other lanes reuse it. | — | guards.codexQuotaDetect |
| PostToolUseFailure (Bash) | failure-root-cause-nudge | One-line pointer to `/anti-hall:root-cause` after a failed command. | — | `ANTIHALL_FAILURE_ROOT_CAUSE_NUDGE=off` |
| Stop | task-guard | Blocks once when ending with genuinely open tasks. | ✓ | guards.taskGuard |
| Stop | tasklist-guard | Requires a live task list + fresh progress file for non-trivial work. | ✓ | guards.tasklistGuard; `ANTIHALL_TASKLIST_WORK_THRESHOLD` |
| Stop | speculation-guard | Tier 2: flags hedge-word speculation (optionally Jev-backed); opt-in `guards.inferenceCheck` also flags a confident causal claim no tool evidence mentions. | ✓ | guards.speculationGuard |
| Stop | claim-ledger | Tier 2.5, ledger-only (never blocks): records confident claims with no supporting evidence in the turn. | ✓ | guards.claimLedger |
| Stop | speculation-judge | Tier 3, opt-in: LLM judge for confident unverified assertions; sees the user request and tool evidence; Anthropic API or local `claude -p` (`jev.judgeBackend`). | ✓ | `jev.semanticJudge` or `ANTIHALL_SEMANTIC_JUDGE=1` |
| Stop | codex-nudge | Once per session: suggests an independent Codex review of substantial code. | — | `ANTIHALL_CODEX_NUDGE=off` |
| Stop | silent-agent-nudge | Scans the transcript for a background Agent launch with no terminal notification and a stale/missing `output_file` (plus the `~/.anti-hall/agents` heartbeat as an extra signal); nudges once per stale snapshot past the threshold (default 20 min); never kills anything. | ✓ | guards.silentAgentNudge; guards.silentAgentNudgeMin (`ANTIHALL_SILENT_AGENT_NUDGE=off`) |
| Stop | compact-advice-guard | Blocks once when the final reply recommends /compact ("SAFE TO COMPACT", "good point to /compact") while context is below the auto-handover threshold minus a margin, or within N turns of a compact boundary; the threshold-fired handover path stays allowed. | ✓ | guards.compactAdviceGuard; guards.compactAdviceRecentTurns; guards.compactAdviceMarginPct |
| Stop | auto-handover-pause-nag | Delivers the handover directive once at a Stop if a long turn never reached a new prompt; afterwards, at a quiet pause, reminds at most once per 15 min. | ✓ | autoHandover.nag |
| Stop | devswarm-parent-gate | DevSwarm Primary: blocks ending the turn with child unread/stale/escalated or own unread (capped). | ✓ | devswarm.parentGate |
| Stop | devswarm-child-gate | DevSwarm child: must heartbeat/self-report before idling (capped). | ✓ | devswarm.childGate |
| PreCompact | precompact-snapshot | Before every compaction writes a mechanical `PRECOMPACT-<n>.md` (git state, task list, last 10 user messages, newest handover pointer); never blocks. A "since the last handover" delta is planned, not shipped. | ✓ | maintenance.precompactSnapshot |
| SessionEnd | session-end-mcp-reaper | On clean exit, reaps MCP servers orphaned by earlier crashed sessions (audit-logged). | — | maintenance.sessionEndReaper (`ANTIHALL_SESSION_END_REAPER=0`) |
Shared libraries (not hooks): `verify-first-core.js`, `coordinator-detect.js`, `skip-guard.js`,
`omc-detect.js`, `limit-conserve.js`; `hooks/lib/`: `settings.js` + `settings-schema.js`
(the settings store), `context-pct.js` + `context-pct-store.js` (context %),
`auto-handover-config.js`/`-state.js`, `jev-client.js`/`jev-assist.js`/`jev-triage.js`,
`defect-store.js` + `defect-history.js`, `emit-dedupe.js`, `state-prune.js`, `doctor-repair.js`,
`devswarm-detect.js`, `devswarm-wake.js`, `transcript-tail.js`.
## Claude skills (plugins/anti-hall/skills/, invoke as /anti-hall:<name>)
| Skill | What it does |
|---|---|
| root-cause | Evidence-driven debugging: prove the original and root cause before any fix. |
| orchestration | Non-blocking coordinator/worker swarm; background + parallel subagents. |
| deadly-loop | Reviewer + Auditor + Critic debate and fix waves until no new P0/P1. |
| deadly-loop-multi | The deadly-loop trio multiplied 2–4× with diversified lenses. |
| ship-it | One workflow from one-line fix to multi-phase feature; rigor scaled to blast radius. |
| simplify | Behavior-preserving simplification of recent code. |
| debt | Register and audit deliberate technical debt markers. |
| handover | Minimal-but-lossless session handover for a fresh session. |
| doctor | Health check and `--repair` (hooks present, guards fire, companions, DevSwarm, split stores). |
| update | Self-update, changelog delta, repairs, then `/reload-plugins` (restart only if a hook or skill path still shows the old version). |
| activate | One-shot first-run setup. |
| install-statusline | Installs the two-line statusline. |
| settings | Show/change any setting (`~/.anti-hall/settings.json`), including auto-handover. |
| system-briefing | The operator guide: glossary, hard rules, every skill/CLI verb/setting with defaults, plus a live inventory of what is installed. SessionStart points agents at it. |
| devswarm | DevSwarm integration: mesh CLI, recovery, auto-archive/prune, retention, app DB, screenshot sync. |
| jev | Jev classifier activation, modes per integration, report. |
| defects | File/list/show/rule on anti-hall defect reports. |
`skills/MODEL-POLICY.md` is the shared model roster (Claude + Codex tables).
## Codex skills (plugins/anti-hall/codex/skills/)
| Codex skill | Claude counterpart / purpose |
|---|---|
| anti-hall-activate | activate |
| anti-hall-context-conserve | no Claude skill — Codex form of limit conservation (`limit-conserve-inject.js`) |
| anti-hall-deadly-loop | deadly-loop |
| anti-hall-debt | debt |
| anti-hall-defects | defects |
| anti-hall-devswarm | devswarm |
| anti-hall-doctor | doctor |
| anti-hall-handover | handover |
| anti-hall-install-statusline | install-statusline (explains what applies on Codex) |
| anti-hall-jev | jev |
| anti-hall-model-policy | skills/MODEL-POLICY.md (Codex model table) |
| anti-hall-omc | no Claude skill — optional OMC state from Codex |
| anti-hall-omx | no Claude skill — oh-my-codex (OMX) integration |
| anti-hall-orchestration | orchestration |
| anti-hall-root-cause | root-cause |
| anti-hall-settings | settings (numbered-choice menus; no `/config` on Codex) |
| anti-hall-ship-it | ship-it |
| anti-hall-simplify | simplify |
| anti-hall-system-briefing | system-briefing |
| anti-hall-update | update |
## Scripts and companions
| Path | Verbs / use |
|---|---|
| ah-engine settings | `show [--all] [--section s] [--json]`, `get`, `set`, `reset` — the settings store CLI; `trust-command-allow [<repo>] --confirmed` trusts a repo's `.anti-hall/command-allow.json` by content hash; `trust-edit-allow [<repo>] --confirmed` trusts its `.anti-hall/edit-allow.json` doc-edit globs the same way. |
| ah-engine auto-handover-config | `get \| set <1-99> \| off \| on \| max-tokens <n> \| nag on\|off \| nag-step <n> \| nag-quiet <n>` — alias over `autoHandover.*`. |
| ah-engine mesh | The DevSwarm mesh CLI (JSON out): register/ensure, register-primary, primary status/takeover, heartbeat, send, inbox (incl. `inbox tick`, the mailbox-wake cron drain), roster, mesh, gate, spawn, merge, archive, reconcile, diagnose, healthcheck, app-state, app-sync, sync-ui, auto-archive, prune-archived, retention, … (`help` lists all). |
| ah-engine jev-setup | `status \| enable \| disable \| set-key \| test \| mode` (`--transport vercel\|typesafe`). |
| ah-engine jev-report | Per-integration calls, precision, cost/efficiency, budget status, credit balance; `--by project\|session`, `--project`, `--weekly`; `label`, `prune-audit`. |
| ah-engine defect | `report \| list \| show \| rule \| archive` for the defect channel; `backfill \| recurring \| similar` for bug history (hotspots, likely regressions, similar past fixes). |
| ah-engine briefing | Backs system-briefing. |
| ah-engine capability-scan | Harness capability scan (see the update skill). |
| ah-engine harvest | Backs the debt skill. |
| `ah-engine migrate` | State-layout migration CLI (see the update skill). |
| ah-engine update | The updater (`--check`); re-execs the freshly pulled version for post-pull stages; re-registers the plugin with the harness (`claude plugin update`) and then asks for a `/reload-plugins`. |
| ah-engine doctor | Doctor (`--repair`, `--quiet`). |
| ah-engine mcp-reaper | Opt-in interval job killing orphaned MCP servers (macOS LaunchAgent / systemd user timer). |
| ah-engine devswarm supervisor | Opt-in DevSwarm sweep: liveness poke/escalate (never kills), app-DB sync, auto-archive, message retention, hourly housekeeping (child-gate/reaped sweeps), own log rotation. Installer dry-runs under tests or a temp HOME. |
| ah-engine devswarm ingest | Opt-in per-project ingest daemon (`hivecontrol workspace monitor` → mesh store). |
| ah-engine migrate | Legacy DevSwarm state → store migration. |
| ah-engine devswarm recover | The only DevSwarm path that kills: on-demand, one named workspace. |
| ah-engine statusline | The two-line statusline renderer (line 1 rich, line 2 phase bar; also persists the context window for auto-handover); `ah-engine install-statusline` / `ah-engine uninstall-statusline` manage it. |
| monitors/monitors.json | Registers `ah-engine devswarm wake-watch` (Monitor-based wake; off: `devswarm.wakeWatch`). |
## Settings (user-facing; `/anti-hall:settings`, `ah-engine settings show --all` for advanced)
Store: `~/.anti-hall/settings.json`. Precedence: env > settings.json > stored plugin option
(plugin.json userConfig, headline rows only) > legacy file (e.g. `jev.json`) > default; legacy outranks the plugin option
until the one-time migration is stamped.
Numbers clamp to schema bounds. Every feature has a settings key in ~/.anti-hall/settings.json, reachable through
/anti-hall:settings and grouped by category; Claude Code's plugin options (`/config`) show only the 10 headline
switches, the safety guards and the 4 keys (14 userConfig options; a drift test pins them). Older stored plugin
options keep resolving as a read-only source and are copied into settings.json by the first update / doctor --repair
that runs the migration (locked safety keys as human-confirmed values). Enum switches are a string
type whose description lists the allowed values, since `/config` requires Claude Code ≥ 2.1.269 for those rows.
Codex: no `/config`, use the skill.
| Setting | Default | Env |
|---|---|---|
| autoHandover.enabled / pct / maxTokens / nag / nagStepPct / nagQuietMin / gateNewWork / gateBudgetPct | true / 93 / 500000 / true / 5 / 15 / true / 5 | `ANTIHALL_AUTO_HANDOVER_PCT`, `ANTIHALL_AUTO_HANDOVER_MAX_TOKENS` |
| guards.mergeGate / shipitGate | false / false | `ANTIHALL_MERGE_GATE`, `ANTIHALL_SHIPIT_GATE` |
| guards.outputVerifyGuard / failureRootCauseNudge / repoSelfDrift / emitDedupe | true | `ANTIHALL_OUTPUT_VERIFY_GUARD`, … |
| guards.stashGuard (safety: --confirmed) | false | `ANTIHALL_STASH_GUARD` |
| guards.handoverCommitGuard | true | `ANTIHALL_HANDOVER_COMMIT_GUARD` |
| guards.gitGuardHeredocData | true | `ANTIHALL_GIT_GUARD_HEREDOC_DATA` |
| guards.modelRouting | strict (strict/advisory/off) | `ANTIHALL_MODEL_ROUTING` |
| guards.noBlockingQuestions | off (off/advise/block) | `ANTIHALL_NO_BLOCKING_QUESTIONS` |
| guards.questionAgentsNote | true | `ANTIHALL_QUESTION_AGENTS_NOTE` |
| guards.sharedTreeAgentNote | true | `ANTIHALL_SHARED_TREE_AGENT_NOTE` |
| guards.mergeSidePickAdvisory | true | `ANTIHALL_MERGE_SIDE_PICK_ADVISORY` |
| guards.idleAgentSweep / idleAgentSweepCount / idleAgentSweepMin | true / 3 / 15 | `ANTIHALL_IDLE_AGENT_SWEEP`, `ANTIHALL_IDLE_AGENT_SWEEP_COUNT`, `ANTIHALL_IDLE_AGENT_SWEEP_MIN` |
| guards.tasklistNoTaskTools | reduced | `ANTIHALL_TASKLIST_NO_TASK_TOOLS` |
| guards.stopNagBudgetPerPrompt | 0 | `ANTIHALL_STOP_NAG_BUDGET` |
| guards.apiGuard / speculationGuard / claimLedger / taskGuard / tasklistGuard / scanThrottle | true | `ANTIHALL_SCAN_THROTTLE` (scanThrottle; deprecated alias `ANTI_HALL_SCAN_THROTTLE`) |
| safety.gitGuard / commandGuard / editGuard / swarmGuard (safety: risky `set`/`reset` need `--confirmed`; normal precedence applies, settings.json values count) | true | `ANTIHALL_GIT_GUARD`, `ANTIHALL_COMMAND_GUARD`, `ANTIHALL_EDIT_GUARD`, `ANTIHALL_SWARM_GUARD` |
| guards.gitAliasResolve / gitReusedMessageCheck (advanced, safety: --confirmed) | true / true | `ANTIHALL_GIT_ALIAS_RESOLVE`, `ANTIHALL_GIT_REUSED_MESSAGE_CHECK` |
| guards.editGuardAllow / allowSubagentMailbox (advanced, safety: --confirmed) | "" / false | `ANTIHALL_EDIT_GUARD_ALLOW`, `ANTIHALL_ALLOW_SUBAGENT_MAILBOX` |
| engine.bootstrap | false | `AH_ENGINE_BOOTSTRAP` (1 opts in to the automatic `ah-engine` binary download on SessionStart, 0 forces it off; overrides the setting; the explicit install is `sh hooks/install.sh --download`) |
| engine.autoUpdate | off | `AH_ENGINE_AUTO_UPDATE` (off, stable or dev: `ah-engine engine-update --auto` from the engine scheduler, at most daily; URLs and timeouts in `engine/ah-update.toml`) |
| context.verifyFirstSession / verifyFirstOrchestration / verifyFirstTurn / verifyFirstSubagent / taskTracker / handoverResume / defectNudge | true | — |
| maintenance.repairOnReload / progressPrune / precompactSnapshot / taskLifecycleLog / sessionEndReaper | true | `ANTIHALL_REPAIR_ON_RELOAD`, `ANTIHALL_SESSION_END_REAPER` (deprecated alias `ANTI_HALL_SESSION_END_REAPER`) |
| versionAlerts.antiHall / claudeCli / devswarm | true | `ANTIHALL_VERSION_ALERT`, `ANTIHALL_CLAUDE_CLI_VERSION_ALERT`, `ANTIHALL_DEVSWARM_VERSION_ALERT` |
| updates.quiet | false | `ANTIHALL_UPDATE_QUIET` |
| limitConserve.mode / threshold | auto / 85 | `ANTIHALL_LIMIT_CONSERVE`, `ANTIHALL_LIMIT_THRESHOLD` |
| jev.enabled / transport / judgeModel / semanticJudge | false / vercel / haiku / false | `ANTIHALL_JEV`, `ANTIHALL_JUDGE_MODEL`, `ANTIHALL_SEMANTIC_JUDGE` |
| jev.budget.mode / usdPerDay / usdPerWeek / minCreditUsd | unlimited / — / — / — | — (watch only warns; never disables Jev) |
| jev.audit.snippets, jev.prices (advanced) | false, — | `ANTIHALL_JEV_AUDIT_SNIPPETS` |
| jev.logRotatedFiles / rollupRetentionDays (advanced) | 10 / 0 (keep all) | — |
| jev.weeklyNotice | true | — |
| jev.recommendNoticeHeadless | false | `ANTIHALL_JEV_NOTICE_HEADLESS` |
| jev.recommendNotice | true | `ANTIHALL_JEV_RECOMMEND_NOTICE` |
| jevIntegrations.speculation / triage / newRequest / claimLedger / outputVerifyGuard / gitGuardSelfCredit / modelRouting / tasklistTrivial / codexNudgeSubstantial / mergeGateHedge / parentGateQuestion / supervisorBlockerLabel / findingDedup / postHandoverGate (one row each; legacy jev.json / jev["integrations.<id>"] auto-migrate) | on (speculation, triage, findingDedup) / off (postHandoverGate) / shadow (rest) | `ANTIHALL_JEV_<ID>=0` forces an integration off |
| devswarm.planTracking / planRequired / stepStallMin / strayWarnMax / burnTokensWarn / burnCacheReadPct / respawnGraceMin / respawnWipWaitSec; jevIntegrations.devswarmOnBrief / devswarmExtraSanctioned / devswarmWaitKind / devswarmLoop / devswarmStepMap | Meeseeks supervision (0.117.0): step plans, advisory straying warnings (stall, off-scope, idle, token burn), `ah-engine mesh correct` / `scope add` / `supervision-report`, and the Primary-run `respawn <id>` (after a warning and a grace period: WIP pushed or parked on a new pushed branch, handover, new workspace from the default branch, old one archived); the five Jev integrations are recommendations to the Primary (default on), never a suppression, block or kill. |
| devswarm.hivecontrol / supervisorMode / requiredGates / inboxCmd | "" / auto / done,merged,tests_passed / "" | `ANTIHALL_DEVSWARM_*` |
| devswarm.autoArchive.mode (+ idleMin, maxPerSweep advanced) | on (30, 3) | `ANTIHALL_DEVSWARM_AUTO_ARCHIVE_MODE` |
| devswarm.retention.days / maxStoreMB / keepPerPartition / archive / archiveMaxMB (advanced) | 30 / 100 / 200 / true / 0 (no cap) | `ANTIHALL_DEVSWARM_RETENTION_*` |
| devswarm.parentGate / childGate / parentInbox / childTurn / childRole / childDrain / parentReplyTracker / commsGuard / inboxReadGuard / wakeWatch / appSync / screenshotSync / spawnFromOrigin / dispatchTierText / inlineWorkNudge | true | `ANTIHALL_DEVSWARM_APP_SYNC` (appSync) |
| statusline.base / noEmail | "" / false | `ANTIHALL_STATUSLINE_BASE`, `ANTIHALL_STATUSLINE_NO_EMAIL` |
| codexNudge.enabled | true | `ANTIHALL_CODEX_NUDGE` |
| defects.defaultProj | "" | `ANTIHALL_DEFECT_PROJ` |
Env-only: `ANTIHALL_CONTEXT_WINDOW_TOKENS`, `ANTI_HALL_THROTTLE_PATTERNS`,
`ANTIHALL_DEVSWARM_APP_DB` (path or `off`). The ~35 DevSwarm tuning knobs are advanced
settings (`show --section devswarm --all`). No switch on purpose (`ah-engine settings show` lists
the reasons): skip-guard, coordinator-detect, omc-detect, phase-tracker, fable-availability,
codex-availability, emit-dedupe-reset, agent-watchdog, command-guard's data-safety
sub-guards.
## State files (~/.anti-hall/)
| Path | Written by / for |
|---|---|
| settings.json | the settings store |
| ah-engine/ | the engine (core component): `bin/ah-engine` (installed from the pinned release, `ah-engine.prev` kept), `bootstrap.log`, `defaults.lkg/` (last-known-good engine files), `hot.db`/`archive.db` (state and local-only telemetry), socket and health files |
| skip.json | per-guard, per-session TTL'd user override (key `<guard>@<session-id>`; `--global` for all sessions; git-guard must be named explicitly) |
| jev.json | legacy Jev config (still read as a fallback; never deleted) |
| update-sweep-state.json | per-migration repair markers (update, doctor, repair-on-reload) |
| version-check.json, version-alert-reload.json | version-alert cache and reload-nudge dedupe |
| orch-full/ | orch-full-<session>.json marker and per-epoch claim files for the once-per-epoch full orchestration delivery (pruned after 7 days) |
| auto-handover/<session>.json, context-pct/<session>.json | auto-handover latch; statusline context window |
| codex-availability.json, phase-state.json, agents/ | availability cache; statusline phase; spawn heartbeats |
| claim-ledger/, approvals/, defects/ | claim ledger; merge approvals; defect channel |
| logs/ | hook/companion logs (jev-assist, jev-audit, devswarm-retention, devswarm-prune, repair-on-reload-*) |
| coordinator-work-session-<session>.json | coordinator-work-guard per-session WORK window and counters (folded into the metrics after 7 days) |
| coordinator-work-metrics.json | coordinator-work nudges, blocks and per-version folded session counts (dispatch-report, doctor) |
| coordinator-work-trips.log | coordinator-work nudge/block/skip events (JSONL, rotated at 1 MiB) |
| .coordinator-work-fold-stamp.json | last coordinator-work fold (at most once per 6 h) |
| devswarm/ | mesh stores, summaries, heartbeats, capabilities.json, app-state.json, archive/ (retention) |
Per-project: `.anti-hall/progress/`, `.anti-hall/history/`, `.anti-hall/handovers/`.
## DevSwarm coordination (optional)
Dormant unless in a DevSwarm session (`DEVSWARM_REPO_ID`) or an opt-in companion is
installed. Primary and children talk only through the per-project mesh store via
`ah-engine mesh` (native hivecontrol messaging and `SendMessage` to workspaces are
blocked). Recovery is layered and never auto-kills: child self-report → supervisor poke →
escalate to the parent; only `devswarm-recover.js` kills. The DevSwarm desktop app's own
SQLite DB is read (read-only, never message bodies or credentials) as the ground truth for
open/archived state, titles, sidebar order, PRs and session identity. Every DevSwarm
surface passes the capability gate (`devswarm-capabilities`: minimum
version + `--help`/schema detection); a missing surface sleeps and doctor names it.
Auto-archive (default on, DevSwarm >= 2.5.3) archives only workspaces proven done, merged,
clean, drained, unfocused and idle, always by explicit workspace id; deleting archived
workspaces needs the owner's approval of an exact list. Message retention archives old
message bodies to gzip, then prunes them. Full reference:
[docs/KB-devswarm-hivecontrol.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-devswarm-hivecontrol.md),
[docs/KB-devswarm-app-db.md](https://github.com/talas9/anti-hall/blob/main/docs/KB-devswarm-app-db.md).
## Manifests, tests, release
- [plugins/anti-hall/.claude-plugin/plugin.json](https://github.com/talas9/anti-hall/blob/main/plugins/anti-hall/.claude-plugin/plugin.json): the only version authority.
- [plugins/anti-hall/.codex-plugin/plugin.json](https://github.com/talas9/anti-hall/blob/main/plugins/anti-hall/.codex-plugin/plugin.json): the Codex manifest, bumped together with the Claude one.
- [.claude-plugin/marketplace.json](https://github.com/talas9/anti-hall/blob/main/.claude-plugin/marketplace.json): the marketplace entry (carries no version).
- [tests/](https://github.com/talas9/anti-hall/tree/main/tests/): zero-dependency `node --test`; v0.108.0 end-to-end scenarios in `tests/e2e/v0108/`.
- [.github/workflows/test.yml](https://github.com/talas9/anti-hall/blob/main/.github/workflows/test.yml): CI: full sharded matrix (ubuntu + macOS x Node 22/24) on `rc-v*` tags, a reduced matrix on pull requests (the `dev` → `main` pull request is the merge gate) and on `main`; pushes to `dev` and `v*` tags do not trigger it.
- [RELEASING.md](https://github.com/talas9/anti-hall/blob/main/RELEASING.md): bump both manifests + CHANGELOG on `dev`, pull request `dev` → `main`, tag, GitHub Release.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

