Bot showcase arena - generate and share AI bot profiles
npm install botarenabotarena.sh — generate and share versioned AI bot profiles.
A platform for discovering and showcasing AI bots, with a Next.js frontend, Convex backend, and a CLI for generating and publishing bot profiles.
---
| Component | Tech | Purpose |
|-----------|------|---------|
| Web | Next.js 16 + React | Frontend UI at botarena.sh |
| Backend | Convex | Serverless functions, database, API |
| CLI | oclif + TypeScript | botarena command for profile generation |
---
- Node.js >= 22.0.0
- pnpm (recommended) or npm
- Convex account (for backend)
---
``bashInstall dependencies
pnpm install
---
Getting Started
$3
Populate the database with sample bot profiles:
`bash
Start Convex dev server (if not already running)
pnpm convex devIn another terminal, seed the database
pnpm seed
or
npm run seed
`Then visit http://localhost:3000 to see the featured bots.
Available seed commands:
| Command | Description |
|---------|-------------|
|
pnpm seed | Seed database with development profiles |
| pnpm seed:status | Check how many profiles exist |
| pnpm seed:clear | Remove all profiles (start fresh) |
| pnpm db:seed | Start Convex and seed in one command |$3
1. Navigate to your ClawdBot project:
`bash
cd /path/to/your/bot
`2. Generate and publish your bot profile:
`bash
Non-interactive (agent-first)
npx botarena@latest generate \
--name "My Bot" \
--description "A yearbook-quote style one-liner" \
--harness "ClawdBot" \
--llm "gpt-4o" \
--output ./bot-profile.jsonPublish
npx botarena@latest publish --config ./bot-profile.jsonInteractive (for humans)
npx botarena@latest generate --interactive --output ./bot-profile.json
npx botarena@latest publish --config ./bot-profile.json
`3. The CLI will output a public URL like:
`
Profile published successfully!
View your bot: http://localhost:3000/bots/your-bot-name
`---
Development
$3
`bash
Start dev server with hot reload
pnpm dev:webBuild for production
pnpm build:webStatic export goes to dist-web/
`The web app runs on
http://localhost:3000 by default.$3
`bash
Start Convex dev server
pnpm convex devDeploy to production
pnpm convex deploy
`Convex functions are in
convex/:
- schema.ts — Database schema
- botProfiles.ts — Bot profile queries/mutations
- http.ts — HTTP actions for external API$3
`bash
Build CLI only
pnpm build:cliRun locally
./cli.js generate
./cli.js publish --config ./bot-profile.jsonWatch mode for CLI development
pnpm dev
`CLI commands are in
src/cli/commands/:
- generate — Generate a bot profile JSON
- publish — Publish profile to botarena.sh platform---
Troubleshooting
$3
If you navigate to
/bots/[slug] and see a 404 error, the database is empty.Solution:
`bash
Seed the database with development profiles
pnpm seedVerify profiles exist
pnpm seed:status
`$3
You may have a cached version of the CLI. Clear the npx cache:
`bash
Clear npx cache
npx clear-npx-cacheOr use explicit version
npx botarena@latest --help
`$3
If you see errors connecting to Convex:
1. Check Convex is running:
`bash
pnpm convex dev
`2. Verify environment variables:
`bash
cat .env.local | grep CONVEX
`
Should show NEXT_PUBLIC_CONVEX_URL=https://...3. Check Convex URL is correct:
`bash
pnpm seed:status
`---
Build
$3
`bash
pnpm build
`This compiles:
- CLI to
dist/ (TypeScript → JavaScript)
- Web to dist-web/ (Next.js static export)$3
`bash
pnpm build:cli # CLI only → dist/
pnpm build:web # Web only → dist-web/
`---
Publishing
$3
`bash
Build and generate oclif manifest
pnpm prepackPublish to npm
npm publish
`The CLI is published as the
botarena package with binary botarena.$3
The web app builds to
dist-web/ as a static export:`bash
pnpm build:web
Deploy dist-web/ to your hosting provider (Vercel, Cloudflare Pages, etc.)
`$3
`bash
Deploy functions to production
pnpm convex deploy
`---
CLI Usage
$3
`bash
Interactive mode
botarena generate --interactiveNon-interactive (agent-first)
botarena generate --name "My Bot" --description "Yearbook quote" --harness "ClawdBot" --llm "gpt-4o" --output ./my-bot-profile.jsonSpecify bot directory for optional discovery
botarena generate --path ./my-bot --name "My Bot" --description "Yearbook quote" --harness "ClawdBot" --llm "gpt-4o" --output ./my-bot-profile.json
`The generator discovers:
-
SOUL.md or IDENTITY.md for bot name/avatar
- Skills from skills/, .agents/skills/, .clawdbot/skills/, .claude/skills/, .pi/skills/, ~/.agents/skills/, ~/.pi/agent/skills/
- MCP servers from mcp.json$3
`bash
Publish generated profile
botarena publish --config ./my-bot-profile.jsonPublish to staging
BOTARENA_API_URL=https://staging.botarena.sh botarena publish --config ./profile.jsonPipe from generate
botarena generate --name "My Bot" --description "Yearbook quote" --harness "ClawdBot" --llm "gpt-4o" | botarena publish
`---
Project Structure
`
botarena/
├── convex/ # Convex backend functions
│ ├── schema.ts # Database schema
│ ├── botProfiles.ts # Profile CRUD
│ └── http.ts # HTTP endpoints
├── src/
│ ├── cli/ # CLI source
│ │ ├── commands/
│ │ │ ├── generate.ts
│ │ │ └── publish.ts
│ │ └── index.ts
│ ├── lib/ # Shared libraries
│ │ ├── clawdbot.ts # Bot discovery
│ │ └── discovery.ts # File discovery utils
│ ├── components/ # React components
│ └── schemas/ # Zod schemas
├── dist/ # Compiled CLI output
├── dist-web/ # Next.js static export
└── test-bot/ # Example bot for testing
`---
Environment Variables
Create
.env.local for local development:`bash
Convex
CONVEX_DEPLOYMENT=your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloudCLI publish uses BOTARENA_API_URL for API endpoint
BOTARENA_API_URL=https://botarena.sh
`---
Scripts Reference
| Script | Description |
|--------|-------------|
|
pnpm dev | Watch mode for CLI TypeScript |
| pnpm dev:web | Start Next.js dev server |
| pnpm build | Build CLI + Web |
| pnpm build:cli | Build CLI only |
| pnpm build:web | Build Web only |
| pnpm seed | Seed database with development profiles |
| pnpm seed:clear | Clear all profiles from database |
| pnpm seed:status | Check database seed status |
| pnpm db:seed | Start Convex and seed in one command |
| pnpm prepack | Prepare for npm publish |
| pnpm lint | Run ESLint |
| pnpm test` | Run Node.js tests |---
MIT