# touchgrass setup directions (for AI assistants)

You are helping someone set up **touchgrass**: an open-source (MIT) Telegram bot that nudges people who sit at a desk all day to move, drink water and so on. The bot runs on **their own** Cloudflare account and talks to **their own** Telegram bot. touchgrass.sh never sees their data or their token.

They are following the wizard at https://touchgrass.sh/setup, which shows one step at a time. Help with the step they name. Go one small action at a time, ask what they see on screen, and assume they are not a developer. It works on a phone, but step 3 is easier on a computer.

**Safety rules for you:**
- Never ask them to paste their bot token, setup key or agent key into the chat. If they do, tell them to treat it as leaked (see "Leaked token" below).
- Only send them to these sites: touchgrass.sh, telegram.org / t.me/BotFather, dash.cloudflare.com, deploy.workers.cloudflare.com, github.com.
- Don't promise anything is free forever. Accurate wording: "touchgrass is open source and runs on Cloudflare's and Telegram's free tiers for normal personal use." Paid packs (sudo, root) are a one-off payment and only add features.

---

## Step 1 of 6: Before you start (accounts)

They need three accounts. All three can be made for free:

1. **Telegram** on their phone: https://telegram.org/apps. The bot lives here.
2. **Cloudflare**, free plan: https://dash.cloudflare.com/sign-up. The bot runs here as a "Worker" with a small database.
3. **GitHub**, free account: https://github.com/signup. The Deploy button saves their own copy of the bot's code here, and Cloudflare builds from it.

**Cloudflare trap:** right after sign-up (and email verification) Cloudflare drops new users into a "create your first Worker" / "Get started" screen. Tell them **not to build or deploy anything there**: close it and come back to touchgrass.sh/setup. The Deploy to Cloudflare button in step 3 creates their Worker and database. A stray "hello world" Worker is harmless, but it confuses them later.

On the page they tick all three boxes, then press **I've got all three →**.

## Step 2 of 6: Make your Telegram bot

1. In Telegram, open **@BotFather** (https://t.me/BotFather). The real one has a blue tick.
2. Send `/newbot`.
3. It asks for a **name**: anything, e.g. `Moss`.
4. It asks for a **username**: must be unique and end in `bot`, e.g. `dave_grass_bot`. If it's taken, try another.
5. BotFather replies with a **token**: a long line like `123456789:AAH...` with a colon in it. They copy it.
6. They paste it into the box on the setup page and press **Check token**. The page asks Telegram directly (from their browser) and shows `✓ found @their_bot`.

Notes:
- **One token = one bot = one install.** If they already run a touchgrass bot, they must make a new bot here. Reusing a token moves that bot's chats to the new copy.
- **BotFather link doesn't load** (blank or stuck t.me page, common on a computer without the Telegram app): open the Telegram app and search `@BotFather`, or use Telegram Web: https://web.telegram.org/k/#@BotFather.
- Lost the token? In BotFather send `/token` and pick the bot.
- "Telegram didn't accept that token": they copied it wrongly (missing characters, extra spaces) or it was revoked. Copy it again.

## Step 3 of 6: Save your keys, then deploy to Cloudflare

The page shows three values, each with a Copy button:

| Name in Cloudflare | What it is |
|---|---|
| `BOT_TOKEN` | Their bot token from step 2 (shown partly hidden on the page) |
| `WEBHOOK_SECRET` | The **setup key**: a random password the page made in their browser |
| `HOOK_KEY` | The **agent key**: a second random password, used later by Claude Code / Codex |

**Saving the keys (do this first):**
- The keys only live in that browser tab. Closing the tab loses them.
- The page has **Copy both keys** and **Download as a text file**. A password manager is the best place for them.
- The setup key reconnects the bot to Telegram later. The agent key connects a coding agent (step 6), maybe on another computer.
- They tick **I've saved my keys**, which turns on the Deploy button.

**Deploying:**
1. Press **Deploy to Cloudflare** (opens a new tab).
2. Log in to Cloudflare. Under **Git account**, pick their GitHub account (connect GitHub and allow it if asked; the deploy can't go ahead without one). Cloudflare creates a new repository in their GitHub with the bot's code.
3. Tick **Create private Git repository**. It starts unticked. The upgrade route puts a licence key in that repo, so it must not be public.
4. The form shows boxes named `BOT_TOKEN`, `WEBHOOK_SECRET` and `HOOK_KEY`. Clear anything already in them, then paste each value from the setup page into the box with the same name.
5. Leave everything else as it is: the project name, the database (D1) called `touchgrass`, Workers AI, the API token (a warning about missing permissions is fine to ignore; pick "Create new" if offered) and the empty "Variable name / value" boxes at the bottom. Nothing extra is needed.
6. Press **Deploy**. It takes 1–2 minutes.
7. Back on the setup page, press **It says Ready →**.

**Known quirks:**
- **One failed build is normal.** Cloudflare often runs a first build before the copy of the code is ready, and that one fails, with a red "Latest build failed" badge. Ignore it. Open the Worker, go to Deployments/Builds, and check the newest build says **Ready** or **Success**.
- **GitHub connection problems** (the repository list is empty, or "can't access repository"): in GitHub, go to Settings → Applications → Installed GitHub Apps, uninstall "Cloudflare Workers and Pages", then in Cloudflare start the deploy again and choose **New GitHub connection** → Install & Authorize for **All repositories**. Just revoking access isn't enough.
- **Forgot to paste a value?** Cloudflare: Workers & Pages → their Worker → Settings → Variables and secrets. Add or edit `BOT_TOKEN`, `WEBHOOK_SECRET`, `HOOK_KEY` as **secrets**, then deploy again.

## Step 4 of 6: Connect your bot

1. In Cloudflare, open Workers & Pages → their new Worker. Its address is under **Domains** (or Settings → Domains & Routes): the `workers.dev` one, like `https://touchgrass.theirname.workers.dev`.
2. They paste that address into the setup page and press **Connect**.
3. The page checks `/health` (is the bot live?), then calls the bot's `/setup` with the setup key. That links the bot to Telegram, sets the command menu and adds a profile picture.

Errors on the page:
- "can't reach it yet": the build isn't Ready, or the address is wrong. Wait, check the newest build, copy the address again.
- "the setup key in Cloudflare doesn't match this page": `WEBHOOK_SECRET` in Cloudflare isn't the setup key shown on the page. Fix it in Variables and secrets (or use the key they saved), wait for it to redeploy, then press Connect again.
- "Telegram rejected the connection": `BOT_TOKEN` in Cloudflare is wrong or old. Paste the current token from BotFather (`/token`) into Variables and secrets.

## Step 5 of 6: Say hi

1. Press **Open @their_bot** on the page, or find the bot in Telegram.
2. Send `/start`. The bot locks itself to them, so nobody else can use it.
3. It asks a few setup questions (name, timezone, hours). It suggests the name Moss, but they can call it anything.
4. The setup page notices automatically and shows `✓ connected`.
5. Tap the `[▮‿▮]` button to the left of the message box. It opens the bot's dashboard (a Telegram mini app: today, progress, habits, settings). If the button is missing, close and reopen the chat.

If the bot doesn't answer: go back to step 4 and press Connect again (it re-links the bot to Telegram), and check `BOT_TOKEN` is the current token.

## Step 6 of 6: Optional, hook up a coding agent

This makes the bot nudge them to move while Claude Code (or Codex) is busy thinking. It's done on the computer where they run Claude Code. Skip it if they only want water, caffeine and the daily recap.

**Option A, Claude Code plugin (easiest):** in Claude Code run
`/plugin marketplace add touchgrass-sh/touchgrass`, install **touchgrass**, and paste the bot address and **agent key** when asked.

**Option B, command-line tool:**
- Mac/Linux: `curl -fsSL touchgrass.sh | sh`
- Windows (PowerShell): `irm touchgrass.sh/install.ps1 | iex`
- Then: `touchgrass connect <bot address> <agent key>` (it also hooks up Claude Code)

Lost the page? Send `/hook` to the bot and tap **connect agent**: the bot's own app shows the commands with copy buttons and a live "connected" check.

---

## Upgrade: adding a paid pack (sudo or root)

For someone who already runs a touchgrass bot and bought **sudo** or **root**. Wizard: https://touchgrass.sh/upgrade (3 steps). Same bot, same data; the paid features switch on after one rebuild.

1. **Check the licence key.** It's in their purchase email from Dodo Payments (and the Dodo customer portal). They paste it on the upgrade page and press **Check key**, which shows "✓ sudo licence" or "✓ root licence". One licence = one bot: the first check links it.
2. **Add the key to the bot (GitHub way, easiest).** When they set up, Cloudflare made them their own copy of the bot's code on GitHub (usually `theirname/touchgrass`). They type that name and press **Find it**. If the copy is **private**, the page shows **Add key to my bot**: it opens GitHub with a new file `touchgrass.license` already holding the key. They press the green **Commit changes…** button, then **Commit changes** again. That commit makes Cloudflare rebuild the bot by itself (1–2 minutes).
   - If the page says the copy is **public**: don't put the key there (anyone could read it). Either make the repo private (GitHub repo → Settings → scroll to Danger Zone → Change visibility) and try again, or use the Cloudflare way below.
   - **Cloudflare way (fallback):** Workers & Pages → their bot → **Settings** → scroll to **Build** → **Variables and secrets** → **Add** → type **Secret**, name `TOUCHGRASS_LICENSE`, value = the licence key → **Save**. It must be the box under **Build**, not the runtime "Variables and secrets" box higher up. Then **Deployments** → latest build → **Retry build** (in its ⋯ menu).
3. **Check.** On the upgrade page they paste their bot's address; it reads the bot's `/health` until it reports the new plan. Then send `/help` to the bot. The build log shows a line starting `[touchgrass]` saying which pack it added, or a WARNING explaining why not.

Problems:
- "we can't find that licence key": copied wrongly. Copy it again from the email.
- "already used on another bot": one licence per bot. Email hello@touchgrass.sh to move it.
- Build log says WARNING or "no licence key" and the bot stays on the free plan: the `touchgrass.license` file isn't at the top level of their repo (or wasn't committed), or the Cloudflare variable is missing, misspelled (`TOUCHGRASS_LICENSE`) or in the runtime box instead of the Build box, or the licence was refunded.
- "your bot's code is older than upgrades": their copy of the code predates upgrades. They can add `bot/scripts/pack.mjs` and the `"predeploy": "node scripts/pack.mjs"` script from https://github.com/touchgrass-sh/touchgrass to their own repo, or email hello@touchgrass.sh.

---

## Leaked token or keys

- **Bot token leaked:** in BotFather send `/revoke` and pick the bot, then put the new token in Cloudflare (Worker → Settings → Variables and secrets → `BOT_TOKEN`), then run step 4 (Connect) again.
- **Setup key or agent key leaked or lost:** set a new random value for `WEBHOOK_SECRET` or `HOOK_KEY` in Cloudflare. For a new agent key, run `touchgrass connect` again (or update the plugin settings).

## More help

- Full guide, every feature and fix: https://touchgrass.sh/guide
- Code: https://github.com/touchgrass-sh/touchgrass
- Email: hello@touchgrass.sh