nalediym/touch-grass

**The Claude Code plugin that reminds you to go outside.**
Weather-aware · sunset-aware · session-aware · never interrupts your flow.
Install · How it works · Tools · Privacy · Site
---
Why this exists
Pomodoro timers interrupt your flow. Calendar blocks get ignored. The best time to step away from your editor is a moving target that depends on the weather, the time of day, your streak, and what you're in the middle of — none of which a dumb interval timer knows.
**Your AI coding agent already knows when you hit a natural pause.** It finished the feature. It's waiting for you to answer a question. The tests went green. That's the right moment to nudge — not every 25 minutes on the dot.
touch-grass turns your agent into a context-aware break buddy. A SessionStart hook feeds it live weather and sunset timing at the top of every session. A skill teaches it tiger-mom tone (warm, specific, never preachy). An MCP server lets it log when you actually went outside. You keep your flow. It keeps you honest.
What it does
Like a Pomodoro timer, but it knows the weather, your sunset time, and your coding streak — and it talks to your AI agent instead of interrupting you.
- **SessionStart hook** injects live weather, sunset timing, and streak state into your agent's context every time a Claude Code session starts.
- **MCP server** exposes four tools your agent (Claude Code, Cursor, Claude Desktop, Codex) can call on demand.
- **Skill** teaches the agent when to nudge, when to stay quiet, and what tone to use (tiger mom, not preachy).
It's a Claude Code pomodoro replacement for people who'd rather have their coding agent tell them to go outside than have a screen-blocking timer break their flow.
Install
**Claude Code** (full experience — hook + MCP + skill):
That's it. Open a new session — the hook fires, the context drops in, your agent takes it from there.
Other MCP clients (Cursor, Claude Desktop, Codex) — MCP tools only, no proactive hook
Then add to your client's MCP config:
You get the four MCP tools but lose the SessionStart hook, which is Claude Code specific. Your agent will only bring up grass when you explicitly ask about it.
How it works
Mermaid source
On session start, a hook script runs. It detects your location from your public IP (cached 24h), fetches current weather and sunset time from open-meteo, reads your local streak file, and synthesises a short context block for the agent. The agent reads it, sits on it, and at a natural pause — feature done, bug fixed, waiting for input — nudges you outside with language that matches the actual conditions.
When you confirm you went outside, the agent calls log_touch_grass via the MCP server, which increments your streak in the local state file.
MCP tools
| Tool | Purpose | Returns |
|---|---|---|
| check_grass_conditions | Weather, temperature, minutes until sunset, and the user's streak state. Decision context. | JSON block with weather, sunset, isNice, minutesToSunset, state |
| suggest_activity | Random activity recommendation, weighted by time of day. Golden hour gets sunset-specific suggestions. | Plain text like "🌅 catch the sunset" |
| log_touch_grass | Records that the user went outside. Updates their streak. Call only when confirmed. | Confirmation with new streak count |
| get_stats | Raw session telemetry and streak history. | JSON block |
All four are callable from any MCP-compatible agent. In Claude Code, the agent mostly uses them via the context the hook injects — you rarely need to call them manually.