🌿 touch-grass

El plugin de Claude Code que te recuerda salir al exterior.

Conocedor del clima · conocedor del atardecer · conocedor de la sesión · nunca interrumpe tu flujo.

Instalación · Cómo funciona · Herramientas · Privacidad · Sitio

Por qué existe esto

Los temporizadores Pomodoro interrumpen tu flujo. Los bloques de calendario se ignoran. El mejor momento para alejarse del editor es un objetivo móvil que depende del clima, la hora del día, tu racha y en qué estás trabajando; nada de lo cual sabe un temporizador de intervalos básico.

Tu agente de programación IA ya sabe cuándo haces una pausa natural. Terminó la funcionalidad. Está esperando a que respondas una pregunta. Las pruebas salieron en verde. Ese es el momento adecuado para dar un empujón, no cada 25 minutos exactos.

touch-grass convierte a tu agente en un compañero de descanso consciente del contexto. Un hook SessionStart le proporciona el clima en tiempo real y la hora del atardecer al inicio de cada sesión. Una habilidad le enseña un tono de "madre tigre" (cálido, específico, nunca sermoneador). Un servidor MCP le permite registrar cuándo realmente saliste. Tú mantienes tu flujo. Él te mantiene honesto.

Qué hace

Como un temporizador Pomodoro, pero conoce el clima, la hora de tu atardecer y tu racha de programación, y habla con tu agente de IA en lugar de interrumpirte.

• Hook SessionStart inyecta el clima en tiempo real, la hora del atardecer y el estado de la racha en el contexto de tu agente cada vez que comienza una sesión de Claude Code.

• Servidor MCP expone cuatro herramientas que tu agente (Claude Code, Cursor, Claude Desktop, Codex) puede llamar bajo demanda.

• Habilidad enseña al agente cuándo dar un empujón, cuándo permanecer en silencio y qué tono usar (madre tigre, no sermoneador).

Es un reemplazo de Pomodoro para Claude Code para personas que prefieren que su agente de programación les diga que salgan al exterior en lugar de tener un temporizador que bloquea la pantalla y rompe su flujo.

Instalación

Claude Code (experiencia completa: hook + MCP + habilidad):

/plugin install nalediym/touch-grass

Eso es todo. Abre una nueva sesión: el hook se dispara, el contexto se carga y tu agente se encarga del resto.

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

Luego añade a la configuración MCP de tu cliente:

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

Obtienes las cuatro herramientas MCP pero pierdes el hook SessionStart, que es específico de Claude Code. Tu agente solo mencionará el césped cuando le preguntes explícitamente al respecto.

Cómo funciona

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

Al iniciar la sesión, se ejecuta un script de hook. Detecta tu ubicación a partir de tu IP pública (caché de 24h), obtiene el clima actual y la hora del atardecer de open-meteo, lee tu archivo de racha local y sintetiza un breve bloque de contexto para el agente. El agente lo lee, lo procesa y, en una pausa natural (funcionalidad terminada, error corregido, esperando entrada), te anima a salir con un lenguaje que coincide con las condiciones reales.

Cuando confirmas que saliste, el agente llama a log_touch_grass a través del servidor MCP, lo que incrementa tu racha en el archivo de estado local.

Herramientas MCP

Las cuatro son invocables desde cualquier agente compatible con MCP. En Claude Code, el agente las usa principalmente a través del contexto que inyecta el hook; rara vez necesitas llamarlas manualmente.

Ejemplos de prompts

El plugin funciona de forma ambiental, pero estas frases funcionan bien si quieres sacarlo a colación tú mismo:

• "¿Debería salir a tocar césped ahora mismo?"

• "¿Cuál es mi racha?"

• "Recuérdame salir antes del atardecer."

• "Acabo de salir a caminar, regístralo."

• "¿Está agradable afuera?"

Privacidad

Todo es local primero.

• Almacenado en tu máquina: ~/.touch-grass/state.json (racha, conteos de sesión, fecha de la última vez que saliste) y ~/.touch-grass/config.json (ubicación en caché, umbral de clima).

• Sale de tu máquina: tu IP pública se envía a ip-api.com una vez cada 24 horas para resolver las coordenadas de la ciudad, y esas coordenadas se envían a api.open-meteo.com en cada inicio de sesión para obtener el clima y el atardecer.

• Nunca sale de tu máquina: tu racha, tus notas de actividad, tu horario de programación, tus prompts, cualquier cosa de tu sesión de Claude Code.

Sin cuentas. Sin claves API. Sin telemetría. Sin analíticas. Sin autenticación. Si deseas deshabilitar el acceso a la red por completo, fija "location" manualmente en ~/.touch-grass/config.json y la búsqueda de IP nunca se activará.

Configuración

{
  "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": "🪜" }
  ]
}

Solución de problemas

Ejecuta el hook manualmente para confirmar que funciona:

node plugin/hooks/session-start.mjs

Deberías ver un objeto JSON con hookSpecificOutput.additionalContext que contiene el empujón. Si additionalContext es una cadena vacía, el hook no pudo llegar a ip-api.com o open-meteo.com: verifica tu red. Si el hook está bien pero Claude Code nunca lo llama, el plugin no está conectado: vuelve a ejecutar /plugin install nalediym/touch-grass en una sesión nueva.

Revisa ~/.touch-grass/state.json. Los campos sessionStart, lastSessionStart y totalCodingSessions se actualizan cada vez que se ejecuta el hook. Si sessionStart es más antiguo que tu invocación más reciente de claude, el hook no se está ejecutando.

Sí. Fija tu ubicación manualmente en ~/.touch-grass/config.json:

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

La marca de tiempo alta de fetchedAt evita que la caché de 24h expire, por lo que la búsqueda de IP nunca se activa. El clima seguirá siendo obtenido de open-meteo.com.

Establece "enabled": false en ~/.touch-grass/config.json. El hook sigue escribiendo telemetría de sesión pero emite un contexto vacío, por lo que el agente deja de ver recordatorios de césped.

Elimina o edita ~/.touch-grass/state.json. El archivo se recreará en la siguiente sesión con los valores predeterminados.

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

El directorio ~/.touch-grass solo contiene tu estado y la ubicación en caché; es seguro eliminarlo.

Desarrollo

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

Tres partes móviles:

• plugin/hooks/session-start.mjs — script de Node sin dependencias. Llamado por Claude Code al inicio de la sesión. Envía JSON a stdout.

• plugin/mcp-server/index.mjs — servidor MCP. Usa @modelcontextprotocol/sdk. Transporte stdio.

• plugin/lib/grass.mjs y plugin/lib/nudge.mjs — lógica compartida (clima, atardecer, estado, texto del empujón).

El hook y el servidor MCP leen del mismo archivo de estado, por lo que se mantienen sincronizados.

Relacionado

• Documentación del plugin de Claude Code

• Protocolo de Contexto de Modelo (MCP)

• open-meteo.com — API de clima gratuita y sin claves

• ip-api.com — Geolocalización IP gratuita y sin claves

Licencia

MIT · Construido a la sombra.

Soporte

touch-grass es gratuito y tiene licencia MIT. Si te ha ayudado a alejarte de la pantalla, considera apoyarlo:

Apoyar en Polar → — $9 pago único. Tu nombre aparece en la lista de colaboradores, obtienes prioridad en problemas y desbloqueas listas de actividades personalizadas en la configuración.

Colaboradores

Sé el primero. Apoyar en Polar →