Tapoo

Tapoo increases maze area as levels rise. Progress continues until the current terminal window or browser viewport can no longer fit the next maze cleanly.

• Arrow keys: move the player
• Ctrl+B: cycle maze wall weight
• Space or Esc: pause the current run
• Enter: proceed after pause, win, or failure
• Ctrl+C: quit

• Keyboard controls mirror the terminal controls
• Ctrl+Alt+R: reset browser progress
• On touch devices, on-screen controls are shown automatically

• Terminal-first maze gameplay
• Browser SPA with the same black-and-green terminal feel
• Adjustable wall weights with live cycling during play
• Per-level scoring and progression
• Pause, resume, retry, and next-level flow
• HTTP-driven AI agent play against Ollama, OpenAI-compatible, and Anthropic APIs, with up to 6 (configurable) agent seats
• Best-effort persistence for terminal and browser sessions
• Manual GitHub Pages deployment for the web build
• Go and TypeScript test coverage in CI

The browser build outputs a bundled file at public/js/tapoo.min.js and serves the SPA from public/index.html.

This compiles frontend/tapoo.ts with esbuild into a minified browser bundle.

Available pages:

• /index.html for the game
• /agents.html for configuring and running HTTP-driven AI agents
• /prompts.html for previewing the exact prompts and tool definitions sent to an agent
• /privacy.html for the browser storage and agent data privacy notice

Instead of (or alongside) a human player, up to 6 agent seats can each be configured to play the maze by calling an HTTP chat-completions endpoint every turn.

• Ollama — native /api/chat shape
• OpenAI-compatible — /v1/chat/completions (also covers self-hosted servers such as vLLM, LM Studio, and llama.cpp, and routers such as Hugging Face's Inference Providers)
• Anthropic — /v1/messages

Each seat is configured independently from the /agents.html overlay:

• player name, model, endpoint, and API provider
• credential (bearer token or API key) and custom extra headers, e.g. anthropic-version
• reasoning effort — how hard the model reasons before replying; the available levels and default depend on the provider, since reasoning support varies by model (e.g. Kimi K3 handles heavy reasoning well, Gemma 4 does not)
• echo back reasoning — whether prior reasoning content is replayed on the next request, off by default since guidance on this conflicts across reasoning models; locked off automatically whenever reasoning effort is set to none, and has no effect for Anthropic agents

The /prompts.html page mirrors the exact system prompt, tool definitions, and required response format an agent receives, so its behavior can be inspected without capturing live traffic.

Tapoo carries a semantic version (MAJOR.MINOR.PATCH), shown in the terminal intro banner and in the browser footer. Browser storage additionally carries its own separate schema version, independent of the app version above — see the browser storage note below.

The terminal version stores best-effort runtime state in a local file:

• .tapoo.store

It keeps track of:

• current level
• selected wall weight
• last game progress state

If the persisted state cannot be read or validated, Tapoo falls back to default startup behavior.

The SPA stores gameplay state in browser storage:

• localStorage for durable preferences such as level and wall weight, and for configured agent seats (including credentials, endpoints, and per-agent reasoning settings)
• sessionStorage for the active round snapshot

Every stored entry is tagged with the current storage schema version. On startup, Tapoo automatically discards any entries left over from an older schema version rather than attempting to migrate them — so upgrading Tapoo can silently reset previously stored preferences and agent configuration.

Privacy note: browser storage stays on the current device unless the user clears it, resets progress, or removes configured agent data. Browser storage is lightly obfuscated to discourage casual tampering, but it should not be treated as strong encryption for personal data. When AI Agent play is configured, gameplay context such as player name, current cell, destination cell, submitted moves, score, level, and traversal history may be sent to the configured agent API endpoint.

The deployed browser pages include a short privacy notice at privacy.html.

• Go 1.25+
• pnpm 11.7.0
• Node.js 22
• golangci-lint v2.12.2

make help
make frontend-install
make frontend-quality
make frontend-build
make test
make ci

Go and TypeScript carve mazes independently from different random sources, so scripts/bench-report.mjs runs both ports' benchmark suites (maze/bench and frontend/bench) and statistically checks that the two generators still produce equivalent-distribution mazes rather than merely eyeballing the numbers. A flagged case means a reproducible behavioral gap between the ports, not just run-to-run noise.

make go-bench        # Go maze generation only
make frontend-bench  # TypeScript maze generation only
make ci-bench        # both, with the cross-port parity check

Each run also writes bench-report.json with the full comparison.

Contributions are welcome, but contributors should install the repository pre-commit hook before creating commits.

1. Install the required toolchains: Go 1.25+, Node.js 22, pnpm 11.7.0, and golangci-lint v2.12.2
2. Install frontend dependencies:

make frontend-install

3. Install the repository git hooks:

./scripts/install-hooks.sh

The hook installer copies scripts/hooks/pre-commit into .git/hooks/pre-commit.

The pre-commit hook runs:

golangci-lint run

This is required so commits are checked locally before they are pushed. If golangci-lint is not installed, the hook installation script will warn you and show installation options.

make ci

At minimum, contributors should make sure:

• Go tests pass
• frontend typecheck, lint, and tests pass
• golangci-lint run passes
• govulncheck passes

• make lint: run golangci-lint
• make govulncheck: run govulncheck
• make frontend-quality: run frontend typecheck, lint, and tests
• make frontend-build: build the minified SPA bundle
• make test: run frontend checks plus Go race tests with coverage
• make ci: run the local equivalent of the main CI pipeline

The main CI workflow lives at .github/workflows/go.yml and runs:

• Go linting
• govulncheck
• frontend typecheck, lint, tests, and build
• Go race tests with coverage
• coverage uploads for Go and frontend reports

The Pages workflow lives at .github/workflows/pages.yml.

Pages deployment is manual-only.

To deploy:

1. Open the repository on GitHub.
2. Go to Actions.
3. Choose Deploy Pages Manually.
4. Click Run workflow.
5. Select the branch you want to deploy.

Important:

• GitHub Pages should be configured to use GitHub Actions as the publishing source.
• Since the workflow is manual, it deploys the branch selected at run time.