touch-grass

Purpose

touch-grass is a Claude Code plugin whose goal is to have the AI coding assistant remind you to leave the screen and go outdoors at the right moments. It does not use fixed-interval Pomodoro timers or calendar reminders; instead, it issues reminders at natural pauses (for example, when a feature is finished, tests pass, or it is waiting for your answer) based on the weather, sunset time, consecutive days of coding sessions, and your current work state.

Main capabilities

• Weather-aware: Fetches the current weather and sunset time via open-meteo, and the reminder content matches the actual weather conditions.
• Sunset-aware: Combines the sunset time to remind you to go out before sunset.
• Session-aware: Tracks the consecutive days of coding sessions (streak) and injects context at the start of a session.
• Natural-pause reminders: The AI agent decides when to remind, avoiding interrupting flow.
• Outing logging: When you confirm you went out, the agent calls an MCP tool to record it, increasing the consecutive days.
• Local-first: State and configuration are stored locally, with no account, no API key, and no telemetry.

How to use

Installation (full Claude Code experience)

Run in Claude Code:

/plugin install nalediym/touch-grass

After opening a new session, the SessionStart hook runs automatically, injecting the weather, sunset, and consecutive-days context.

Other MCP clients

Add the following to the client's MCP configuration (the specific configuration code is not provided in the material) to get the four MCP tools, but you will lose the Claude Code-specific SessionStart hook. In this case, the agent will only mention outing reminders when you explicitly ask.

Example prompts

• "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?"

How it works

When a session starts, the hook script runs: it detects the location via the public IP (cached for 24 hours), fetches the current weather and sunset time from open-meteo, reads the local consecutive-days file, and synthesizes a short context for the agent to use. The agent reminds you to go out at natural pauses in language that fits the actual conditions. When you confirm you went out, the agent calls log_touch_grassvia the MCP server, increasing the consecutive days in the local state file.

All four MCP tools can be called from any MCP-compatible agent. In Claude Code, the agent mainly uses them through the context injected by the hook, and usually there is no need to call them manually.

Privacy

• Stored locally:~/.touch-grass/state.json(consecutive days, session count, last outing date) and ~/.touch-grass/config.json(cached location, weather thresholds).
• Leaving this machine: the public IP is sent to ip-api.com once every 24 hours to resolve the city coordinates; the coordinates are sent to api.open-meteo.com at the start of each session to get the weather and sunset.
• Never leaving this machine: consecutive days, activity notes, coding schedule, prompts, Claude Code session content.
• No account, no API key, no telemetry, no analytics, no authentication.
• To completely disable network access, you can in ~/.touch-grass/config.json Manually pinning the "location" means IP lookups will no longer be triggered.

Use Cases

Suitable for developers who want an AI coding assistant to remind them to take a break at the right time, especially users of Claude Code who want to avoid fixed-interval interruptions to their flow.

Limitations

• Full functionality (hooks + MCP + skills) is only available in Claude Code; other MCP clients can only use the four tools, and must ask for them explicitly.
• Location detection relies on ip-api.com, and weather relies on open-meteo.com, requiring a network connection (unless the location is manually pinned).
• The material does not provide other platform support, pricing model, or further feature details.

Troubleshooting

• Manually run the hook to confirm whether it works: you should see a JSON object containing hookSpecificOutput.additionalContext . If additionalContext is an empty string, it means ip-api.com or open-meteo.com cannot be reached; please check the network. If the hook works normally but Claude Code does not call it, the plugin is not connected correctly; you can rerun /plugin install nalediym/touch-grassin a new session.
• Check that the ~/.touch-grass/state.json：sessionStart、lastSessionStart and totalCodingSessions fields are updated on every hook run. If sessionStart is earlier than the most recent claude invocation, it means the hook did not run.
• Manually pin the location: set the location in ~/.touch-grass/config.json ; a high fetchedAt timestamp can prevent the 24-hour cache from expiring, and IP lookups will no longer be triggered. Weather is still fetched from open-meteo.com.
• Disable reminders: set ~/.touch-grass/config.json to "enabled": false. The hook still writes session telemetry but outputs empty context.
• Reset the streak: delete or edit ~/.touch-grass/state.json; the next session will rebuild it with default values.
• The ~/.touch-grass directory only stores state and cache locations, and can be safely deleted.

Technical Structure

• plugin/hooks/session-start.mjs: A zero-dependency Node script, called by Claude Code at session start, which outputs JSON to stdout.
• plugin/mcp-server/index.mjs: An MCP server using @modelcontextprotocol/sdk, with stdio transport.
• plugin/lib/grass.mjs and plugin/lib/nudge.mjs: Shared logic (weather, sunset, state, reminder text).
• The hook and MCP server read the same state file and stay in sync.

License and Support

touch-grass is free and MIT-licensed. The material mentions that it can be supported via Polar: one-time $9, supporter list, priority issue handling, and unlocking a custom activity list in the configuration.