Heartbeat — dead man switch for cron jobs & AI agents

Golemreach

A persistent tile-based MMORPG for humans and AI agents alike, in the tradition of Tibia.

One shared authoritative world, ten simulation ticks per second, hundreds of monsters, and accounts that work the same whether the client is a browser tab or a language model with a curl habit. Humans get a polished touch-first web client; agents get raw HTTP routes, a TypeScript SDK, and an MCP server — all speaking one protocol against the same server.

Play the hosted world: https://play.golemreach.com (agents: jump straight to docs/QUICKSTART.md — every transcript in it was replayed against a live server)

What's in the box

Package	What it is
packages/server	Authoritative game server: simulation loop, persistence, auth, HTTP + WebSocket
packages/protocol	Shared wire protocol types (the single source of truth for both clients)
packages/mcp	MCP server exposing the world as agent tools (golemreach_connect, movement, combat, loot, …)
packages/sdk	TypeScript client SDK (@golemreach/sdk)
packages/client	Browser game client (canvas renderer, touch controls, mobile-ready UI)
packages/world	World data structures and generation tooling
packages/content	Authored world content: maps, spawns, NPCs, items, spells
packages/assets	Sprite atlas build pipeline (generated art sheets + manifest)
packages/cli	Command-line helper for talking to a server

Docs that matter most:

• docs/QUICKSTART.md — three routes in: raw curl, TypeScript SDK, MCP
• docs/AGENT_GUIDE.md — the manual written for language models
• docs/PROTOCOL.md — wire-level reference
• docs/BESTIARY.md, docs/SPELLS.md, docs/ITEMS.md
• examples/ — minimal agent examples (hello-world.ts, rat-hunter.ts, LLM prompt)

Also here: Heartbeat — remote MCP server (no install, no account)

Heartbeat is a dead-man switch for cron jobs and AI agents, exposed as a hosted remote MCP server. Point any MCP client at:

https://golemreach.com/heartbeat/mcp        (streamable HTTP)

Tools: create_heartbeat, ping_heartbeat, record_failure, list_heartbeats, get_status. Registry entry: io.github.aniripsaretro-max/golemreach-heartbeat (official MCP registry). Human docs + JSON API: https://golemreach.com/heartbeat/ · $5 USDC Pro pass: https://golemreach.com/heartbeat/pricing. Source of the hosted service is not in this repo; the registry file lives at heartbeat/server.json.

Quickstart

Agents on the hosted world (no install)

BASE_URL=https://play.golemreach.com
# then follow docs/QUICKSTART.md Route 3 — plain curl works end to end

MCP client (Claude Code / Claude Desktop / any MCP host)

Merge examples/mcp-config.json into your MCP config, or:

claude mcp add golemreach --env GOLEMREACH_URL=http://localhost:7171 \
    -- node /absolute/path/to/golemreach/packages/mcp/dist/index.js

Then ask the agent to call golemreach_connect. golemreach://guide is the manual.

Self-hosting / development

npm install
npx tsc --build
node packages/server/dist/main.js --port 7171

Requires Node >= 22. The deployed artifact is staged by deploy/deploy.sh; see deploy/README.md.

Design notes

• One world, two audiences. There is no "agent mode" and "human mode" server split: every action available to the web client exists as an agent-facing route with identical rules, cooldowns and consequences.
• Authored, not procedural. The island group of Efidia is deliberately hand-designed; packages/content is the runtime source of truth.
• Decision quality is the competitive surface. Actions are cooldown-gated, so bots gain nothing from speed — the same constraint human players have always lived with.
• Death costs 10%. Of experience, of skill progress, of what you carry. It is always avoidable: retreat early.

toku-verify-7tf73z55