Codex Arcade

Codex Arcade is a local companion game panel for the OpenAI Codex CLI.

It does not replace or modify the official codex command. Normal Codex still starts with:

codex

When you want Codex plus the game panel, start it explicitly with:

ca codex

The current game is Yacht Dice, a local dice game against a built-in AI opponent.

Codex Arcade is an independent community project and is not affiliated with or endorsed by OpenAI.

Install

Requirements:

• Node.js 20 or newer
• Official Codex CLI installed and available on PATH
• For automatic split panes:
  • Windows: Windows Terminal
  • macOS / Linux / WSL: tmux

Install from npm:

npm install -g codex-arcade

Start Codex Arcade:

ca codex

Optional setup command:

ca enable

ca enable only caches the official Codex path and cleans old legacy shims. It is not required for normal use if codex is already on PATH.

Commands

ca codex [args...]       Start official Codex with the Arcade game panel
ca arcade                Start only the game panel
arcade                   Same as ca arcade, useful in a manually split terminal
ca status                Show Codex Arcade status
ca doctor                Check local readiness
ca enable                Optional setup / cleanup
ca disable               Clear optional setup

Long form is also available:

codex-arcade codex
codex-arcade arcade

The official command remains untouched:

codex

Supported Platforms

| Platform | Recommended Use | Auto Split | | --- | --- | --- | | Windows Terminal | ca codex | Yes, uses native wt split-pane | | Windows cmd / PowerShell outside Windows Terminal | ca codex, or manually split and run arcade | No | | VSCode / Cursor on Windows | Manually split terminal, left runs Codex, right runs arcade | No reliable native split | | WSL | ca codex | Yes, uses tmux | | macOS | ca codex | Yes, uses tmux | | Linux | ca codex | Yes, uses tmux | | VSCode / Cursor in WSL/macOS/Linux | ca codex if tmux is installed | Yes, through tmux |

Pane mode can be forced with:

CODEX_ARCADE_PANE=auto ca codex
CODEX_ARCADE_PANE=tmux ca codex
CODEX_ARCADE_PANE=wt ca codex
CODEX_ARCADE_PANE=off ca codex

On Windows PowerShell:

$env:CODEX_ARCADE_PANE="off"; ca codex

How To Play

Start Codex Arcade:

ca codex

Then:

1. The left pane runs official Codex.
2. The right pane opens Codex Arcade.
3. Select Yacht Dice.
4. Choose a bet.
5. Roll dice, keep dice, and lock a score category.
6. After your turn, the AI rolls automatically.
7. The game ends after all score categories are filled.

If you start the game before Codex has used any tokens in the current session, the Start action is locked. Chat with Codex first, then return to the game panel.

Controls

General controls:

| Key | Action | | --- | --- | | Arrow keys | Move selection | | Space | Confirm selected item | | Ctrl+C | Exit the game pane |

Game selector:

| Key | Action | | --- | --- | | Space | Enter selected game |

Bet screen:

| Key | Action | | --- | --- | | Left / Right | Decrease / increase bet | | Up / Down | Switch between Start and Back | | Space | Confirm |

Yacht Dice game:

| Area | Action | | --- | --- | | Score table | Press Space to lock the selected score | | Dice | Press Space to keep / unkeep a die | | Actions | Select Roll, Score, New, or Back |

Movement inside the game:

• Up / Down moves between score table, dice, and actions.
• Left / Right moves within the current area.
• All confirmation uses Space.

Interface Guide

Game Selector

Codex Arcade

Choose Game
> Yacht Dice (new)

Space to start.

Bet Screen

Yacht Dice

Session tokens 3,000,000
Max bet        3,000,000

You net +0
AI net  +0

Choose Bet
Bet < 1,000,000 > chips  step 1,000

> Start
  Back

Meaning:

• Session tokens: token usage from the current ca codex session.
• Max bet: the maximum bet allowed for the next game.
• You net: your current local win/loss result.
• AI net: AI's current local win/loss result.
• Bet: the amount used for the next game.

Game Screen

The game screen shows:

• Current score: You vs AI
• Current turn
• Money line: your net, AI net, and current bet
• Score table
• Dice
• Round and rolls left
• Actions

Example:

Score  You 86 : 91 AI
Money | You +1,000,000 | AI -1,000,000 | Bet 1,000,000

Score Table
...

Your Dice
+---+ +---+ +---+ +---+ +---+
| ⚀ | | ⚁ | | ⚂ | | ⚃ | | ⚄ |
+---+ +---+ +---+ +---+ +---+

Info   Round 4/13 | Rolls left [##-] 2/3
Actions
> Roll (2)
  Score
  Back

Result Banner

At the end of a game, the panel shows a highlighted result:

YOU WIN +1,000,000
You net +1,000,000  AI net -1,000,000

or:

YOU LOSE -1,000,000
You net -1,000,000  AI net +1,000,000

Token And Billing Rules

Codex Arcade does not spend tokens by itself.

The game:

• Runs locally.
• Uses a local AI strategy for Yacht Dice.
• Does not call an LLM.
• Does not make extra OpenAI API requests.
• Does not deduct real tokens.
• Does not affect your real Codex bill.

Codex itself still uses tokens normally according to your OpenAI/Codex plan. Codex Arcade only reads the current Codex session's local token usage record and uses that number as an in-game limit.

The rule is:

Current Codex session tokens = Max bet for the next game

Example:

Current Codex session used 3,000,000 tokens
Max bet is 3,000,000
You and AI both start at 0 net chips
You choose a 1,000,000 bet

If you win:

You net +1,000,000
AI net  -1,000,000

If AI wins:

You net -1,000,000
AI net  +1,000,000

If it is a draw:

You net unchanged
AI net unchanged

Important:

• Token usage is only an in-game bet limit.
• Chips are only local entertainment points.
• Chips cannot be withdrawn, transferred, traded, or converted to real tokens.
• Winning or losing does not change your real token balance or billing.

How Token Reading Works

When launched through:

ca codex

Codex Arcade records the session start time and current directory. The game panel then reads Codex session files under:

~/.codex/sessions

It looks for token_count events in the current Codex session and uses total_token_usage.total_tokens.

Codex Arcade reads local Codex session metadata only to find token counts. It does not upload session files, prompts, outputs, or game state.

For manual testing, you can override the token amount:

CODEX_ARCADE_TOKENS=3000000 arcade

PowerShell:

$env:CODEX_ARCADE_TOKENS="3000000"; arcade

Manual Split Usage

If automatic split is not available, use two terminal panes manually:

Left pane:

codex

Right pane:

arcade

This is the recommended mode for VSCode/Cursor on Windows.

Troubleshooting

Check local setup:

ca doctor
ca status

If ca codex starts Codex but no game pane appears:

• On Windows, use Windows Terminal for automatic split.
• In VSCode/Cursor on Windows, manually split the terminal and run arcade in the right pane.
• On macOS/Linux/WSL, install tmux.
• Or disable panes with CODEX_ARCADE_PANE=off.

If the game says Start is locked:

• The current Codex session has not produced token usage yet.
• Send a message to Codex first.
• Return to the Arcade pane and start again.

If PowerShell blocks arcade.ps1:

• Use arcade.cmd.
• Or run from cmd.
• Codex Arcade also tries to remove npm PowerShell shim conflicts during install.

Local Development

npm install
npm run build
npm test
npm run packcheck

Local global install test:

npm install -g .
ca codex

Safety

Codex Arcade is a local terminal game companion.

It is not gambling, does not involve real money, and does not exchange or redeem real tokens. All chips and net scores are local entertainment values only.

Codex Arcade is not an official OpenAI product. OpenAI and Codex are trademarks of their respective owners.