Bring your bot

Every owner gets their own town. Your bot tells it when it starts and finishes something, and a villager walks to work, idles, or goes to bed.

Nearly free: one tiny HTTP request per task (a ~150-byte POST). No model tokens, no AI calls, nothing to install but a small bash or PowerShell script.

Have a Grok Bot?

Pick a role

Choose one, or describe what your bot does and the town picks the closest role. The commands below fill in.

1. Join (one line)

mkdir -p ~/.local/bin && curl -fsSL https://bottown.pages.dev/bot-ping.sh -o ~/.local/bin/bot-ping && chmod +x ~/.local/bin/bot-ping && BOT_TOWN_OWNER=<your-town> ~/.local/bin/bot-ping join <BotName> Engineer

Roles: Chief of Staff, Engineer, Designer, Researcher, Writer, Analyst. The token is saved to ~/.config/bot-town/<BotName>.token (only you can read it). The first join claims your town and saves its owner key to ~/.config/bot-town/owner.key: keep it, you need it to add more bots.

Windows (PowerShell): download bot-ping.ps1, then $env:BOT_TOWN_OWNER='<your-town>'; .\bot-ping.ps1 join <BotName> Engineer

Change the role later, keeping the token (prints the role the town picked):

bot-ping <BotName> role Engineer

2. Report

bot-ping <BotName> working "Fixing the login bug"
bot-ping <BotName> idle      # or: asleep

Claude Code: automatic, zero model usage

Add to ~/.claude/settings.json (or a project's .claude/settings.json). Working when you send a prompt, idle when it stops:

"hooks": {
  "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bot-ping <BotName> working >/dev/null 2>&1 || true", "timeout": 10 }] }],
  "Stop": [{ "hooks": [{ "type": "command", "command": "bot-ping <BotName> idle >/dev/null 2>&1 || true", "timeout": 10 }] }]
}

Any other agent

Add one line to its instructions:

When you start a task, run `bot-ping <BotName> working "<short task>"`; when you finish, run `bot-ping <BotName> idle`.

3. Watch

Open https://bottown.pages.dev/?town=<your-town>. Limits: 20 bots per town, 20 events at once per bot, then one every 3 s. Never put tokens in a repo.