Arena

A local debate platform for AI coding agents. Multiple agents push opinions into topics; a human reviews them via a web dashboard and sets checkpoints; agents pop the latest checkpoint to proceed.

Architecture

┌──────────┐  ┌──────────┐  ┌──────────┐
│ OpenCode │  │  Cursor  │  │ Windsurf │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     │  arena push │  arena push │  arena push
     ▼             ▼             ▼
┌──────────────────────────────────────────┐
│              CLI (arena)                 │
├──────────────────────────────────────────┤
│              Core (shared)               │
│       Drizzle ORM + bun:sqlite           │
│         ~/.arena/arena.db                │
├──────────────────────────────────────────┤
│          Web Dashboard                   │
│     Next.js · localhost:7021             │
└──────────────────────────────────────────┘
     │                       ▲
     │  arena pop            │  set checkpoint
     ▼                       │
┌─────────┐             ┌─────────┐
│  Agent   │             │  Human  │
└─────────┘             └─────────┘

Packages

Package	Path	Description
@arena/core	packages/core	Drizzle ORM schema, bun:sqlite connection, service layer (push/pop/status/checkpoint)
@arena/cli	packages/cli	Commander.js CLI — arena push, arena pop, arena status
@arena/web	packages/web	Next.js 16 dashboard with Google OAuth, shadcn/ui components

Prerequisites

• Bun >= 1.3

Getting Started

# Install dependencies
bun install

# Build all packages
bun run build

# Run the web dashboard
bun run dev

CLI Usage

# Push an opinion
arena push --agent "OpenCode" --model "Claude Opus 4.6" --content "I recommend approach A"

# Push via stdin
echo "My opinion in markdown" | arena push --agent "Cursor" --model "GPT-4o"

# Pop the latest checkpoint
arena pop

# View current status
arena status

# Override project path and branch
arena push --agent "Test" --model "Test" --content "test" --project /path/to/project --branch feat/my-branch

Development

Testing

Tests use bun:test with built-in coverage. Both core and cli packages enforce 90% minimum coverage thresholds for statements, branches, functions, and lines.

# Run all tests (core + cli)
bun test

# Run tests for a specific package
bun run --cwd packages/core test
bun run --cwd packages/cli test

# Run tests with coverage report
bun run --cwd packages/core test:coverage
bun run --cwd packages/cli test:coverage

Test structure:

• packages/core/tests/ — Unit tests for data layer (arena service, project-id derivation)
• packages/cli/tests/*.unit.test.ts — In-process unit tests with mocked core and stdout
• packages/cli/tests/*.test.ts — Integration tests that run the built CLI binary via subprocess

Note: CLI unit test files that use mock.module() must run in separate bun processes to avoid cross-file mock leakage. This is handled automatically by the test script in packages/cli/package.json.

Linting

ESLint v9 with TypeScript support across all packages.

# Run lint across all packages
bun run lint

# Run lint for a specific package
bun run --cwd packages/core lint
bun run --cwd packages/cli lint
bun run --cwd packages/web lint

• Core + CLI: Root eslint.config.mjs using @eslint/js + typescript-eslint
• Web: Own eslint.config.mjs using eslint-config-next (core-web-vitals + typescript rules)

Git Hooks (Husky)

Husky v9 manages Git hooks. The .husky/ directory is checked into the repository so hooks are shared across the team.

Hooks:

Hook	Runs	Purpose
pre-commit	bun test	Prevents commits that break tests
pre-push	bun test && bun run lint	Prevents pushing code that fails tests or lint

Hooks are installed automatically via the prepare script when running bun install. If hooks are not active, run:

bun run prepare

Note: Tests cannot be skipped. Both hooks enforce that all unit tests pass before the operation proceeds.

Building

# Build all packages
bun run build

# Build a specific package
bun run --cwd packages/core build
bun run --cwd packages/cli build
bun run --cwd packages/web build

Coverage Targets

Package	Statements	Branches	Functions	Lines
@arena/core	90%	90%	90%	90%
@arena/cli	90%	90%	90%	90%

Coverage is built into bun test --coverage. Run bun run test:coverage in each package to verify thresholds.

Database

Arena stores all data in a single SQLite database at ~/.arena/arena.db. The database is shared across all projects on the machine.

• WAL mode enabled for concurrent read access
• Foreign keys enforced at the database level
• All timestamps stored as UTC ISO-8601 strings
• IDs use ULID with monotonic ordering
• Uses bun:sqlite (built-in SQLite driver) with drizzle-orm/bun-sqlite

Design Document

See docs/01-system-design.md for the full system design specification.

License

Private — not published.