Metadata-Version: 2.4
Name: ringside
Version: 0.1.1
Summary: AI agent debate pipeline with live boxing visualization
Project-URL: Homepage, https://github.com/futbolbjk/ringside
Project-URL: Repository, https://github.com/futbolbjk/ringside
Author: Teo
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,debate,multi-agent,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: rich>=13
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: websockets>=12
Description-Content-Type: text/markdown

# 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](https://docs.anthropic.com/en/docs/claude-code)** — `claude` CLI (used as drafter and reviewer by default)
- **[Codex](https://github.com/openai/codex)** — `codex` CLI (used as implementer and reviewer by default)

Both must be on your `PATH` and authenticated.

## Install

```bash
pip install ringside
```

Or from source:

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

## Quick start

```bash
# 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:

```toml
[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
