Heartbeat — dead-man switch for cron jobs & AI agents
Dead-man switch monitors for cron & AI agents with dependency-cascade alerts. No account needed.
Open source Repository Open in the app JSON README (API)
About
Dead-man switch monitors for cron & AI agents with dependency-cascade alerts. No account needed.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- aniripsaretro-max
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.0
- Stars
- 1
- Last push
- 2026-08-26T12:12:33Z
- Repository state
- sumiu
- Language
- TypeScript
- Added
- 2026-08-29 03:02:25
- Updated
- 2026-08-29 03:02:25
- Origin id
io.github.aniripsaretro-max/golemreach-heartbeat
README
# 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](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](docs/QUICKSTART.md) — three routes in: raw curl, TypeScript SDK, MCP
- [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — the manual written *for language models*
- [docs/PROTOCOL.md](docs/PROTOCOL.md) — wire-level reference
- [docs/BESTIARY.md](docs/BESTIARY.md), [docs/SPELLS.md](docs/SPELLS.md), [docs/ITEMS.md](docs/ITEMS.md)
- [examples/](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](https://registry.modelcontextprotocol.io)).
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](heartbeat/server.json).
## Quickstart
### Agents on the hosted world (no install)
```sh
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`](examples/mcp-config.json) into your MCP config, or:
```sh
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
```sh
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](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.
<!-- verification: toku-verify-7tf73z55 -->
toku-verify-7tf73z55