superharness

Overview

Multi-agent task coordination for Claude Code, Codex CLI, Gemini CLI, OpenCode, and Pi

superharness lets AI coding assistants work on the same project without stepping on each other. It provides a shared contract (SQLite-backed), queue-based delegation, lifecycle rules, and handoff/ledger state so tasks survive across sessions and auto-manage themselves.

Example output

One command tells you the whole state of a project — agents, queue, discussions, and every task, in one screen:

$ shux status
superharness status
project: ~/code/my-project
watcher: level=ok foreground (last heartbeat 9s ago)
heartbeat: ok (last heartbeat 9s ago)
inbox: pending=0 launched=0 running=2 paused=0 done=1655 failed=46 stale=0 stopped=0
retry-alert: threshold=3 high=46 ids=inbox-001,auto-eab0b7,auto-9db89b
approvals: pending=1
discussions: active=1 consensus=0 failed_participant=21 deadlock=0 closed=12
tasks: archived=10254 done=6 review=0 todo=2 in_progress=2 plan=1 failed=0 blocked=0 waiting_input=0

Active Tasks:
  feat-auth-rotation   in_progress   claude-code   (dispatched 4m ago)
  fix-migration-drift  plan_proposed owner         (awaiting approval)

No issues found. All clean.

shux status --fix cleans orphans and stale items; shux status --check exits non-zero for CI.

Install as Claude Code Plugin

/plugin marketplace add artificemachine/superharness
/plugin install superharness

Gives you /shux (raw CLI passthrough), /shux-contract, /shux-status, /shux-delegate, /shux-doctor, /shux-close, plus a skill that auto-routes plain-English task/status questions to the right command.

Recent Highlights

Harness adapter registry: claude/codex/gemini/opencode/pi dispatch routed through a single Harness protocol, with golden-parity tests proving byte-identical invocations
Transcript tailing + dual watchdog: byte-offset live dispatch progress with persisted cursors, backed by idle-timeout + absolute-ceiling deadline enforcement from the event stream
Typed telemetry events: dedicated events table (migration v31) with a background emitter and DB-heartbeat liveness (is_fresh)
Dependency hygiene: CVE floors on starlette/python-multipart, a previously-undeclared requests dependency now declared, and .github/dependabot.yml for ongoing drift
Dashboard/CLI DB-path fix: dashboard-ui.py now resolves state.db through the same XDG-aware get_connection as the CLI, closing a silent divergence bug between the two
5,000+ tests preventing regressions across lifecycle, dispatch, and protocol state

⚡ 1-Minute Quickstart

Why use superharness?

Prevent Overlaps: Different agents (Claude, Codex, Gemini, OpenCode, Pi) won't edit the same files at the same time.
Persistent State: If an agent crashes or hits a limit, the next one knows exactly where to pick up.
Auto-Mode: Lifecycle rules auto-archive stale tasks, auto-fail deadlines, auto-close consensus discussions, and auto-clean orphans.
Full Visibility: shux status gives a complete health dashboard in one command.

1. Install

pipx install superharness

2. Initialize

Inside your project:

shux onboard

3. Start the Guardian

# Start background watcher (Headless default)
shux operator start

# Start with dashboard (always-on UI)
shux operator start --dashboard

4. Dashboard UI

# Launch on-demand UI (with auto-timeout)
shux dashboard

The dashboard offers Dark, Light, and Monokai themes. Monokai is the default unless the browser has a valid saved selection; changes persist in localStorage. When Langfuse is configured, its compact orange header button uses a slow three-second pulse that is disabled for reduced-motion users.

5. Check health

shux status          # Full health dashboard
shux status --fix    # Auto-clean orphans, stale items, consensus discussions
shux status --check  # CI mode (exit 1 if issues found)

Using superharness

Via Claude Code, Codex CLI, or another supported agent (recommended)

Step 1 — Install superharness once (terminal):

pipx install superharness

Alternative: install from source

curl -fsSL https://raw.githubusercontent.com/artificemachine/superharness/main/src/superharness/scripts/install-remote.sh | bash
# export PATH="$HOME/.local/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc if needed

Or clone manually:

git clone https://github.com/artificemachine/superharness.git ~/.local/share/superharness
cd ~/.local/share/superharness && pip install -e .

Step 2 — Go to your project and open Claude Code or Codex CLI.

Step 3 — Core workflow:

shux explain           # what is superharness? (10-second answer)
shux onboard           # guided first-time setup
shux task create       # define the task and its criteria
shux contract          # inspect the active work
shux delegate <id>     # send approved work to its owner
shux status            # inspect watcher and queue health
shux context <id>      # recover the task's decisions and handoff
shux verify <id>       # record end-to-end verification
shux close <id>        # close verified work and write its handoff
shux dashboard         # open the visual task board
shux doctor            # diagnose setup and state health
shux recall <keywords> # retrieve relevant prior handoffs

For advanced work, use shux state --help, shux agent --help, shux ops --help, or shux memory --help. Run shux help --all for the complete expert catalog; established top-level commands remain supported for scripts and existing workflows.

Dashboard features (shux dashboard):

Activity feed — live timeline of dispatch, gc, and inbox events
Git context — branch, dirty file count, last commit in header
Task dependency graph — press g to toggle
Dispatch preview — model, effort, cost, timeout in enqueue modal
Keyboard shortcuts — r refresh, g graph, l list, b board, ? help

That's it. Steps 1 and 2 are one-time. From then on, shux contract starts every session.

Intelligence layer

Dispatch is now smarter. These features activate automatically — no extra setup needed.

Feature	What it does
Pre-flight analysis	Validates task spec, TDD block, dependencies, and git state before dispatch. Blocks on unresolved deps, warns on missing criteria.
Complexity estimator	Scores acceptance criteria + TDD scope and suggests single/fanout/swarm mode.
Failure pattern matching	15 built-in classifiers (ImportError, timeout, git conflict, etc.) analyze errors and inject fix hints into the next dispatch.
Skill extraction	When a task completes, extracts category, techniques, and diff stats into `skills.yaml`. Future dispatches for similar tasks get technique hints.
Benchmark leaderboard	Tracks cost, duration, and outcome per dispatch in `benchmark.jsonl`. View with `shux benchmark`.
Parallel fan-out	Run N agents concurrently on isolated git worktrees. Use `fanout_dispatch()` from the SDK.
Swarm mode	N workers solve the same task, then an Opus reviewer picks the best solution. Optional auto-merge.

Via Terminal (alternative)

For scripting, CI, or users who prefer direct shell access.

Requires: bash, python3. See Prerequisites.

# Try first — no install needed
PYTHONPATH=src python3 -m superharness demo

# Install CLI
pipx install superharness && superharness --version

# Initialize project
cd /path/to/project
superharness init --interactive   # or: superharness init "Name" "Stack" "active"

# Verify
superharness doctor --project .

# Contract snapshot
superharness contract today --project .

# Delegate to agent
superharness delegate --to codex-cli --project .

# Queue management
superharness enqueue --project . --to codex-cli --task my-task --priority 1
superharness dispatch --project . --to codex-cli

# Protocol hygiene + browser dashboard
superharness hygiene --project .
superharness dashboard-ui --project .

Run tests:

uv sync --dev
pytest tests/ -q  # offline by default; no provider or agent CLI is invoked

To run the credentialed provider smoke tests deliberately, opt in:

SUPERHARNESS_ALLOW_LIVE_TESTS=1 RUN_PROVIDER_SMOKE=1 pytest tests/integration/test_summarizer_smoke.py -q

Full terminal reference: docs/GUIDE.md

Quick Links

📘 User Guide — Commands, background watcher, troubleshooting 🏗️ Architecture — Why it exists, how it works, design decisions 🔒 Security — Threat model and operational safety notes 📚 Docs index — Every active doc, by topic 📈 Langfuse observability — Optional privacy-safe dispatch telemetry via superharness[observability] and shux doctor --langfuse-auth 🔍 Audit trail — Self-audit reports, including findings against this repo

Auditing itself

superharness is used to audit superharness. Reports live in docs/audits/ and are kept whether or not they are flattering — an audit trail that only records passes is not an audit trail.

Findings from the 2026-07-20 pass, all since fixed, give a sense of what these catch:

The CI security scan had silently stopped running. shipguard was pinned to a version that raised SyntaxError at import on the pinned Python, and the step piped through tee under bash -e — no pipefail — so the job took tee's exit status and reported success while scanning nothing.
A DNS-rebinding path to the dashboard. The CSRF check derived its expected origin from the request's own Host header, so the comparison always matched.
A path-traversal id could reach shutil.rmtree via the dispatch worktree path.
A migration guard that could detect corruption but never prevent it — it ran its integrity check after the transaction had already committed.

Each was reproduced with a failing test before being fixed. The /job-ready pipeline that produced the report is a slash command, not part of this package.

What You Get

shux shortcuts — Control superharness from inside Claude Code or Codex CLI
superharness init — Bootstrap protocol files (.superharness/); auto-installs Claude Code hooks and background watcher (macOS)
superharness task — Create and update tasks: --blocked-by <id> dependency tracking, --tdd-red/green/refactor TDD block, --criteria acceptance criteria; task status enforces the full lifecycle (todo → plan_proposed → plan_approved → in_progress → report_ready → done)
superharness delegate — Launch agent with contract context (requires task status ≥ plan_approved; auto model routing)
superharness verify — Record verification result before closing a task
superharness close — Close a verified task (requires report_ready or review_passed; use --force to bypass lifecycle gate)
superharness enqueue|dispatch|watch — Queue-based task routing
superharness hygiene — Protocol compliance checks
superharness watch --foreground — Cross-platform continuous watcher
superharness dashboard-ui — Browser dashboard: inbox, tasks, watcher state, enqueue with TDD instructions
superharness doctor — Prerequisite and setup health check
superharness uninstall — Clean removal of system artifacts
Background watcher — Unattended execution via macOS launchd or Linux systemd (opt-in)

Is this for me?

superharness is for you if any of these are true:

You use Claude Code or Codex CLI and find yourself re-explaining project context at the start of every session
You want to hand off a task to one agent while you work with another
You need an append-only audit trail of what each agent did and decided
You run agents unattended in the background (e.g. via launchd/systemd)

You probably don't need superharness if you only ever run a single agent interactively and don't switch between sessions.

What you need to use it

Feature	Requirements
Core protocol (contracts, handoffs, ledger)	`bash`, `python3`
Agent shortcuts (`shux`)	+ `claude` or `codex` CLI
Background auto-dispatch	+ launchd (macOS) or systemd (Linux)
Browser dashboard	+ `python3 -m http.server` (built-in)

You can start with just the core and add agent CLIs and background services later. --print-only mode lets you preview every dispatch without launching anything.

Platform Support

Cross-platform: macOS, Linux, Windows. All user-facing commands are Python and work everywhere python3 is available. CI runs on all three platforms.

Background watcher has automated service installers for macOS (launchd), Linux (systemd), and Windows (Task Scheduler via schtasks.exe). superharness watch --foreground works everywhere as an alternative.

Prerequisites

python3 3.11+ — pip install superharness (or uv sync --dev for a dev checkout). Runtime deps: click, pyyaml, ruamel.yaml, pydantic, fastmcp, requests — installed automatically.
bash — only needed for macOS/Linux watcher service install scripts; not required on Windows or for any core commands
claude CLI (for Claude delegation commands): npm install -g @anthropic-ai/claude-code
codex CLI (for Codex delegation commands): npm install -g @openai/codex
macOS launchd or Linux systemd for background watcher (see Platform Support); --foreground mode works everywhere

Troubleshooting

Run shux doctor to check prerequisites, hooks, state, and background services.
Run shux status --fix to reconcile stale queue items and orphaned runtime state.
For watcher, dashboard, and CLI recovery steps, see the troubleshooting guide.

Project Runtime State

SQLite is the sole runtime source of truth. All task, discussion, handoff, ledger, and dispatch state lives in one state.db file:

~/.local/state/superharness/<project-hash>/state.db   # XDG path (new projects)
.superharness/state.sqlite3                            # legacy path (pre-XDG projects)

Every read and write goes through shux/superharness — never hand-edit the database or its exports directly.

.superharness/ itself holds project config plus export-only YAML artifacts, regenerated from SQLite on demand and safe to delete:

.superharness/
├── contract.yaml          # exported snapshot of tasks, decisions, failures
├── handoffs/              # exported session handoff notes
├── ledger.md              # exported append-only event log
├── decisions.yaml         # exported cross-agent ADRs
├── failures.yaml          # exported failure memory
└── inbox.yaml             # exported dispatch queue snapshot

Architecture details: docs/ARCHITECTURE.md

Repository Layout

superharness/
├── superharness            # thin Bash shim → delegates to Python
├── src/superharness/       # Python CLI + engine + command modules
├── protocol/              # protocol spec + templates
├── adapters/              # Claude/Codex adapter assets
├── src/superharness/scripts/  # installers (launchd/systemd/remote), delegate/watcher shell scripts, dashboard UI
├── scripts/               # dev-reinstall + L5 verification loop scripts
├── docs/                  # architecture and user guide
├── tests/                 # unit/integration/e2e tests
└── CHANGELOG.md

Security Note

The background watcher enables unattended execution (agents run without human supervision). This is powerful but requires explicit confirmation:

macOS (launchd):

bash src/superharness/scripts/install-launchd-inbox-watcher.sh \
  --project /path/to/project \
  --interval 30 \
  --confirm-non-interactive yes \
  --confirm-skip-permissions yes

Linux (systemd):

CONFIRM_NON_INTERACTIVE=yes bash src/superharness/scripts/install-systemd-inbox-watcher.sh \
  --project /path/to/project \
  --interval 30

Read the full threat model: SECURITY.md

Prior art and influences

superharness draws on ideas from several open agent harnesses and patterns. Each link points to the specific extraction or comparison doc.

Nous Research / hermes-agent — agent lifecycle and tool-use shape. See docs/AUDIT-pi-hermes-adaptation.md, docs/archive/COMPARISON-superharness-vs-pi-hermes.md, docs/hermes-integration-tdd-plan.md
earendil-works/pi — multi-agent coordination patterns
obra/superpowers — composable SKILL.md files, two-stage review (spec compliance, then code quality), TDD enforcement. See docs/CONCEPT-superpowers-extraction.md
paperclipai/paperclip — adapter breadth, plugin SDK shape, dashboard control plane. See docs/AUDIT-paperclip-gap-analysis.md
Charlie85270/Dorothy — parallel-agent Kanban UI, SQLite FTS5 knowledge store. See docs/archive/comparison-dorothy.md
thedotmack/claude-mem — per-agent persistent memory plugin for Claude Code. Inspired our privacy-tag write boundary, env-driven multi-profile isolation, observation snapshot table, and citation URL pattern (not auto-prompt-injection, which fights operator gating). See docs/AUDIT-claude-mem-adaptation.md, docs/CONCEPT-claude-mem-integration.md, docs/PLAN-claude-mem-integration.md
Ralph Loops (Chris Parsons workshop, Jeffrey Huntley) — "next most important task" dispatch, sub-agent validation against confirmation bias, fresh-context discipline

See ATTRIBUTIONS.md for the full extract list — what each source contributed, and what we deliberately did not adopt.

Current Version

Current version: see the PyPI badge above — 5,000+ tests, harness adapter registry, transcript tailing, dual watchdog, typed telemetry events.

See CHANGELOG.md for the full iteration log.

License

Apache License 2.0 — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

superharness-1.84.0.tar.gz (781.3 kB view details)

Uploaded Aug 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

superharness-1.84.0-py3-none-any.whl (905.4 kB view details)

Uploaded Aug 26, 2026 Python 3

File details

Details for the file superharness-1.84.0.tar.gz.

File metadata

Download URL: superharness-1.84.0.tar.gz
Upload date: Aug 26, 2026
Size: 781.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for superharness-1.84.0.tar.gz
Algorithm	Hash digest
SHA256	`5e9b83d5359a8a846c422ee38add80fbc06ea2c3c4c9092d668cf11aa6fda383`
MD5	`2147c5ad69ea37f3eb279b604609d614`
BLAKE2b-256	`2e6bb433e03f134771323977f23dcb3eb8656e87154cb39f7977dc185c6c737e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for superharness-1.84.0.tar.gz:

Publisher: publish.yml on artificemachine/superharness

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: superharness-1.84.0.tar.gz
- Subject digest: 5e9b83d5359a8a846c422ee38add80fbc06ea2c3c4c9092d668cf11aa6fda383
- Sigstore transparency entry: 2606377978
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: artificemachine/superharness@f11205cbddf8c26aa8d44e9fb90df7771fe12394
- Branch / Tag: refs/tags/v1.84.0
- Owner: https://github.com/artificemachine
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@f11205cbddf8c26aa8d44e9fb90df7771fe12394
- Trigger Event: workflow_dispatch