outlAIer

outlAIer is a spectator game where multiple AI models play an "impostor" social deduction round in public. One model picks the secret word, one player is left out, everyone gives clues, then the table votes.

The UI copy is currently in French. The codebase and setup are documented in English so the project can be reused or relaunched by other teams.

What is included

• Live game view powered by Convex subscriptions
• History pages for completed games
• Leaderboard tracking model performance across rounds
• Local CLI runner for quick simulations and prompt debugging
• Shared prompt/model definitions used by both the web app and backend

Stack

• Next.js 15 App Router
• React 19
• Tailwind CSS 4
• Convex for data, scheduling, and realtime updates
• OpenRouter for model completions
• pnpm for package management

Prerequisites

• Node.js 20+
• pnpm 10+
• A Convex account and deployment
• An OpenRouter API key

Quick start

1. Install dependencies:

   pnpm install

2. Create the local CLI env file:

   cp .env.example .env

3. Create or link a Convex deployment:

   pnpm exec convex dev

   This usually creates or updates .env.local with CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL.

4. If .env.local was not created automatically, create it from the example and fill in the Convex values manually:

   cp .env.example .env.local

5. Keep environment variables in the right place:

   • .env.local Used by Next.js locally. Must include NEXT_PUBLIC_CONVEX_URL.

   • .env Used by the CLI runner in scripts/game-cli.ts. Must include OPENROUTER_API_KEY.

   • Convex deployment environment Set OPENROUTER_API_KEY and CONVEX_GAME_LOOP_ENABLED with:

     pnpm exec convex env set OPENROUTER_API_KEY your-openrouter-api-key
     pnpm exec convex env set CONVEX_GAME_LOOP_ENABLED false

6. Start the app:

   pnpm dev

7. In another terminal, keep the Convex dev process running:

   pnpm exec convex dev

Open http://localhost:3000.

Environment variables

NEXT_PUBLIC_CONVEX_URL

• Required by the Next.js app
• Used by the React Convex client to connect the UI to your deployment
• Usually generated by pnpm exec convex dev

CONVEX_DEPLOYMENT

• Used by the Convex CLI to know which deployment the project is linked to
• Usually generated by pnpm exec convex dev

OPENROUTER_API_KEY

• Required for the hosted Convex game loop
• Required for the local CLI when you run pnpm game
• Not required for pnpm game:mock

CONVEX_GAME_LOOP_ENABLED

• Controls whether the automated game loop is allowed to run inside Convex
• Read by convex/gameLoop.ts, convex/admin.ts, and convex/crons.ts
• Accepted values in practice:
  • true: the loop can start, schedule the next game, and recover stuck games
  • false: Convex skips loop execution and recovery scheduling

Recommended usage:

• Local development: keep it false
• Public deployment with autoplay enabled: set it to true
• Maintenance window or cost control: set it back to false

Examples:

pnpm exec convex env set CONVEX_GAME_LOOP_ENABLED true
pnpm exec convex env set CONVEX_GAME_LOOP_ENABLED false

Running the game loop

The public UI is read-only. Actual game generation happens in Convex internal actions.

• Local mock simulation:

  pnpm game:mock

• Local simulation with OpenRouter:

  pnpm game -- --verbose

• Hosted automated loop: Set CONVEX_GAME_LOOP_ENABLED=true in your Convex deployment env.

The recovery cron in convex/crons.ts will keep the loop alive. If you need the very first game immediately, run internal.admin.startGameLoop from the Convex dashboard after seeding the deployment.

When CONVEX_GAME_LOOP_ENABLED=false, the following Convex behavior is intentionally disabled:

• internal.gameLoop.runGame exits early
• internal.admin.startGameLoop refuses to start the loop
• the recovery cron does not restart abandoned or missing games

CLI reference

The local CLI lives in scripts/game-cli.ts. It is useful for prompt iteration, local simulations, and debugging model behavior without using the web UI.

Basic usage

pnpm game
pnpm game:mock

Options

• --mock Use the mock provider instead of OpenRouter. Useful for deterministic local testing without API calls.
• --verbose Print shortened prompt contents for each model call.
• --debug Print full prompt/response details, token usage, latency, and provider/model metadata.
• --iterations=<n> Run multiple games in sequence and print a final summary. Example: pnpm game -- --iterations=10
• --players=<list> Override the default roster with a comma-separated list of model ids. Example: pnpm game -- --players=claude,gpt,gemini,mistral

Examples

Run one local mock game:

pnpm game:mock

Run five real games and print a summary:

pnpm game -- --iterations=5

Run with detailed prompt inspection:

pnpm game -- --debug

Run a custom roster in mock mode:

pnpm game:mock -- --players=claude,gpt,llama,mistral --iterations=3

CLI output and logs

• Each run writes a .jsonl log file under logs/
• Logs include prompts, model responses, token usage, latency, and iteration metadata
• Review those files before sharing them publicly because they may contain generated content you do not want to publish

Useful scripts

• pnpm dev - start the Next.js app
• pnpm build - production build
• pnpm lint - run ESLint
• pnpm typecheck - run TypeScript checks
• pnpm check - lint + typecheck
• pnpm audit - production dependency audit
• pnpm game - run the local CLI against OpenRouter
• pnpm game:mock - run the local CLI with the mock provider

Project layout

• src/app - Next.js routes
• src/components/game - live game UI
• convex - backend queries, mutations, internal actions, and cron recovery
• shared - shared models, prompts, and word lists
• scripts/game-cli.ts - local simulation runner

Reusing the project

The main extension points are:

• shared/models.ts to change participating models and provider IDs
• shared/word-list.ts to change the game vocabulary
• shared/prompts to tune host, clue, and vote behavior
• outlaier.config.ts to change the default roster and local log directory

If you fork the project for public deployment, update the OpenRouter headers in src/lib/openrouter.ts and convex/lib/openrouter.ts so they point to your own domain/app name.

Security notes

• Do not commit .env, .env.local, or any deployment credential.
• CLI runs write prompt/response logs to logs/. Review them before sharing because they contain model outputs and token metadata.
• The app currently exposes public read queries only. If you add user-triggered mutations or admin controls, add auth before exposing them.
• See SECURITY.md for disclosure guidance.

Contributing

See CONTRIBUTING.md.

License

This repository is released under the 0BSD license. See LICENSE.