Guide

Telegram, plus free Cloudflare and GitHub accounts. About 10 minutes. A phone is enough; the coding-agent nudges also need the computer where Claude Code runs. Optional extras for a tidier bot: your own domain and a bot avatar.

Follow touchgrass.sh/setup, one step at a time: check you have Telegram, Cloudflare and GitHub (free accounts), make your bot, save your keys, press Deploy to Cloudflare, connect, then send /start. Stuck on a step? Its Ask AI button opens Claude or ChatGPT with our full directions. Nothing you paste there is sent to us.

In Telegram, open @BotFather (blue tick), send /newbot, pick a name and a username ending in bot. It replies with a token like 123456789:AAH…. Treat it like a password: anyone with it controls your bot.

Yes. The first person to send /start to a new bot owns it, and it ignores everyone else. It runs on your Cloudflare account, so your logs live there, not with us.

No. Moss is our mascot and the first name it offers, but you can call your bot anything. Change it any time in /settings (it renames the bot in Telegram too).

touchgrass is open source (MIT). It runs on Cloudflare's and Telegram's free tiers for normal personal use. Two costs can land on your own Cloudflare account: Workers AI past the free daily allowance (food photos on the paid plans; the bot stops itself before that), and Workers Paid ($5/mo) only if you outgrow the free limits. We charge nothing for running it.

When your coding agent has been busy for a while, your bot sends one small move: squats, a stretch, a walk. Tap ✅ done, skip, or snooze. It respects your hours, your daily cap and a gap between nudges.

On the computer where you run it: curl -fsSL touchgrass.sh | sh (Windows: irm touchgrass.sh/install.ps1 | iex), then touchgrass connect <your bot address> <agent key> and touchgrass hook claude. Send /hook to your bot for the exact connect command.

touchgrass status shows what's connected, and touchgrass test sends a test ping. Send /nudge to your bot for a move right now, whatever the rules say.

Not yet. Codex only tells us when it finishes, not when it starts, so it needs a small wrapper. It's on the list.

To pause, tap snooze on a nudge or set your hours in /settings. To disconnect Claude Code for good, run touchgrass unhook claude. It removes only our two hook entries from ~/.claude/settings.json and leaves your other hooks alone. touchgrass status confirms they're gone.

1. touchgrass unhook claude.
2. If you added the Claude Code plugin, run /plugin uninstall touchgrass@touchgrass inside Claude Code.
3. Delete the files. Mac/Linux: rm -rf ~/.touchgrass ~/.local/bin/touchgrass. Windows (PowerShell): Remove-Item -Recurse -Force $HOME\.touchgrass, then remove that folder from your user PATH (Start → "Edit environment variables for your account").
Your bot keeps working; it just stops hearing from your agent.

Type water, 500ml or 2 glasses of water, or tap the buttons from /water. Water checks only come when you're behind for the time of day.

Type the drink (flat white, red bull, 2 coffees, 150mg) or use /coffee. A plain "coffee" asks what kind. You can add sugar, mark it decaf or undo it. After your cutoff time it reminds you caffeine can cost you sleep.

/today shows today so far. A morning message recaps yesterday and your streaks.

/undo lists today's logs. Pick one and confirm to remove it.

Streaks count days in a row. Badges are earned for streaks and total moves; see them with /badges.

Send /app (or tap "open full settings" in /settings) for the mini app: today, meals, progress charts, daily ticks, this guide and every setting.

Send a photo of your meal (a caption like "200g rice" helps) or type it: 2 eggs and toast. You get a card with ✅ Log it / ✏️ Fix / ❌. Nothing is saved until you tap ✅.

The AI only works out what the food is and how much. The numbers come from the UK government's food database (CoFID), then products you scanned before, then Open Food Facts for barcodes. Only if none has it does the AI guess, and that's marked "est". Switch sources in Settings. Estimates can be wrong; they're a guide, not medical or nutrition advice.

Tap ✏️ Fix: change the grams, the calories, what it was, remove an item, or type a fix like "no rice". Calories you type always win, e.g. skewers 340g, 172 kcal per 100g. To fix a logged meal, reply to its card.

Photograph a barcode or a nutrition label for exact numbers, or use /scan and /snap to open the camera in the app. A shop receipt photo fills your kitchen, which meal ideas then use.

Ask "calories in a steak?" or "thinking of having mince and broccoli" for the numbers without logging anything.

/breakfast, /lunch, /dinner, /snack or /ideas: three ideas (about 5, 15 and 30 minutes) sized to what's left today. Tap one to log it.

Set a window in Settings. You get a message 15 minutes before it opens, when it opens, 30 minutes before it closes, and when the fast starts. /fast shows where you are; /late extends tonight only. Black coffee, plain tea and anything under about 25 kcal don't break the fast.

Send a number: 106.8, 16st 9, 235 lb. waist 113 logs your waist. Set goal steps in Settings; /goal shows progress and milestones get a little celebration. It's a log, never a judgement.

/skip 10m, /skip 1200 (jumps), /burpees 50, or just "did 30 burpees". Burned calories are shown as a bonus and never added to your food budget.

/targets and /window show and change your numbers. /deficit estimates this week from your height, age and logs. /week shows the last 7 days.

Small things you want to do each day, like an inhaler, vitamins or a stretch. Add them in Settings → Daily ticks. Each gets its own command (e.g. /inhaler), a button on the morning message and a reminder at its time if it isn't ticked.

In Settings → Daily ticks, swipe a row left and tap Delete, then Save.

Send /settings for quick changes, or open the dashboard for everything: name, personality (buddy, hype, zen, savage), timezone, hours, weekdays only, nudge level, gaps, daily cap, water target and more.

Messages can arrive with a small terminal-style GIF. Pick Paper white or Terminal dark in Settings → GIF style. Forward any GIF to your bot to add your own; you pick one section for it.

/avatar offers a few looks. Setup adds one automatically unless your bot already has a picture.

Yes, it's your code. Ask your own coding agent (Claude Code, Codex) to edit your copy, then redeploy. Your tweaks go in src/custom/ so updates don't overwrite them: extra moves, your own lines, different defaults.

The root add-on works with a TRMNL or a jailbroken Kindle on your fridge or desk, showing today's numbers. Hardware is not included, and jailbreaking a Kindle is at your own risk.

In a database on your own Cloudflare account. We can't see it. Food photos are sent to Cloudflare's Workers AI on your account to estimate them.

/export sends you everything as a file. /reset wipes your logs after asking first; your settings stay.

/export first if you want a copy. Then in Cloudflare delete your Worker and its D1 database (Workers & Pages and Storage & Databases → D1), in @BotFather send /deletebot, and delete your GitHub copy if you like. Nothing is left with us.

In @BotFather send /revoke and pick your bot. Put the new token in Cloudflare (your Worker → Settings → Variables → BOT_TOKEN), then run the connect step on /setup again.

The open-source core (user) has agent nudges, streaks, water, caffeine, the daily recap and the dashboard, with no AI. That includes weight, waist, goals, fasting, exercise and daily ticks. sudo adds the AI food features: food photos and text, barcodes, labels and the UK food database, meal ideas and calorie targets. root adds done-for-you setup and the e-ink screen setup. Every feature by plan: pricing.

Press Buy sudo or Buy root on the pricing page. One-off payment, no subscription. You get a licence key by email; add it to your bot on touchgrass.sh/upgrade (about 2 minutes, one GitHub button, your data stays). 14-day refund, see refunds.

Cloudflare often runs a first build before your copy is ready, and that one fails. Open your Worker: if the newest build says Ready, you're fine.

The setup key on /setup must equal WEBHOOK_SECRET in Cloudflare. Fix it in your Worker → Settings → Variables, or make new keys on /setup and paste both again.

Run the connect step on /setup again: it re-links your bot to Telegram. Check the BOT_TOKEN in Cloudflare is the current one from BotFather.

Nudges only come inside your hours, after the agent has been busy for the wait time, and not more than your daily cap. Run touchgrass status, then /nudge to test the bot side.

Food photos and ideas use Workers AI on your Cloudflare. The bot stops itself before the free daily allowance runs out, so you're never billed by surprise. It resets each day; water, coffee, weight and nudges keep working.

Email hello@touchgrass.sh with what you tried and a screenshot.