Liku-AI

██╗     ██╗██╗  ██╗██╗   ██╗       █████╗ ██╗
██║     ██║██║ ██╔╝██║   ██║      ██╔══██╗██║
██║     ██║█████╔╝ ██║   ██║█████╗███████║██║
██║     ██║██╔═██╗ ██║   ██║╚════╝██╔══██║██║
███████╗██║██║  ██╗╚██████╔╝      ██║  ██║██║
╚══════╝╚═╝╚═╝  ╚═╝ ╚═════╝       ╚═╝  ╚═╝╚═╝

Liku-AI

AI-Enhanced Terminal Game Platform with Real-Time WebSocket Communication

Quick Start • For AI Agents • For Developers • Games • API Reference

⛔ FOR AI AGENTS: READ THIS FIRST

DO NOT run npm start in VS Code's integrated terminal!

This is a TUI that will hang your IDE. You MUST:

Read LIKU-CORE.md - Essential setup and launch instructions

Read game docs in docs/ai/ before playing any game

The correct way to launch is via Start-Process (Windows) or background process (Linux). See LIKU-CORE.md for details.

🎯 What is Liku-AI?

Liku-AI is a terminal-based game platform designed for both human players and AI agents. It provides:

Feature	Description
🎮 Terminal Games	Chess, Snake, Dino Run, Tic-Tac-Toe with React/Ink TUI
🤖 AI Agent API	Real-time WebSocket control for any AI model
♟️ Chess Engine	Alpha-beta search, 20+ openings, Elo rating system
📊 Training Tools	Session recording, replay, self-play, A/B testing
🌍 Cross-Platform	Windows, macOS, Linux, GitHub Codespaces

Use Cases:

Play terminal games as a human
Build AI agents that play games autonomously
Train models with recorded game sessions
Benchmark AI strategies with Elo ratings

🚀 Quick Start

Prerequisites

Requirement	Version	Check Command
Node.js	20.x+	`node --version`
npm	10.x+	`npm --version`

Installation (All Platforms)

# Clone repository
git clone https://github.com/TayDa64/Liku-AI.git
cd Liku-AI

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the game!
npm start

First Run

Use arrow keys to navigate, Enter to select, Escape to go back.

┌─────────────────────────────────────┐
│           LIKU-AI v2.0              │
├─────────────────────────────────────┤
│  > 🎮 Let's Play                    │
│    ♟️ Chess                         │
│    📊 Stats & Leaderboards          │
│    ⚙️  Settings                     │
│    🚪 Exit                          │
└─────────────────────────────────────┘

🤖 For AI Agents

Liku-AI is designed to be controlled by AI models (Claude, GPT, Gemini, etc.) through a state file + command interface.

How It Works

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   AI Agent   │ ──── │  State File  │ ──── │   Liku-AI    │
│  (Claude,    │ read │ likubuddy-   │      │   Terminal   │
│   GPT, etc.) │      │ state.txt    │      │     Game     │
└──────────────┘      └──────────────┘      └──────────────┘
       │                                           ▲
       │              ┌──────────────┐             │
       └───────────── │  Commands    │ ────────────┘
              send    │  WebSocket   │   control
                      │  or Scripts  │
                      └──────────────┘

Quick Start for AI Agents

Windows (PowerShell)

# 1. Start game in separate window
Start-Process pwsh -ArgumentList "-NoExit", "-Command", "cd C:\dev\Liku-AI; node dist/index.js"

# 2. Read current state
Get-Content .\likubuddy-state.txt

# 3. Send commands
.\send-keys.ps1 -Key "{DOWN}"    # Navigate down
.\send-keys.ps1 -Key "{ENTER}"   # Select item

macOS / Linux / Codespaces

# 1. Start game in background
node dist/index.js &

# 2. Read current state
cat likubuddy-state.txt

# 3. Send commands via WebSocket
./send-keys.sh -Key "{DOWN}"     # Navigate down
./send-keys.sh -Key "{ENTER}"    # Select item

# Alternative: Direct WebSocket
node send-command.js --key down
node send-command.js --key enter

Available Commands

Command	Windows	macOS/Linux	Description
Navigate Up	`.\send-keys.ps1 -Key "{UP}"`	`./send-keys.sh -Key "{UP}"`	Move selection up
Navigate Down	`.\send-keys.ps1 -Key "{DOWN}"`	`./send-keys.sh -Key "{DOWN}"`	Move selection down
Select	`.\send-keys.ps1 -Key "{ENTER}"`	`./send-keys.sh -Key "{ENTER}"`	Confirm selection
Back	`.\send-keys.ps1 -Key "{ESCAPE}"`	`./send-keys.sh -Key "{ESCAPE}"`	Go back / Exit
Jump (Dino)	`.\send-keys.ps1 -Key " "`	`./send-keys.sh -Key " "`	Space bar
Chess Move	`.\send-keys.ps1 -Key "e4"`	`./send-keys.sh -Key "e4"`	Type move notation

State File Reference

The likubuddy-state.txt file updates in real-time with:

=== LIKU-AI STATE ===
SCREEN: chess
STATUS: Your turn (White)
TURN: white
FEN: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1

VISUAL STATE:
  a b c d e f g h
8 r n b q k b n r
7 p p p p p p p p
...

STRUCTURED STATE (JSON):
{"screen":"chess","turn":"white","fen":"..."}

AI Agent Documentation

Document	Purpose
LIKU-CORE.md	Complete AI agent manual
docs/ai/LIKU-CHESS.md	Chess-specific AI guide
docs/ai/LIKU-SNAKE.md	Snake AI guide
docs/AI_AGENT_BRIEFING.md	Quick agent briefing

🎮 Games

Game	Description	Controls	AI Support
♟️ Chess	Full chess engine with 5 difficulty levels	`e4`, `Nf3`, `h` (hint), `u` (undo), `r` (resign)	✅ Minimax + Opening Book
🐍 Snake	Classic snake game	Arrow keys	✅ State-based AI
🦖 Dino Run	Chrome dinosaur clone	Space (jump), Down (duck)	✅ Obstacle prediction
⭕ Tic-Tac-Toe	Unbeatable AI opponent	Number keys 1-9	✅ Perfect play AI
📝 Hangman	Word guessing game	Letter keys	❌ Human only
🔢 Sudoku	Number puzzle	Number keys	❌ Human only

Chess Engine Details

┌─────────────────────────────────────────────────────┐
│                  Chess Engine                       │
├─────────────────────────────────────────────────────┤
│  Search: Alpha-Beta with Iterative Deepening       │
│  Features: Transposition Table, Quiescence Search  │
│  Opening Book: 20+ named openings                  │
│  Evaluation: Material, Position, Pawn Structure    │
├─────────────────────────────────────────────────────┤
│  Difficulty │ Depth │ Time   │ Est. Elo            │
│  ───────────┼───────┼────────┼──────────           │
│  Easy       │ 2     │ <1s    │ ~1000               │
│  Medium     │ 3     │ ~2s    │ ~1200               │
│  Hard       │ 4     │ ~5s    │ ~1400               │
│  Expert     │ 5     │ ~15s   │ ~1600               │
└─────────────────────────────────────────────────────┘

👨‍💻 For Developers

Project Structure

liku-ai/
├── src/
│   ├── index.tsx              # Entry point (React/Ink TUI)
│   ├── chess/                 # Chess engine
│   │   ├── ChessAI.ts         # AI player (minimax)
│   │   ├── ChessEval.ts       # Position evaluation
│   │   ├── ChessSearch.ts     # Alpha-beta search
│   │   └── OpeningBook.ts     # 20+ named openings
│   ├── websocket/             # WebSocket server
│   │   ├── server.ts          # WS server (port 3847)
│   │   ├── router.ts          # Command routing
│   │   └── cli.ts             # Standalone server CLI
│   ├── training/              # Training infrastructure
│   │   ├── SessionRecorder.ts # Record game sessions
│   │   ├── SessionPlayer.ts   # Replay sessions
│   │   └── ABTest.ts          # A/B testing framework
│   ├── ui/games/              # Game components
│   │   ├── Chess.tsx          # Chess UI
│   │   ├── Snake.tsx          # Snake game
│   │   ├── DinoRun.tsx        # Dino game
│   │   └── TicTacToe.tsx      # Tic-Tac-Toe
│   └── core/                  # Core utilities
│       ├── StateLogger.ts     # State file writer
│       └── DatabaseService.ts # SQLite database
├── scripts/                   # Utility scripts
│   ├── chess-ai-battle.js     # AI vs AI matches
│   ├── self-play.ts           # Training data generation
│   └── elo-estimate.ts        # Elo calculation
├── __tests__/                 # Test files (514 tests)
├── docs/                      # Documentation
├── k8s/                       # Kubernetes manifests
├── send-keys.ps1              # Windows keystroke sender
├── send-keys.sh               # macOS/Linux keystroke sender
├── send-command.js            # Cross-platform WebSocket CLI
└── likubuddy-state.txt        # Real-time state file (generated)

NPM Scripts

Script	Command	Description
Start	`npm start`	Launch terminal UI
Build	`npm run build`	Compile TypeScript
Dev	`npm run dev`	Watch mode (auto-rebuild)
Test	`npm test`	Run Vitest tests
Server	`npm run server`	WebSocket server only
AI Battle	`npm run ai-vs-ai`	Run AI vs AI chess match

WebSocket API

Connect to ws://localhost:3847 for real-time communication:

// Example: Connect and send commands
import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3847');

ws.on('open', () => {
  // Send a key press
  ws.send(JSON.stringify({ type: 'key', key: 'down' }));
  
  // Send a chess move
  ws.send(JSON.stringify({ type: 'action', action: 'chess_move', params: { move: 'e4' } }));
  
  // Query current state
  ws.send(JSON.stringify({ type: 'query', query: 'state' }));
});

ws.on('message', (data) => {
  const response = JSON.parse(data.toString());
  console.log('Response:', response);
});

Message Types:

Type	Purpose	Example
`key`	Send keystroke	`{ type: 'key', key: 'enter' }`
`action`	Game action	`{ type: 'action', action: 'chess_move', params: { move: 'e4' } }`
`query`	Request data	`{ type: 'query', query: 'state' }`

Environment Variables

Variable	Default	Description
`LIKU_WS_PORT`	`3847`	WebSocket server port
`LIKU_HEALTH_PORT`	`3848`	Health check endpoint
`GEMINI_API_KEY`	—	Google AI for move explanations

Testing

# Run all tests
npm test

# Run once (CI mode)
npm run test:run

# Run specific test file
npx vitest run __tests__/WebSocket.test.ts

# Run with coverage
npx vitest run --coverage

Test Coverage:

Module	Tests	Coverage
WebSocket	179	~95%
Training	93	~95%
Spectator	93	~95%
Security	43	~90%
TURN	40	~90%
Total	514	~95%

Training & Self-Play

# Generate training data from AI vs AI games
npx tsx scripts/self-play.ts --games 20 --depth-range 2-4

# Estimate Elo rating from recorded games
npx tsx scripts/elo-estimate.ts --verbose

# Run AI battle with specific settings
node scripts/chess-ai-battle.js --white=minimax --black=minimax --depth=4

Docker Support

# Build image
docker build -t liku-ai .

# Run container
docker run -p 3847:3847 -p 3848:3848 liku-ai

# Docker Compose (with Redis)
docker-compose up -d

📚 Documentation

Quick Links

Document	Audience	Description
LIKU-CORE.md	AI Agents	Complete AI agent operation manual
Quick Reference	Everyone	One-page command cheatsheet
API Reference	Developers	WebSocket API documentation
WebSocket Protocol	Developers	Protocol specification
Troubleshooting	Everyone	Common issues & solutions
AI Battle Guide	Developers	AI vs AI game setup
Performance	Developers	Benchmarks & load tests

AI-Specific Guides

Game	AI Guide
Chess	docs/ai/LIKU-CHESS.md
Snake	docs/ai/LIKU-SNAKE.md
Tic-Tac-Toe	docs/ai/LIKU-TICTACTOE.md
Dino Run	docs/ai/LIKU-DINORUN.md

❓ Troubleshooting

Common Issues

Problem	Solution
"Cannot find module 'dist/index.js'"	Run `npm run build` first
WebSocket connection refused	Ensure server is running: `npm run server`
State file not updating	Check game is running in separate terminal
Commands not working	Verify game window has focus (Windows) or WebSocket port 3847 is open
Permission denied on send-keys.sh	Run `chmod +x send-keys.sh send-command.js`

Platform-Specific Notes

Windows:

PowerShell 5.1+ required
send-keys.ps1 uses COM automation (requires foreground window)

macOS:

Bash 3.2+ compatible (native macOS shell works)
send-keys.sh uses WebSocket (no GUI requirements)

Linux / Codespaces:

Works fully headless via WebSocket
No display server required

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit changes: git commit -m 'Add my feature'
Push to branch: git push origin feature/my-feature
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/Liku-AI.git
cd Liku-AI

# Install dependencies
npm install

# Start dev mode (auto-rebuild)
npm run dev

# In another terminal, run the app
npm start

📜 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

chess.js — Chess move generation & validation
Ink — React for command-line interfaces
ws — WebSocket implementation
Vitest — Testing framework
Chess Programming Wiki — Engine algorithms reference

Version: 2.0.0 • Tests: 514 passing • Platforms: Windows, macOS, Linux

Made with ❤️ for AI agents and humans alike

⬆ Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.genkit/traces_idx		.genkit/traces_idx
.github		.github
.vscode		.vscode
__tests__		__tests__
commands		commands
docs		docs
ideas		ideas
k8s		k8s
media		media
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dec_02__0957_48s_202512021051_9e7kt.mp4		Dec_02__0957_48s_202512021051_9e7kt.mp4
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
GEMINI.md		GEMINI.md
GENERATIVE_GAME_PLATFORM.md		GENERATIVE_GAME_PLATFORM.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LIKU-CORE.md		LIKU-CORE.md
LikuBuddy.code-workspace		LikuBuddy.code-workspace
PERSISTENCE_AND_COMMANDS_UPDATE.md		PERSISTENCE_AND_COMMANDS_UPDATE.md
README.md		README.md
SUPERVISOR_PORT_COMPLETE.md		SUPERVISOR_PORT_COMPLETE.md
TODO.md		TODO.md
ai-battle-errors.log		ai-battle-errors.log
ai-game-state.json		ai-game-state.json
chess_game.log		chess_game.log
chess_game_2.log		chess_game_2.log
chess_game_3.log		chess_game_3.log
chess_review.md		chess_review.md
codex-chess-review.md		codex-chess-review.md
codex-max-chess-review-v2.md		codex-max-chess-review-v2.md
codex-max-chess-review.md		codex-max-chess-review.md
codex-review.md		codex-review.md
docker-compose.yml		docker-compose.yml
down.ps1		down.ps1
enter.ps1		enter.ps1
feed.ps1		feed.ps1
game-output.txt		game-output.txt
game_output.txt		game_output.txt
gemini-extension.json		gemini-extension.json
gemini-suggestion.md		gemini-suggestion.md
image.png		image.png
improvements.md		improvements.md
knowing.md		knowing.md
left.ps1		left.ps1
likubuddy-state.txt		likubuddy-state.txt
package-lock.json		package-lock.json
package.json		package.json
rest.ps1		rest.ps1
review_chess.md		review_chess.md
right.ps1		right.ps1
send-command.js		send-command.js
send-keys.ps1		send-keys.ps1
send-keys.sh		send-keys.sh
send-ws-key.js		send-ws-key.js
server-output.txt		server-output.txt
server.log		server.log
setup_and_play.ps1		setup_and_play.ps1
snake_ai.ps1		snake_ai.ps1
stderr.txt		stderr.txt
stdout.txt		stdout.txt
test-error.txt		test-error.txt
test-output.txt		test-output.txt
tictactoe-state.txt		tictactoe-state.txt
todo-chess.md		todo-chess.md
training-data-games.json		training-data-games.json
training-data.jsonl		training-data.jsonl
tsconfig.json		tsconfig.json
up.ps1		up.ps1
vitest.config.ts		vitest.config.ts
ws-debug.log		ws-debug.log

TayDa64/Liku-AI

Folders and files

Latest commit

History

Repository files navigation

Liku-AI

⛔ FOR AI AGENTS: READ THIS FIRST

🎯 What is Liku-AI?

🚀 Quick Start

Prerequisites

Installation (All Platforms)

First Run

🤖 For AI Agents

How It Works

Quick Start for AI Agents

Windows (PowerShell)

macOS / Linux / Codespaces

Available Commands

State File Reference

AI Agent Documentation

🎮 Games

Chess Engine Details

👨‍💻 For Developers

Project Structure

NPM Scripts

WebSocket API

Environment Variables

Testing

Training & Self-Play

Docker Support

📚 Documentation

Quick Links

AI-Specific Guides

❓ Troubleshooting

Common Issues

Platform-Specific Notes

🤝 Contributing

Development Setup

📜 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages