agent_game

!Norm playing chess with OpenClaw

A deterministic, offline-first Python CLI framework built to allow OpenClaw agents to play multi-session games (like Chess, Battleship, Blackjack) over text channels (iMessage, Telegram).

Project Philosophy: Low Linguistic Complexity

This project is explicitly engineered for low cognitive load. We use psycholinguistic metrics to ensure the codebase remains legible to both human maintainers and AI coding agents, prioritizing obviousness over raw computational efficiency (Big O).

• Low MDD (Mean Dependency Distance): Variable scope is minimized. State is declared exactly where it is used.
• Low DLT (Dependency Locality / Fan-Out): Execution flows top-to-bottom. We avoid deep call graphs, massive class inheritance trees, and event-driven frameworks.
• Low Entropy: Command handlers and game drivers follow strict, standardized patterns. Once you understand one command, you understand them all.
• Low Subordination Index: We prefer early returns and guard clauses over deeply nested if/for branches.

By minimizing Linguistic Complexity, we make attention cheap, leaving human cognitive resources available for system-level coordination.

Architecture & Data Flow

1. JSON-First CLI: The core is a Python CLI (agent_game/) where every command accepts arguments and outputs exactly one JSON object to stdout. 2. File-Based State: The system is stateless in memory. All game state, history, and rendering outputs are atomically persisted to disk under workspace/games/<type>/<id>/. 3. OpenClaw Plugin: The openclaw-game/ directory contains a TypeScript plugin that wraps the Python CLI into structured tool definitions for OpenClaw agents.

Project Structure

agent_game/
├── docs/                # Spec, plans, and methodology
├── agent_game/          # Main Python package
│   ├── cli.py           # CLI entry point
│   ├── core/            # Game-agnostic protocols (GameDriver, state management)
│   ├── commands/        # CLI command routing (new, board, play)
│   └── games/           # Specific game drivers (chess, etc.)
├── tests/               # Pytest suite
└── openclaw-game/       # OpenClaw TypeScript plugin workspace

Setup & Toolchains

This repository uses a dual-stack setup.

1. Python CLI (Core)

We use uv for lightning-fast Python dependency management and execution.

# Run tests
uv run pytest

# Type checking (strict)
uv run ty check .

# Linting
uv run ruff check .

2. TypeScript Plugin (openclaw-game/)

We use bun along with the oxlint toolchain for the OpenClaw plugin.

cd openclaw-game
bun install

# Run the full validation gate (lint, format, typecheck, test)
bun run check

# Formatting and fixing
bun run fmt
bun run lint:fix

Contributing (TCR+R)

We use strict TCR+R (Test && Commit || Revert + Refactor) for development. Every change must be validated against the dual-stack gates before committing. Atomic commits using Conventional Commits are required. See AGENTS.md and docs/ for specific agent-harness operating procedures.