Touch Grass README | AllMCPs

🌿 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

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

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

bash

/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.

Other MCP clients (Cursor, Claude Desktop, Codex) — MCP tools only, no proactive hook

bash

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

Then add to your client's MCP config:

config.json

{
  "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.

How it works

Mermaid source

mermaid

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

Override defaults in ~/.touch-grass/config.json

config.json

{
  "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.

Troubleshooting

I installed the plugin but my agent doesn't mention grass at session start.

Run the hook by hand to confirm it works:

bash

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.

How do I know the hook actually fired in my last session?

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.

ip-api.com is blocked on my network. Can I still use this?

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

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.

How do I disable the nudges without uninstalling?

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.

How do I reset my streak?

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

How do I uninstall?

bash

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

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

Development

bash

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.