A gentle break-reminder companion for long vibecoding sessions with Codex and Claude Code.
Credit to IC for inspiring this project <3
I don't know about you, but I feel like I'm lost in a whole other different galaxy the moment I start lecturing ChatGPT. I get so sucked in: lashing out, crashing out, giving permissions every 5 minutes because I'm scared it's going to go do unintended stuff on/with my computer, and at that moment, I might as well just be a plugged-in brain in a jar, no need for anything else. I forget that as a feeble human being with a mortal body, I need water, I get hungry (which when vibecoding is peaking, I literally don't feel), I need to be able to see stuff and walk around with a functional spine when I'm 80+... stuff that makes me almost go, "why is that still my job??" when I just came off of bossing around 100 agents and feeling like the GOATest GOAT who has ever existed. But alas.
Touch Grass helps you take care of yourself when you get absorbed in vibecoding. While you work, it gives you friendly reminders to drink water, rest your eyes, stretch, walk around, eat a snack, and wrap up for bed.
It starts with a balanced routine:
- Rest your eyes every 20 minutes of active coding
- Drink water every 30 minutes
- Stretch every hour
- Take a short walk every two hours
- Get a snack at 10:30 AM and 3:30 PM
- Eat lunch at noon and dinner at 6 PM
- Wind down at 9:40 PM and head to bed at 10 PM
Each reminder has its own schedule, so you can change one without affecting the others. Everything stays on your Mac.
Touch Grass currently supports macOS.
- macOS 13 or later
- Node 18 or later, available on your
PATH - Xcode Command Line Tools, which the reminder companion is built with (
xcode-select --install)
Open any Codex or Claude Code conversation and say:
Import Touch Grass from https://github.com/jd20030807/touch-grass
Your agent will download Touch Grass, install it for your account, and open the local reminder companion. Once the welcome banner appears, automatic timing is ready—there is no separate hook approval for the desktop apps.
When installation is complete, start a new Codex task or Claude Code session and say:
Introduce Touch Grass and tell me how I can personalize it.
Touch Grass will then be available in every new conversation in that app. The timer itself already works outside the conversation: it pauses when the coding app is closed or no longer in front, and resumes when you reopen it and start using your Mac again.
Ask your agent to update Touch Grass, or run:
cd ~/.local/share/touch-grass/repository
git pull --ff-only
npm run install:macos-helper
claude plugin marketplace update touch-grass && claude plugin update touch-grass@touch-grassThe last step is for Claude Code; for Codex it is codex plugin marketplace add "$HOME/.local/share/touch-grass/repository" followed by codex plugin add touch-grass@touch-grass. Rebuilding the companion matters as much as updating the plugin — they are two halves of the same release. Start a new conversation afterwards, since an open one keeps the version it started with. If you ever suspect the two have drifted apart, ask "is Touch Grass healthy?" and your agent will check.
Touch Grass keeps its companion running in the background, so removing it takes one command:
cd ~/.local/share/touch-grass/repository
npm run uninstall:macos-helperThat stops the companion, removes it from your login items, and deletes the app. Then remove the plugin with claude plugin uninstall touch-grass@touch-grass (or codex plugin remove touch-grass@touch-grass). Your reminder preferences live in ~/.touch-grass; delete that folder if you want them gone too, or leave it and everything is waiting if you come back.
There is no settings page and no command language to learn. Just describe what you want in any new Codex or Claude Code conversation:
Remind me to walk every 40 minutes.
Move snack reminders to 11 AM and 4 PM.
Keep quiet from 10 PM to 8 AM.
Turn off bedtime reminders.
Snooze reminders for 30 minutes.
You can change one reminder, several reminders, or your whole routine whenever you like. Touch Grass will answer naturally—for example, “Okay, I won’t remind you about snacks anymore.”
Do this in a chat you started after installing. Every conversation picks up its tools at the moment it opens, so the chat you ran the installation in is usually the one chat that cannot reach Touch Grass yet. If it does not seem to understand you, open a fresh chat and ask again there. It does not matter which of the two apps you use — your routine is shared, so a change you make in one shows up in the other.
To see your current routine, ask:
What are my Touch Grass reminders?
Once the local companion is installed, it recognizes both Codex and Claude Desktop. Switching between them keeps one shared coding stretch, and closing either app pauses its contribution until you reopen it.
Install the plugin in both apps if you want to change your routine conversationally from either one. This does not create duplicate schedules: your water, stretch, and eye-rest timers remain shared, and each reminder appears once. Optional plugin hooks can also count Codex CLI, Claude Code CLI, and supported editor sessions after you review them.
You can replace the included companions with your own cat, dog, or other character. Put its animations in a folder on your Mac, then tell Codex or Claude Code where to find them:
Use my dog Mochi from /absolute/path/to/mochi.
Rotate between my companions.
Keep the folder somewhere under your home folder so the banner can read it. A complete companion needs one animation for each built-in action: water, eye rest, stretching, walking, snacking, and bedtime. Name the files after the actions and Touch Grass matches them up for you — lunch and dinner reuse your snacking animation unless you add your own. GIF and animated WebP files are supported. If anything is missing, your agent can help you finish the set.
You can also create a new kind of reminder in plain language:
Add a breathing reminder every 90 minutes.
Add a posture check every 45 minutes with this GIF.
Your own reminders work exactly like the built-in ones. If you give one its own animation it uses that; if you don't, it arrives with both bundled cats instead.
Touch Grass runs locally and keeps your preferences on your Mac. It never records your typing, clicks, code, prompts, or window titles. You can read the full details in PRIVACY.md and SECURITY.md.
Default companions, Yuzu and Nian, developed based on HWZ's real-life, lovely cats <3 bestie.
Yuzu:
Nian:
