用途

touch-grass 是一个 Claude Code 插件，目的是让 AI 编程助手在合适的时机提醒你离开屏幕、到户外活动。它不采用固定间隔的番茄钟或日历提醒，而是根据天气、日落时间、编码会话连续天数以及你当前的工作状态，在自然停顿点（例如功能完成、测试通过、等待你回答问题时）发出提醒。

主要能力

天气感知：通过 open-meteo 获取当前天气和日落时间，提醒内容会与实际天气条件匹配。
日落感知：结合日落时间，在日落前提醒你出门。
会话感知：记录编码会话连续天数（streak），并在会话开始时注入上下文。
自然停顿提醒：由 AI 代理判断何时提醒，避免打断心流。
外出记录：当你确认外出后，代理调用 MCP 工具记录，增加连续天数。
本地优先：状态和配置保存在本地，无账号、无 API 密钥、无遥测。

使用方式

安装（Claude Code 完整体验）

在 Claude Code 中运行：

/plugin install nalediym/touch-grass

打开新会话后，SessionStart 钩子会自动运行，注入天气、日落和连续天数上下文。

其他 MCP 客户端

将以下内容添加到客户端的 MCP 配置中（资料未提供具体配置代码），即可获得四个 MCP 工具，但会失去 Claude Code 特有的 SessionStart 钩子。此时代理只会在你明确询问时提及外出提醒。

示例提示

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

工作原理

会话开始时，钩子脚本运行：通过公共 IP 检测位置（缓存 24 小时），从 open-meteo 获取当前天气和日落时间，读取本地连续天数文件，合成一段简短上下文供代理使用。代理在自然停顿点用符合实际条件的语言提醒你外出。当你确认外出后，代理通过 MCP 服务器调用 log_touch_grass，在本地状态文件中增加连续天数。

四个 MCP 工具均可从任何兼容 MCP 的代理调用。在 Claude Code 中，代理主要通过钩子注入的上下文使用它们，通常无需手动调用。

隐私

存储在本地：~/.touch-grass/state.json（连续天数、会话计数、最后外出日期）和 ~/.touch-grass/config.json（缓存位置、天气阈值）。
离开本机：公共 IP 每 24 小时发送至 ip-api.com 一次以解析城市坐标；坐标在每次会话开始时发送至 api.open-meteo.com 获取天气和日落。
永不离开本机：连续天数、活动笔记、编码日程、提示词、Claude Code 会话内容。
无账号、无 API 密钥、无遥测、无分析、无认证。
如需完全禁用网络访问，可在 ~/.touch-grass/config.json 中手动固定 "location"，IP 查询将不再触发。

适用场景

适合希望由 AI 编程助手在合适时机提醒自己外出休息的开发者，尤其是使用 Claude Code 并希望避免固定间隔打断心流的用户。

限制

完整功能（钩子 + MCP + 技能）仅在 Claude Code 中可用；其他 MCP 客户端只能使用四个工具，且需显式询问。
位置检测依赖 ip-api.com，天气依赖 open-meteo.com，需要网络连接（除非手动固定位置）。
资料未提供其他平台支持、收费模式或更多功能细节。

故障排除

手动运行钩子确认是否工作：应看到包含 hookSpecificOutput.additionalContext 的 JSON 对象。若 additionalContext 为空字符串，说明无法访问 ip-api.com 或 open-meteo.com，请检查网络。若钩子正常但 Claude Code 未调用，插件未正确连接，可在新会话中重新运行 /plugin install nalediym/touch-grass。
检查 ~/.touch-grass/state.json：sessionStart、lastSessionStart 和 totalCodingSessions 字段每次钩子运行都会更新。若 sessionStart 早于最近一次 claude 调用，说明钩子未运行。
手动固定位置：在 ~/.touch-grass/config.json 中设置位置，高 fetchedAt 时间戳可防止 24 小时缓存过期，IP 查询不再触发。天气仍从 open-meteo.com 获取。
禁用提醒：在 ~/.touch-grass/config.json 中设置 "enabled": false。钩子仍写入会话遥测但输出空上下文。
重置连续天数：删除或编辑 ~/.touch-grass/state.json，下次会话会以默认值重建。
~/.touch-grass 目录仅保存状态和缓存位置，可安全删除。

技术结构

plugin/hooks/session-start.mjs：零依赖 Node 脚本，由 Claude Code 在会话开始时调用，输出 JSON 到 stdout。
plugin/mcp-server/index.mjs：MCP 服务器，使用 @modelcontextprotocol/sdk，stdio 传输。
plugin/lib/grass.mjs 和 plugin/lib/nudge.mjs：共享逻辑（天气、日落、状态、提醒文本）。
钩子和 MCP 服务器读取同一状态文件，保持同步。

许可与支持

touch-grass 免费且采用 MIT 许可。资料提到可通过 Polar 支持：一次性 $9，支持者名单、优先问题处理、解锁配置中的自定义活动列表。

touch-grass

工具介绍

用途