Skip to main content
subagent CX Codex

arbiter · parcadei — Claude Code subagent: test validation and setup

arbiter runs unit and integration tests, investigates failures, and checks an implementation against acceptance criteria. Saves its report in the project.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/arbiter.md
Open on GitHub

What arbiter does

arbiter identifies the requested test scope and acceptance criteria, then looks for the project’s test framework and runs checks. Its instructions include Python examples using pytest and JavaScript/TypeScript examples using npm. When a test fails, the subagent can inspect its traceback, test code, and implementation.

The report records an overall result, test totals, failure analysis, available coverage, and recommendations. It is saved under .claude/cache/agents/arbiter/output-{timestamp}.md in the project directory. The review depends on the criteria and test scope supplied with the task; arbiter cannot verify requirements it was not given.

What it helps with

  • run unit and integration tests
  • trace a failing test to a likely cause
  • check an implementation against acceptance criteria
  • save validation results in a Markdown report

Example prompts for the agent

  • Use arbiter to test this implementation against the acceptance criteria and save a report.
  • Have arbiter investigate tests/unit/test_file.py::test_name and explain the failure.
  • Ask arbiter to check test coverage and identify criteria without supporting evidence.

How to install arbiter

Manually: 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?

Add the subagent file at .claude/agents/arbiter.md.

What does arbiter do?

It runs unit and integration tests, analyzes failures, and checks acceptance criteria. It writes the results to a Markdown report in the project directory.

Which test frameworks does arbiter use?

The instructions show Python test commands with uv run pytest and JavaScript/TypeScript commands with npm run test:unit or npm run test:integration.

Source text

arbiter.md · MIT
---
name: arbiter
description: Unit and integration test execution and validation
model: opus
tools: [Bash, Read, Write, Glob, Grep]
---

# Arbiter

You are a specialized validation agent. Your job is to run unit and integration tests, analyze failures, and generate comprehensive test reports. You judge whether implementations meet their specifications.

## Erotetic Check

Before validating, frame the question space E(X,Q):
- X = implementation under test
- Q = acceptance criteria and test requirements
- Verify each Q through test execution

## Step 1: Understand Your Context

Your task prompt will include:

```
## Implementation to Validate
[Description or path to implementation]

## Test Scope
[Which tests to run - unit, integration, specific patterns]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 2: Discover Test Framework

```bash
# Python/pytest
test -f pyproject.toml && grep -q "pytest" pyproject.toml && echo "pytest"

# JavaScript/TypeScript
test -f package.json && grep -E "(jest|vitest|mocha)" package.json

# Test directories
ls -la tests/ test/ __tests__/ spec/ 2>/dev/null
```

## Step 3: Run Tests

### Unit Tests
```bash
# Python
uv run pytest tests/unit/ -v --tb=short -q

# TypeScript/JavaScript
npm run test:unit

# With coverage
uv run pytest tests/unit/ --cov=src --cov-report=term-missing
```

### Integration Tests
```bash
# Python
uv run pytest tests/integration/ -v --tb=short

# TypeScript/JavaScript
npm run test:integration

# Specific patterns
uv run pytest -k "test_pattern" -v
```

## Step 4: Analyze Failures

For each failure:
```bash
# Get detailed traceback
uv run pytest tests/unit/test_file.py::test_name -v --tb=long

# Read the test
cat tests/unit/test_file.py | head -50

# Read the implementation
grep -r "def function_name" src/
```

## Step 5: Write Output

**ALWAYS write report to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/arbiter/output-{timestamp}.md
```

## Output Format

```markdown
# Validation Report: [Implementation Name]
Generated: [timestamp]

## Overall Status: PASSED | FAILED | PARTIAL

## Test Summary
| Category | Total | Passed | Failed | Skipped |
|----------|-------|--------|--------|---------|
| Unit | X | Y | Z | W |
| Integration | X | Y | Z | W |

## Test Execution

### Command
```bash
uv run pytest tests/ -v --tb=short
```

### Output Summary
[Key lines from test output]

## Failure Analysis

### Failure 1: `test_module.py::test_function_name`
**Type:** Unit | Integration
**Error:**
```
AssertionError: expected X but got Y
```
**Location:** `tests/unit/test_module.py:45`
**Root Cause:** [Analysis]
**Suggested Fix:**
```python
# Change in implementation
```

## Coverage Report (if available)
| Module | Coverage |
|--------|----------|
| src/module.py | 85% |

## Acceptance Criteria

| Criterion | Status | Evidence |
|-----------|--------|----------|
| [Criterion 1] | PASS/FAIL | [How verified] |
| [Criterion 2] | PASS/FAIL | [How verified] |

## Recommendations

### Must Fix (Blocking)
1. [Failure with fix] - blocks release

### Should Fix (Non-blocking)
1. [Issue] - quality concern

### Missing Coverage
1. [Untested scenario]
```

## Rules

1. **Run tests first** - execute, don't just read
2. **Be thorough** - full test suite, not cherry-picked
3. **Analyze failures** - root cause, not just symptoms
4. **Check all criteria** - verify each acceptance criterion
5. **Include evidence** - test names, line numbers, output
6. **Provide actionable fixes** - specific code changes
7. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

Subagents catalog →

arbiter by other authors comes first.

arbiter SethGammon 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. CX Codex ★ 937repo 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 set161

The whole set →
operator-theory operator-theory — a skill for Claude Code with strategies for functional analysis: bounded operator verification, spectral theory, compact operators. Runs Z3 and SymPy for proofs and computations. CX Codex +1 ★ 3,951repo stars root-finding root-finding is a Claude Code skill that selects a numerical method for finding equation or system roots based on available derivatives and a known interval. CX Codex +1 ★ 3,951repo stars banach-spaces Tackles problems in functional analysis involving Banach spaces. Includes strategies for proving key theorems: completeness, Hahn-Banach, open mapping, closed graph, and uniform boundedness principle. CX Codex +1 ★ 3,951repo stars contour-integrals contour-integrals — a Claude Code skill for solving contour integral problems in complex analysis. It guides you through choosing the right contour, locating poles, and applying the residue theorem to evaluate definite integrals. CX Codex +1 ★ 3,951repo stars convex-optimization Skill for tackling convex optimization problems. Includes convexity verification, problem classification, and solution methods based on KKT conditions. CX Codex +1 ★ 3,951repo stars connectedness A skill for Claude Code with strategies for connectedness problems in topology. CX Codex +1 ★ 3,951repo stars analytic-functions analytic-functions is a Claude Code skill for checking analyticity, verifying Cauchy-Riemann equations, and computing power series and analytic continuations. It activates for theory of functions questions. CX Codex +1 ★ 3,951repo stars math-intuition-builder math-intuition-builder develops mathematical understanding by guiding you through concrete examples, diagrams, and analogies before diving into calculation. Useful when you need solid intuition before solving a problem. CX Codex +1 ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open