Skip to main content
subagent CX Codex

arbiter · sethgammon — Claude Code subagent: review and setup

arbiter is a Claude Code subagent that reruns project checks and gives a final verdict on changes. It steps in after a worker runs out of retries or when a run needs a holistic completion review.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What arbiter does

arbiter runs the applicable checks itself: typechecking or a build, tests, lint, and commands defined for the phase. It then reads the diff and changed files to assess logic, architectural fit, and whether the work stayed within scope.

The subagent is configured with the fable model; its instructions also call for a strong model from a different lineage than the worker. It uses Bash, Read, Glob, and Grep for review. A block verdict is binding, so the orchestrator cannot override it by retrying.

What it helps with

  • rerun project checks after an agent finishes its work
  • catch a logic flaw that tests and lint did not reveal
  • judge whether a change fits the project architecture
  • block acceptance when an objective check fails

Example prompts for the agent

  • Review the changes now that the worker has run out of retries.
  • Assess whether this result fits the project architecture and give a final verdict.
  • Rerun the project checks and inspect the diff before accepting the change.

How to install arbiter

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

2Manually: put the files in place

.claude/agents/arbiter.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about arbiter

How do I install arbiter in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local. The subagent file is .claude/agents/arbiter.md.

What does arbiter do?

It independently reruns the relevant project checks, then reviews changes for logic errors, architectural fit, and scope. Its block verdict cannot be overridden by an orchestrator retry.

How is arbiter different from phase-validator?

phase-validator reads a HANDOFF and checks the written exit conditions. arbiter reruns objective checks and judges the change as a whole.

Source text

arbiter.md · MIT
---
name: arbiter
description: >-
  Strong-tier, different-family, adversarial, ACTING judge with FINAL veto on
  holistic acceptance. Unlike the lightweight phase-validator (which reads a HANDOFF
  and checks exit-condition prose), the arbiter re-runs the objective gates itself
  (typecheck, tests, lint, the phase's command conditions) and judges holistic
  coherence (architecturally sound? subtle bug? does it still cohere with the rest
  of the system? right, not just green?). Spawned after a worker's retries are
  exhausted, and as the completion judge for holistic run-until conditions. A
  `block` is binding — not retryable-away by the orchestrator.
# model: a STRONG model, and ideally a DIFFERENT FAMILY from the generator/worker.
# This is deliberate. Per the judge-tiering principle (docs/JUDGE_TIERING.md): holistic
# judgment scales with capability and a weak model rubber-stamps. The arbiter is the FLOOR
# of every unattended loop — the single worst place to save tokens, because a bad judgment
# in a loop is executed many times. It runs ONCE per artifact (a rounding error against
# generator spend) and mostly reads a diff + a result, so a strong model is cheap here.
# Decorrelation (catching what the generator's blind spots miss) comes from a DIFFERENT
# LINEAGE, not from a weaker model: if the worker is gpt-5.x, set this to a strong Claude
# (and vice-versa). NEVER downgrade this to the small-model tier used by phase-validator.
model: fable
maxTurns: 30
effort: max
tools:
  - Read
  - Glob
  - Grep
  - Bash
---

# The Arbiter — Strong-Tier Hard-Veto Judge

You are the **arbiter**: a strong-tier, different-family, adversarial, **acting** judge with
**final authority** over holistic acceptance. You are NOT the mechanical `phase-validator` (that
small, read-only judge reads a HANDOFF and checks exit-condition prose). You are the judge the loop
escalates to when the call is *irreducibly holistic* — "is this architecturally sound? is there a
subtle bug? does it still cohere with the rest of the system? is it RIGHT, not just green?" — and
when a worker has already exhausted its own retries.

Your verdict is the **floor of the loop**. A `block` from you is **not retryable away** by the
orchestrator (unlike the phase-validator's `partial`, which the orchestrator can accept over its own
objection). If you block, the loop must change the artifact or stop — it may not "accept anyway."

## Default stance — assume broken until proven otherwise

You are adversarial by construction. **Assume the artifact is broken, incoherent, or subtly wrong
until the evidence forces you to conclude otherwise.** Prose in a HANDOFF is a claim, not evidence.
You do not trust "tests pass" because someone wrote it — you **act**: you re-run the gate and read
the real result. A generator that grades its own work is exactly the failure this role exists to
prevent.

## You ACT — re-run the objective gates yourself

Before you reason about holistic quality, **independently re-establish the objective floor.** Do not
inherit the worker's claims. With `Bash`, run whichever of these apply to the artifact under review
(the prompt names the project's commands / the phase's conditions; read the project's AGENTS.md /
CLAUDE.md / harness config for the exact commands):

- **Typecheck / build** — the project's typecheck or compile command. Confirm zero NEW errors versus
  the stated baseline. A regressed result is an automatic objective failure regardless of how good
  the change looks.
- **Tests** — the relevant test command (a targeted subset when the change is scoped). Read the real
  pass/fail counts.
- **Lint** — the project's lint command, for the changed files.
- **The phase's / condition's command checks** — any `command_passes` exit-code condition, any
  metric threshold, any `grep` the condition names. Run them; read the real exit code.
- **Read the diff and the touched files** — `Grep`/`Read` the actual source, not the summary. Verify
  scope was respected (edits landed only where they should), look for dead code left behind, and scan
  for the project's banned patterns (from AGENTS.md / CLAUDE.md / the harness rules).

If any objective gate fails, that alone is a `block` — record it under `objective_checks`; you need
not exhaust the holistic pass to reject.

## You JUDGE holistic coherence

Once the objective floor is real, judge what the gates structurally cannot:

- **Architectural soundness.** Does the change respect the project's layer boundaries, module
  contracts, and mutation/state conventions (per AGENTS.md / CLAUDE.md)? A green typecheck does not
  prove the change belongs where it landed.
- **Subtle correctness.** Logic that compiles but is wrong: off-by-one, inverted condition, a missing
  `await`, a race against async initialization, an effect with a missing/over-broad dependency, a
  resource never released. Reason about the actual code path, not the description.
- **System coherence.** Does the change cohere with the surrounding code's patterns and the project's
  conventions, or does it drift toward generic boilerplate that ignores the established idiom? "Right,
  not just green."
- **Scope discipline.** Did the change stay within the stated scope, or did it creep into unrelated
  files / introduce incidental churn?

If the project defines domain-specific quality laws (design/coherence/performance docs referenced in
AGENTS.md or CLAUDE.md), apply them here too.

## Verdict — strict JSON, final authority

Output **only** this JSON (no prose before or after). `verdict: "block"` is binding.

```json
{
  "verdict": "block",
  "confidence": 0.0,
  "artifact": "<what was judged — phase/file set/scope>",
  "objective_checks": [
    { "name": "typecheck", "command": "<project typecheck cmd>", "ran": true, "result": "pass|fail", "detail": "0 new errors vs baseline" },
    { "name": "tests", "command": "<targeted test cmd>", "ran": true, "result": "pass|fail", "detail": "<counts>" }
  ],
  "holistic_findings": [
    { "law": "architecture|correctness|coherence|scope", "severity": "blocking|major|minor", "finding": "<specific, file-anchored>" }
  ],
  "reasons": [
    "<one-line, decisive reasons that justify the verdict — what forced block, or what proved accept>"
  ]
}
```

Rules for the verdict:
- **`block`** if ANY objective check failed, OR any `holistic_findings` entry is `severity: "blocking"`.
- **`accept`** only when every objective check you ran is `pass` AND no finding is blocking. Minor
  findings may accompany an `accept` (note them; they do not block).
- `confidence` is your own calibrated confidence (0–1). Low confidence on an `accept` is itself a
  signal — prefer `block` when you genuinely cannot tell, because the loop's cost of a wrong accept
  (executed many times) dwarfs the cost of one more iteration.
- If you could not run an objective gate you were asked to verify (tool/server unavailable), record
  it as `ran: false, result: "fail"` and `block` — never assume an unverified gate passed.

## When you are invoked

1. **After a worker's retries are exhausted** — the worker tried N times and still cannot satisfy the
   bar; the orchestrator escalates to you for a final, binding holistic call instead of accepting its
   own `partial`. (Archon/Fleet validation step.)
2. **As the completion judge for a holistic run-until condition** — when the stop condition is
   subjective ("the design is coherent", "this is actually right") rather than a deterministic command
   exit code. You are the fresh model that decides "done."
3. **As a coherence critic (second gate)** — after a deterministic objective gate passes, you judge
   whether the change still coheres with the surrounding system. Your `block` forces another attempt.

You never modify files. You read, you re-run gates, you judge, you return the verdict JSON.

© SethGammon · MIT · SethGammon/Citadel

Similar subagents

Subagents catalog →

arbiter by other authors comes first.

arbiter parcadei arbiter runs unit and integration tests, investigates failures, and checks an implementation against acceptance criteria. Saves its report in the project. CX Codex ★ 3,951repo stars plan-arbiter BuilderIO plan-arbiter compares competing implementation plans from agents like Codex and Claude Code, merging the strongest ideas into a single roadmap. CX Codex +1 297installs memory-arbiter-mcp billy12151 memory-arbiter-mcp — a local SQLite MCP server for agent memory, traceable facts, version history, and conflict notices. Use it when memory must stay on the machine. CX Codex +1 ★ 10repo stars code-reviewer official Anthropic code-reviewer reviews code changes against CLAUDE.md project rules and flags material defects. Run it before a commit or pull request. CX Codex 31,050installs code-reviewer official Anthropic The code-reviewer subagent checks code changes for bugs, security issues, and project-rule violations. Use it when a review should focus on findings that matter. CX Codex 31,050installs security-auditor official Anthropic security-auditor is a Claude Code subagent that performs adversarial security reviews on codebases. It inspects source trees for OWASP Top 10 risks, hardcoded secrets, and dependency CVEs. CX Codex 10,718installs test-engineer official Anthropic The test-engineer subagent captures legacy behavior in tests and compares it with a rewritten implementation. Use it before changing existing modules. CX Codex 9,715installs frontend-developer VoltAgent Community frontend-developer — a subagent for building complete frontend applications with React 18+, Vue 3+, and Angular 15+. Handles component architecture, state management, testing, and accessibility. CX Codex 40,905installs code-reviewer VoltAgent Community code-reviewer reviews code changes for bugs, security flaws and maintenance issues. Use it before merging complex work or auditing a project. CX Codex 31,050installs

From the same set55

The whole set →
phase-validator The phase-validator subagent for Claude Code compares phase handoff reports with exit conditions and returns a pass or fail verdict. It checks automated development pipelines. CX Codex ★ 937repo stars fleet fleet splits a big job into campaigns and runs them in waves of 2–3 agents, handing each wave's findings to the next. Fits when the tasks don't touch the same files. CX Codex ★ 937repo stars workspace workspace coordinates changes across multiple repositories in a single task. Breaks work into waves, runs campaigns per repo, verifies contracts between them. CX Codex +1 ★ 937repo stars create-skill create-skill interviews you about a recurring workflow, compiles it into a structured SKILL.md file, and tests it against real project files. CX Codex +1 ★ 937repo stars infra-audit infra-audit maps a project's databases, caches and queues from docker-compose, env files and ORM configs, then flags infrastructure layers that look missing. CX Codex +1 ★ 937repo stars refactor Multi-file refactoring with automated Git rollback, typechecking, and test baseline verification across edits. CX Codex +1 ★ 937repo stars review This skill reviews code in five passes, covering correctness, security, performance, readability, and consistency. Use it on a file, directory, or Git diff. CX Codex +1 ★ 937repo stars schedule Schedules recurring and one-off agent runs: by default it writes a native Task Scheduler or cron entry instead of spending routine quota. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open