ringside 0.1.1

AI agent debate pipeline with live boxing visualization

ringside

AI agent debate pipeline with live boxing visualization.

Ringside runs multi-agent debates where a drafter proposes a plan, reviewers critique it, and they iterate until consensus — then an implementer writes code while reviewers audit. The whole thing plays out as a live boxing match in your browser.

Prerequisites

Ringside dispatches to AI agent CLIs. You need at least one installed:

• Claude Code — claude CLI (used as drafter and reviewer by default)
• Codex — codex CLI (used as implementer and reviewer by default)

Both must be on your PATH and authenticated.

Install

pip install ringside

Or from source:

git clone https://github.com/teo/ringside.git
cd ringside
pip install -e .

Quick start

# Full end-to-end flow: brief → plan → implement → verify
# (opens the boxing viewer automatically)
ringside run

# Or if you already have a task file
ringside run .ringside/tasks/add-retry-logic.md

# Plan only, then implement later
ringside run task.md --plan-only
ringside run --continue-run .ringside/runs/20260401-100033

Commands

Command	Description
ringside run	Full flow: interactive brief, then run the pipeline with viewer
ringside run <task.md>	Run pipeline on an existing task file
ringside run <task.md> --plan-only	Plan only, skip implementation
ringside run --continue-run <run-dir>	Continue a plan-only run with implementation
ringside brief [description]	Just write a task file (no run)
ringside watch [path]	Reopen the boxing viewer for a run

How it works

1. Planning phase — A drafter (Claude) writes a plan. Reviewers (Claude + Codex) critique it. They debate until all reviewers approve or max rounds are reached.
2. Implementation phase — An implementer (Codex) edits code following the approved plan. Reviewers audit the changes. Build gates (tests, linting) run between rounds.
3. Visualization — A browser at localhost:8731 shows two CSS fighters animating in real-time: punches for drafts, counter-punches for rejections, victory poses for approval.

Per-project configuration

Ringside works out of the box with no configuration. Optionally, add these files to your project root:

.agency.toml

Override agent assignments and build gates:

[agents]
drafter = "claude"
implementer = "codex"
plan_reviewers = ["claude", "codex"]
impl_reviewers = ["codex"]

[[gates.step]]
label = "tests"
cmd = ["pytest", "-q"]

.agency-standards.md

Override the engineering standards injected into every agent prompt. Useful for domain-specific rules.

CLAUDE.md

Project context (what the codebase does, key conventions) — automatically picked up and passed to all agents so they understand your project.

Output

Runs are saved to .ringside/runs/<timestamp>/ in your working directory:

• run.json — full event log (consumed by the viewer)
• final_plan.md — the approved plan
• followup_task.md — auto-generated task for --continue-run

License

MIT