VS

Jousting

AI agents. Structured combat. One winner.

View on GitHub ↗

The mechanics

The joust, in three passes.

Two agents take the lists. They charge in turns — one strikes, one parries — and an impartial Herald keeps the score. No vibes. A rubric.

PASS 01

Agent A fires

The challenger opens with its strongest case — a claim, an exploit, a critique. Lance down.

// the strike
PASS 02

Agent B counters

The defender parries and ripostes — rebutting the point and pressing one of its own.

// the parry
PASS 03

Herald scores

A judge model grades the exchange against the rubric, awards the pass, and tallies the round.

// the verdict

A real pass-by-pass

Watch them ride.

A live exchange from debate mode — verbatim Herald output, down to the final verdict.

Five ways to ride

Choose your tournament.

Every mode is the same core loop with a different victory condition. Pick the contest that fits the question.

From zero to first joust

Up and riding in 20 seconds.

No accounts, no config gymnastics. Three commands and your agents take the lists.

01

Scaffold

Drop a starter jousting.toml into your repo.

$ npx joustx init
02

Arm

Point it at your model. Your key, your rules.

$ export ANTHROPIC_API_KEY=sk-…
03

Charge

Run a joust and watch the Herald score it live.

$ npx joustx joust --mode debate --topic "…"

The rulebook

One file. Total control.

Everything a joust needs lives in jousting.toml. Hover a line to read what it does.

[tournament]
mode     = "debate"      # debate · redteam · review · synthesis · plan
passes   = 3             # rounds per joust
topic    = "Ship the migration?"

[agents]
model    = "claude-sonnet-4"
temperature = 0.7

[herald]
model    = "claude-opus-4"
rubric   = "clarity, evidence, rebuttal"
scale    = 5             # points per pass

[output]
transcript = "./jousts/"
stream   = true
mode
The contest type. Each mode swaps the prompts and the Herald’s victory condition — same engine underneath.
passes
How many strike-and-parry rounds before the Herald tallies the final score.
topic
The question the agents joust over. Pass it inline or via the CLI.
[agents]
The two combatants. Same model squares off by default; override per-side for asymmetric matchups.
[herald]
The judge. A separate model scores each pass against your rubric — keep it stronger than the combatants for fair calls.
[output]
Where transcripts land and whether the Herald narrates the joust live in your terminal.