<div align="center">

🌿 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

</div>

---

<div align="center"> <img src="./plugin/docs/demo.gif" alt="touch-grass demo — SessionStart hook injects live weather, sunset timing, and streak state; the agent nudges the user outside at a natural pause and logs the activity via the MCP server" width="860" /> </div>

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):

/plugin install nalediym/touch-grass

That's it. Open a new session — the hook fires, the context drops in, your agent takes it from there.

<details> <summary><strong>Other MCP clients</strong> (Cursor, Claude Desktop, Codex) — MCP tools only, no proactive hook</summary>

git clone https://github.com/nalediym/touch-grass
cd touch-grass/plugin/mcp-server && npm install

Then add to your client's MCP config:

{
  "mcpServers": {
    "touch-grass": {
      "command": "node",
      "args": ["/absolute/path/to/touch-grass/plugin/mcp-server/index.mjs"]
    }
  }
}

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.

</details>

How it works

flowchart LR
  A[Claude Code<br/>session starts] --> B[SessionStart hook fires]
  B --> C[ip-api.com<br/>location]
  B --> D[open-meteo.com<br/>weather + sunset]
  B --> E[~/.touch-grass/state.json<br/>streak + sessions]
  C --> F[Context injection]
  D --> F
  E --> F
  F --> G[Agent<br/>decides when to nudge]
  G -.calls.-> H[MCP tools]
  H --> E

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.

Example prompts

The plugin works ambiently, but these phrasings work well if you want to bring it up yourself:

• "Should I touch grass right now?"
• "What's my streak?"
• "Remind me to go outside before sunset."
• "I just went for a walk, log it."
• "Is it nice out?"

Privacy

Everything is local-first.

• Stored on your machine: ~/.touch-grass/state.json (streak, session counts, last touched date) and ~/.touch-grass/config.json (cached location, weather threshold).
• Leaves your machine: your public IP is sent to ip-api.com once every 24 hours to resolve city coordinates, and those coordinates are sent to api.open-meteo.com on each session start to get weather and sunset.
• Never leaves your machine: your streak, your activity notes, your coding schedule, your prompts, anything from your Claude Code session.

No accounts. No API keys. No telemetry. No analytics. No auth. If you want to disable network access entirely, pin "location" manually in ~/.touch-grass/config.json and the IP lookup never fires.

Configuration

<details> <summary>Override defaults in <code>~/.touch-grass/config.json</code></summary>

{
  "location": {
    "lat": 40.7128,
    "lon": -74.0060,
    "city": "New York",
    "timezone": "America/New_York",
    "fetchedAt": 9999999999999
  },
  "niceWeatherThresholdC": 15,
  "breakIntervalHours": 2,
  "enabled": true,
  "customActivities": [
    { "label": "walk to the corner store", "emoji": "🛒" },
    { "label": "sit on the fire escape", "emoji": "🪜" }
  ]
}

Key	Default	Description
location	auto (ip-api)	Pin to a specific location. Set fetchedAt to a future timestamp to disable auto-refresh.
niceWeatherThresholdC	15	Temperature (°C) below which weather isn't considered "nice."
breakIntervalHours	2	After this many hours of continuous coding, nudges get firmer.
enabled	true	Set to false to silence the hook without uninstalling.
customActivities	null	Replace the default activity list with your own. Each entry is { "label": "...", "emoji": "..." } or just a plain string. Supporter perk.

</details>

Troubleshooting

<details> <summary><strong>I installed the plugin but my agent doesn't mention grass at session start.</strong></summary>

Run the hook by hand to confirm it works:

node plugin/hooks/session-start.mjs

You should see a JSON object with hookSpecificOutput.additionalContext containing the nudge. If additionalContext is an empty string, the hook couldn't reach ip-api.com or open-meteo.com — check your network. If the hook is fine but Claude Code never calls it, the plugin isn't wired up — re-run /plugin install nalediym/touch-grass in a fresh session.

</details>

<details> <summary><strong>How do I know the hook actually fired in my last session?</strong></summary>

Check ~/.touch-grass/state.json. The sessionStart, lastSessionStart, and totalCodingSessions fields update every time the hook runs. If sessionStart is older than your most recent claude invocation, the hook isn't running.

</details>

<details> <summary><strong>ip-api.com is blocked on my network. Can I still use this?</strong></summary>

Yes. Pin your location manually in ~/.touch-grass/config.json:

{
  "location": {
    "lat": 40.7128,
    "lon": -74.0060,
    "city": "New York",
    "timezone": "America/New_York",
    "fetchedAt": 9999999999999
  }
}

The high fetchedAt timestamp prevents the 24h cache from expiring, so the IP lookup never fires. Weather will still be fetched from open-meteo.com.

</details>

<details> <summary><strong>How do I disable the nudges without uninstalling?</strong></summary>

Set "enabled": false in ~/.touch-grass/config.json. The hook still writes session telemetry but emits empty context, so the agent stops seeing grass reminders.

</details>

<details> <summary><strong>How do I reset my streak?</strong></summary>

Delete or edit ~/.touch-grass/state.json. The file will be recreated on the next session with defaults.

</details>

<details> <summary><strong>How do I uninstall?</strong></summary>

/plugin uninstall touch-grass
rm -rf ~/.touch-grass

The ~/.touch-grass directory only holds your state and cached location — safe to delete.

</details>

Development

git clone https://github.com/nalediym/touch-grass
cd touch-grass/plugin/mcp-server && npm install

# Test the hook directly (outputs JSON context)
node ../hooks/session-start.mjs

# Test the MCP server with the inspector
npx @modelcontextprotocol/inspector node ./index.mjs

Three moving parts:

• plugin/hooks/session-start.mjs — zero-dep Node script. Called by Claude Code on session start. Outputs JSON to stdout.
• plugin/mcp-server/index.mjs — MCP server. Uses @modelcontextprotocol/sdk. stdio transport.
• plugin/lib/grass.mjs and plugin/lib/nudge.mjs — shared logic (weather, sunset, state, nudge text).

The hook and the MCP server read from the same state file, so they stay in sync.

Related

• Claude Code plugin docs
• Model Context Protocol
• open-meteo.com — free, keyless weather API
• ip-api.com — free, keyless IP geolocation

License

MIT · Built in the shade.

---

<div align="center"> _{Your screen will be here when you get back. 🌱} </div>

Support

touch-grass is free and MIT-licensed. If it's helped you step away from the screen, consider supporting it:

Support on Polar → — $9 one-time. Your name goes in the supporters list, you get priority issues, and you unlock custom activity lists in config.

Supporters

Be the first. Support on Polar →