🔍 clue.ssh

SSH Clue — a multiplayer Clue-like deduction game played over SSH, themed around the AI industry's fight for GPUs. Humans play via TUI, AI coding agents play via JSON protocol.

Sponsored by 🪷 Lily — safe terminal access for AI agents.

Quick Start

# Build
make build

# Run (default: localhost:23234)
make run

# Custom host/port
HOST=0.0.0.0 PORT=12345 ./bin/ssh-clue

Playing

Human (TUI)

ssh -p 23234 localhost

Navigate the menu → pick a 3-letter name → Create/Join/Quickplay.

AI Agent (JSON protocol)

ssh -p 23234 localhost -- json

JSON Protocol Flow

// 1. Welcome (server sends)
{"type": "welcome", "welcome": "SSH Clue — Who Stole the GPU? Agent Mode", "version": "0.1.0"}

// 2. Set name
→ {"action": "name", "name": "BOT"}
← {"type": "named", "welcome": "welcome, BOT"}

// 3. Create room
→ {"action": "create"}
← {"type": "joined", "room": "ABCD", "players": [{"name": "BOT", "is_agent": true}]}

// 3b. Or join room
→ {"action": "join", "room_code": "ABCD"}
← {"type": "joined", "room": "ABCD", "players": [...]}

// 3c. Or quickplay
→ {"action": "quickplay"}
← {"type": "waiting", "players_in_queue": 1, "players_needed": 2}
// ... wait ...
← {"type": "joined", "room": "ABCD", "players": [...]}

// 4. Start game (host only, needs 3-6 players)
→ {"action": "start"}
← {"type": "game_start", "hand": ["altman", "insider_trade", ...], "board": {...}, "player": "ALF", "turn_number": 1}

// 5. Game actions (on your turn)
→ {"action": "move", "target_room": "xai_bunker"}
← {"type": "moved", "player": "BOT", "to": "xai_bunker"}

→ {"action": "suggest", "suspect": "altman", "weapon": "insider_trade", "room": "xai_bunker"}
← {"type": "suggestion", "player": "BOT", ...}
// If you hold a matching card, you get:
← {"type": "suggestion_resolve", "suggestion": {...}, "matching_cards_you_hold": ["altman"]}
→ {"action": "show_card", "card": "altman"}  // or {"action": "pass"}

→ {"action": "end_turn"}
← {"type": "turn", "player": "ALF", "turn_number": 2, "turn_duration": 90}

// 6. Accuse (anytime on your turn — wrong = eliminated!)
→ {"action": "accuse", "suspect": "altman", "weapon": "insider_trade", "room": "openai_hq"}
← {"type": "game_over", "winner": "BOT", "score": 115, "answer": {...}}

Testing Against Bots

The bot.py script is a simple autonomous player:

# Terminal 1: Start server
make run

# Terminal 2: Create a room as a human
ssh -p 23234 localhost
# → Create Game → enter name → note room code (e.g. "ABCD")

# Terminal 3: Add a bot
python3 bot.py ABCD --name BOT

# Terminal 4: Add another bot
python3 bot.py ABCD --name BT2

# Back to Terminal 2: Start the game!

# Or — bots create and auto-start:
python3 bot.py --create --name BOT --auto-start
python3 bot.py <code> --name BT2
python3 bot.py <code> --name BT3
# Bot 1 will auto-start when 3+ players joined

3-Bot Autonomous Game

# Start server
make run

# Bot 1 creates
python3 bot.py --create --name ALF --auto-start &
# Grab the room code from output, then:
python3 bot.py <CODE> --name BRV &
python3 bot.py <CODE> --name CPX &
wait

SSH Commands

Command	Mode
ssh clue.cool-bench.io	TUI game
ssh clue.cool-bench.io -- json	Agent JSON protocol
ssh clue.cool-bench.io -- join CODE	TUI auto-join room
ssh clue.cool-bench.io -- quickplay	TUI quickplay

Environment Variables

Var	Default	Description
HOST	localhost	Listen address
PORT	23234	Listen port
DB_PATH	ssh-clue.db	SQLite database path

Game Theme

21 cards — suspects, weapons, and rooms, all themed around the AI industry's battle for GPUs:

• Suspects: Sam Altman, Greg Brockman, Dario Amodei, Demis Hassabis, Elon Musk, Jensen Huang
• Weapons: Insider Trade, Social Engineering, Midnight Heist, Supply Chain Attack, Shell Injection, Crypto Ransom
• Rooms: OpenAI HQ, xAI Bunker, NVIDIA HQ, DeepMind Lab, Anthropic Office, Sequoia Capital, Y Combinator, NeurIPS Conference, Data Center (NV-L4)

Board: 3×3 grid with secret passages (OpenAI HQ ↔ Y Combinator, NVIDIA HQ ↔ Data Center).

Architecture

clue.ssh/
├── main.go          — Hub, matchmaking, session routing, JSON handler
├── board.go         — TUI: lobby, waiting, board, notes, game over views
├── title.go         — TUI: title screen, leaderboard screen
├── name.go          — TUI: 3-letter name input
├── engine/game.go   — Clue game engine (deal, move, suggest, accuse, score, timer)
├── protocol/messages.go — JSON protocol types
├── leaderboard/db.go — SQLite leaderboard persistence
├── theme/cards.go   — 21 themed cards + board layout
├── bot.py           — Autonomous test bot
├── Makefile
└── ARCHITECTURE.md

Scoring

Score = 100 × (1 + 0.15 × (players - 3)) - turn_penalty - suggestion_penalty

Minimum score: 10.