{
"markdown": "\n\n```\n██╗ ██╗██╗ ██╗██╗ ██╗ █████╗ ██╗\n██║ ██║██║ ██╔╝██║ ██║ ██╔══██╗██║\n██║ ██║█████╔╝ ██║ ██║█████╗███████║██║\n██║ ██║██╔═██╗ ██║ ██║╚════╝██╔══██║██║\n███████╗██║██║ ██╗╚██████╔╝ ██║ ██║██║\n╚══════╝╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝\n```\n\n# Liku-AI\n\n**AI-Enhanced Terminal Game Platform with Real-Time WebSocket Communication**\n\n[](https://nodejs.org/)\n[](https://www.typescriptlang.org/)\n[](https://vitest.dev/)\n[](LICENSE)\n\n[Quick Start](#-quick-start) •\n[For AI Agents](#-for-ai-agents) •\n[For Developers](#-for-developers) •\n[Games](#-games) •\n[API Reference](docs/API_REFERENCE.md)\n\n
\n\n---\n\n## ⛔ FOR AI AGENTS: READ THIS FIRST\n\n> **DO NOT run `npm start` in VS Code's integrated terminal!**\n> \n> This is a TUI that will hang your IDE. You MUST:\n> 1. **Read [LIKU-CORE.md](LIKU-CORE.md)** - Essential setup and launch instructions\n> 2. **Read game docs** in `docs/ai/` before playing any game\n> \n> The correct way to launch is via `Start-Process` (Windows) or background process (Linux).\n> See LIKU-CORE.md for details.\n\n---\n\n## 🎯 What is Liku-AI?\n\nLiku-AI is a **terminal-based game platform** designed for both human players and AI agents. It provides:\n\n| Feature | Description |\n|---------|-------------|\n| 🎮 **Terminal Games** | Chess, Snake, Dino Run, Tic-Tac-Toe with React/Ink TUI |\n| 🤖 **AI Agent API** | Real-time WebSocket control for any AI model |\n| ♟️ **Chess Engine** | Alpha-beta search, 20+ openings, Elo rating system |\n| 📊 **Training Tools** | Session recording, replay, self-play, A/B testing |\n| 🌍 **Cross-Platform** | Windows, macOS, Linux, GitHub Codespaces |\n\n**Use Cases:**\n- Play terminal games as a human\n- Build AI agents that play games autonomously \n- Train models with recorded game sessions\n- Benchmark AI strategies with Elo ratings\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n| Requirement | Version | Check Command |\n|-------------|---------|---------------|\n| Node.js | 20.x+ | `node --version` |\n| npm | 10.x+ | `npm --version` |\n\n### Installation (All Platforms)\n\n```bash\n# Clone repository\ngit clone https://github.com/TayDa64/Liku-AI.git\ncd Liku-AI\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Start the game!\nnpm start\n```\n\n### First Run\n\nUse **arrow keys** to navigate, **Enter** to select, **Escape** to go back.\n\n```\n┌─────────────────────────────────────┐\n│ LIKU-AI v2.0 │\n├─────────────────────────────────────┤\n│ > 🎮 Let's Play │\n│ ♟️ Chess │\n│ 📊 Stats & Leaderboards │\n│ ⚙️ Settings │\n│ 🚪 Exit │\n└─────────────────────────────────────┘\n```\n\n---\n\n## 🤖 For AI Agents\n\nLiku-AI is designed to be controlled by AI models (Claude, GPT, Gemini, etc.) through a state file + command interface.\n\n### How It Works\n\n```\n┌──────────────┐ ┌──────────────┐ ┌──────────────┐\n│ AI Agent │ ──── │ State File │ ──── │ Liku-AI │\n│ (Claude, │ read │ likubuddy- │ │ Terminal │\n│ GPT, etc.) │ │ state.txt │ │ Game │\n└──────────────┘ └──────────────┘ └──────────────┘\n │ ▲\n │ ┌──────────────┐ │\n └───────────── │ Commands │ ────────────┘\n send │ WebSocket │ control\n │ or Scripts │\n └──────────────┘\n```\n\n### Quick Start for AI Agents\n\n#### Windows (PowerShell)\n\n```powershell\n# 1. Start game in separate window\nStart-Process pwsh -ArgumentList \"-NoExit\", \"-Command\", \"cd C:\\dev\\Liku-AI; node dist/index.js\"\n\n# 2. Read current state\nGet-Content .\\likubuddy-state.txt\n\n# 3. Send commands\n.\\send-keys.ps1 -Key \"{DOWN}\" # Navigate down\n.\\send-keys.ps1 -Key \"{ENTER}\" # Select item\n```\n\n#### macOS / Linux / Codespaces\n\n```bash\n# 1. Start game in background\nnode dist/index.js &\n\n# 2. Read current state\ncat likubuddy-state.txt\n\n# 3. Send commands via WebSocket\n./send-keys.sh -Key \"{DOWN}\" # Navigate down\n./send-keys.sh -Key \"{ENTER}\" # Select item\n\n# Alternative: Direct WebSocket\nnode send-command.js --key down\nnode send-command.js --key enter\n```\n\n\n\n### Available Commands\n\n| Command | Windows | macOS/Linux | Description |\n|---------|---------|-------------|-------------|\n| Navigate Up | `.\\send-keys.ps1 -Key \"{UP}\"` | `./send-keys.sh -Key \"{UP}\"` | Move selection up |\n| Navigate Down | `.\\send-keys.ps1 -Key \"{DOWN}\"` | `./send-keys.sh -Key \"{DOWN}\"` | Move selection down |\n| Select | `.\\send-keys.ps1 -Key \"{ENTER}\"` | `./send-keys.sh -Key \"{ENTER}\"` | Confirm selection |\n| Back | `.\\send-keys.ps1 -Key \"{ESCAPE}\"` | `./send-keys.sh -Key \"{ESCAPE}\"` | Go back / Exit |\n| Jump (Dino) | `.\\send-keys.ps1 -Key \" \"` | `./send-keys.sh -Key \" \"` | Space bar |\n| Chess Move | `.\\send-keys.ps1 -Key \"e4\"` | `./send-keys.sh -Key \"e4\"` | Type move notation |\n\n### State File Reference\n\nThe `likubuddy-state.txt` file updates in real-time with:\n\n```\n=== LIKU-AI STATE ===\nSCREEN: chess\nSTATUS: Your turn (White)\nTURN: white\nFEN: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1\n\nVISUAL STATE:\n a b c d e f g h\n8 r n b q k b n r\n7 p p p p p p p p\n...\n\nSTRUCTURED STATE (JSON):\n{\"screen\":\"chess\",\"turn\":\"white\",\"fen\":\"...\"}\n```\n\n### AI Agent Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [LIKU-CORE.md](LIKU-CORE.md) | Complete AI agent manual |\n| [docs/ai/LIKU-CHESS.md](docs/ai/LIKU-CHESS.md) | Chess-specific AI guide |\n| [docs/ai/LIKU-SNAKE.md](docs/ai/LIKU-SNAKE.md) | Snake AI guide |\n| [docs/AI_AGENT_BRIEFING.md](docs/AI_AGENT_BRIEFING.md) | Quick agent briefing |\n\n---\n\n## 🎮 Games\n\n| Game | Description | Controls | AI Support |\n|------|-------------|----------|------------|\n| ♟️ **Chess** | Full chess engine with 5 difficulty levels | `e4`, `Nf3`, `h` (hint), `u` (undo), `r` (resign) | ✅ Minimax + Opening Book |\n| 🐍 **Snake** | Classic snake game | Arrow keys | ✅ State-based AI |\n| 🦖 **Dino Run** | Chrome dinosaur clone | Space (jump), Down (duck) | ✅ Obstacle prediction |\n| ⭕ **Tic-Tac-Toe** | Unbeatable AI opponent | Number keys 1-9 | ✅ Perfect play AI |\n| 📝 **Hangman** | Word guessing game | Letter keys | ❌ Human only |\n| 🔢 **Sudoku** | Number puzzle | Number keys | ❌ Human only |\n\n### Chess Engine Details\n\n```\n┌─────────────────────────────────────────────────────┐\n│ Chess Engine │\n├─────────────────────────────────────────────────────┤\n│ Search: Alpha-Beta with Iterative Deepening │\n│ Features: Transposition Table, Quiescence Search │\n│ Opening Book: 20+ named openings │\n│ Evaluation: Material, Position, Pawn Structure │\n├─────────────────────────────────────────────────────┤\n│ Difficulty │ Depth │ Time │ Est. Elo │\n│ ───────────┼───────┼────────┼────────── │\n│ Easy │ 2 │ <1s │ ~1000 │\n│ Medium │ 3 │ ~2s │ ~1200 │\n│ Hard │ 4 │ ~5s │ ~1400 │\n│ Expert │ 5 │ ~15s │ ~1600 │\n└─────────────────────────────────────────────────────┘\n```\n\n---\n\n## 👨💻 For Developers\n\n### Project Structure\n\n```\nliku-ai/\n├── src/\n│ ├── index.tsx # Entry point (React/Ink TUI)\n│ ├── chess/ # Chess engine\n│ │ ├── ChessAI.ts # AI player (minimax)\n│ │ ├── ChessEval.ts # Position evaluation\n│ │ ├── ChessSearch.ts # Alpha-beta search\n│ │ └── OpeningBook.ts # 20+ named openings\n│ ├── websocket/ # WebSocket server\n│ │ ├── server.ts # WS server (port 3847)\n│ │ ├── router.ts # Command routing\n│ │ └── cli.ts # Standalone server CLI\n│ ├── training/ # Training infrastructure\n│ │ ├── SessionRecorder.ts # Record game sessions\n│ │ ├── SessionPlayer.ts # Replay sessions\n│ │ └── ABTest.ts # A/B testing framework\n│ ├── ui/games/ # Game components\n│ │ ├── Chess.tsx # Chess UI\n│ │ ├── Snake.tsx # Snake game\n│ │ ├── DinoRun.tsx # Dino game\n│ │ └── TicTacToe.tsx # Tic-Tac-Toe\n│ └── core/ # Core utilities\n│ ├── StateLogger.ts # State file writer\n│ └── DatabaseService.ts # SQLite database\n├── scripts/ # Utility scripts\n│ ├── chess-ai-battle.js # AI vs AI matches\n│ ├── self-play.ts # Training data generation\n│ └── elo-estimate.ts # Elo calculation\n├── __tests__/ # Test files (514 tests)\n├── docs/ # Documentation\n├── k8s/ # Kubernetes manifests\n├── send-keys.ps1 # Windows keystroke sender\n├── send-keys.sh # macOS/Linux keystroke sender\n├── send-command.js # Cross-platform WebSocket CLI\n└── likubuddy-state.txt # Real-time state file (generated)\n```\n\n### NPM Scripts\n\n| Script | Command | Description |\n|--------|---------|-------------|\n| **Start** | `npm start` | Launch terminal UI |\n| **Build** | `npm run build` | Compile TypeScript |\n| **Dev** | `npm run dev` | Watch mode (auto-rebuild) |\n| **Test** | `npm test` | Run Vitest tests |\n| **Server** | `npm run server` | WebSocket server only |\n| **AI Battle** | `npm run ai-vs-ai` | Run AI vs AI chess match |\n\n### WebSocket API\n\nConnect to `ws://localhost:3847` for real-time communication:\n\n```typescript\n// Example: Connect and send commands\nimport WebSocket from 'ws';\n\nconst ws = new WebSocket('ws://localhost:3847');\n\nws.on('open', () => {\n // Send a key press\n ws.send(JSON.stringify({ type: 'key', key: 'down' }));\n \n // Send a chess move\n ws.send(JSON.stringify({ type: 'action', action: 'chess_move', params: { move: 'e4' } }));\n \n // Query current state\n ws.send(JSON.stringify({ type: 'query', query: 'state' }));\n});\n\nws.on('message', (data) => {\n const response = JSON.parse(data.toString());\n console.log('Response:', response);\n});\n```\n\n**Message Types:**\n\n| Type | Purpose | Example |\n|------|---------|---------|\n| `key` | Send keystroke | `{ type: 'key', key: 'enter' }` |\n| `action` | Game action | `{ type: 'action', action: 'chess_move', params: { move: 'e4' } }` |\n| `query` | Request data | `{ type: 'query', query: 'state' }` |\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `LIKU_WS_PORT` | `3847` | WebSocket server port |\n| `LIKU_HEALTH_PORT` | `3848` | Health check endpoint |\n| `GEMINI_API_KEY` | — | Google AI for move explanations |\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run once (CI mode)\nnpm run test:run\n\n# Run specific test file\nnpx vitest run __tests__/WebSocket.test.ts\n\n# Run with coverage\nnpx vitest run --coverage\n```\n\n**Test Coverage:**\n\n| Module | Tests | Coverage |\n|--------|-------|----------|\n| WebSocket | 179 | ~95% |\n| Training | 93 | ~95% |\n| Spectator | 93 | ~95% |\n| Security | 43 | ~90% |\n| TURN | 40 | ~90% |\n| **Total** | **514** | **~95%** |\n\n### Training & Self-Play\n\n```bash\n# Generate training data from AI vs AI games\nnpx tsx scripts/self-play.ts --games 20 --depth-range 2-4\n\n# Estimate Elo rating from recorded games\nnpx tsx scripts/elo-estimate.ts --verbose\n\n# Run AI battle with specific settings\nnode scripts/chess-ai-battle.js --white=minimax --black=minimax --depth=4\n```\n\n### Docker Support\n\n```bash\n# Build image\ndocker build -t liku-ai .\n\n# Run container\ndocker run -p 3847:3847 -p 3848:3848 liku-ai\n\n# Docker Compose (with Redis)\ndocker-compose up -d\n```\n\n---\n\n## 📚 Documentation\n\n### Quick Links\n\n| Document | Audience | Description |\n|----------|----------|-------------|\n| [LIKU-CORE.md](LIKU-CORE.md) | AI Agents | Complete AI agent operation manual |\n| [Quick Reference](docs/QUICK_REFERENCE.md) | Everyone | One-page command cheatsheet |\n| [API Reference](docs/API_REFERENCE.md) | Developers | WebSocket API documentation |\n| [WebSocket Protocol](docs/WEBSOCKET_PROTOCOL.md) | Developers | Protocol specification |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Everyone | Common issues & solutions |\n| [AI Battle Guide](docs/AI_BATTLE_GUIDE.md) | Developers | AI vs AI game setup |\n| [Performance](docs/PERFORMANCE.md) | Developers | Benchmarks & load tests |\n\n### AI-Specific Guides\n\n| Game | AI Guide |\n|------|----------|\n| Chess | [docs/ai/LIKU-CHESS.md](docs/ai/LIKU-CHESS.md) |\n| Snake | [docs/ai/LIKU-SNAKE.md](docs/ai/LIKU-SNAKE.md) |\n| Tic-Tac-Toe | [docs/ai/LIKU-TICTACTOE.md](docs/ai/LIKU-TICTACTOE.md) |\n| Dino Run | [docs/ai/LIKU-DINORUN.md](docs/ai/LIKU-DINORUN.md) |\n\n---\n\n## ❓ Troubleshooting\n\n### Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| **\"Cannot find module 'dist/index.js'\"** | Run `npm run build` first |\n| **WebSocket connection refused** | Ensure server is running: `npm run server` |\n| **State file not updating** | Check game is running in separate terminal |\n| **Commands not working** | Verify game window has focus (Windows) or WebSocket port 3847 is open |\n| **Permission denied on send-keys.sh** | Run `chmod +x send-keys.sh send-command.js` |\n\n### Platform-Specific Notes\n\n**Windows:**\n- PowerShell 5.1+ required\n- `send-keys.ps1` uses COM automation (requires foreground window)\n\n**macOS:**\n- Bash 3.2+ compatible (native macOS shell works)\n- `send-keys.sh` uses WebSocket (no GUI requirements)\n\n**Linux / Codespaces:**\n- Works fully headless via WebSocket\n- No display server required\n\n---\n\n## 🤝 Contributing\n\n1. **Fork** the repository\n2. **Create** a feature branch: `git checkout -b feature/my-feature`\n3. **Commit** changes: `git commit -m 'Add my feature'`\n4. **Push** to branch: `git push origin feature/my-feature`\n5. **Open** a Pull Request\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/YOUR_USERNAME/Liku-AI.git\ncd Liku-AI\n\n# Install dependencies\nnpm install\n\n# Start dev mode (auto-rebuild)\nnpm run dev\n\n# In another terminal, run the app\nnpm start\n```\n\n---\n\n## 📜 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- [chess.js](https://github.com/jhlywa/chess.js) — Chess move generation & validation\n- [Ink](https://github.com/vadimdemedes/ink) — React for command-line interfaces\n- [ws](https://github.com/websockets/ws) — WebSocket implementation\n- [Vitest](https://vitest.dev/) — Testing framework\n- [Chess Programming Wiki](https://www.chessprogramming.org/) — Engine algorithms reference\n\n---\n\n\n\n**Version**: 2.0.0 • **Tests**: 514 passing • **Platforms**: Windows, macOS, Linux\n\nMade with ❤️ for AI agents and humans alike\n\n[⬆ Back to top](#liku-ai)\n\n
\n",
"bytes": 15139,
"sha": "3896cbd44da7f60dfa63b5f863d2ad1a35743273b5a918d18d53012b42eef445",
"repo_slug": "tayda64/liku-ai",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_tayda64_liku_ai_0ce3dbcc/readme"
}