🌿 touch-grass

Das Claude Code-Plugin, das dich daran erinnert, nach draußen zu gehen.

Wetterbewusst · Sonnenuntergangsbewusst · Sitzungsbewusst · unterbricht nie deinen Arbeitsfluss.

Installation · Funktionsweise · Tools · Datenschutz · Website

Warum gibt es das?

Pomodoro-Timer unterbrechen deinen Arbeitsfluss. Kalender-Blöcke werden ignoriert. Der beste Zeitpunkt, um den Editor zu verlassen, ist ein bewegliches Ziel, das vom Wetter, der Tageszeit, deinem Streak und deiner aktuellen Aufgabe abhängt – all das weiß ein einfacher Intervall-Timer nicht.

Dein KI-Coding-Agent weiß bereits, wann du eine natürliche Pause machst. Er hat das Feature fertiggestellt. Er wartet darauf, dass du eine Frage beantwortest. Die Tests sind grün. Das ist der richtige Moment für einen Anstoß – nicht alle 25 Minuten auf die Sekunde genau.

touch-grass macht deinen Agenten zu einem kontextbewussten Pausen-Buddy. Ein SessionStart-Hook füttert ihn zu Beginn jeder Sitzung mit Live-Wetter- und Sonnenuntergangsdaten. Ein Skill bringt ihm einen „Tiger-Mom“-Tonfall bei (warm, spezifisch, niemals belehrend). Ein MCP-Server ermöglicht es ihm, zu protokollieren, wann du tatsächlich draußen warst. Du behältst deinen Flow. Er sorgt dafür, dass du ehrlich zu dir selbst bleibst.

Was es tut

Wie ein Pomodoro-Timer, aber er kennt das Wetter, deine Sonnenuntergangszeit und deinen Coding-Streak – und er spricht mit deinem KI-Agenten, anstatt dich zu unterbrechen.

• SessionStart-Hook fügt bei jedem Start einer Claude Code-Sitzung Live-Wetter, Sonnenuntergangszeiten und den Streak-Status in den Kontext deines Agenten ein.

• MCP-Server stellt vier Tools bereit, die dein Agent (Claude Code, Cursor, Claude Desktop, Codex) bei Bedarf aufrufen kann.

• Skill bringt dem Agenten bei, wann er dich anstupsen soll, wann er ruhig bleiben muss und welchen Tonfall er verwenden soll (Tiger-Mom, nicht belehrend).

Es ist ein Ersatz für Claude Code-Pomodoro für Leute, die lieber von ihrem Coding-Agenten nach draußen geschickt werden, als von einem bildschirmblockierenden Timer aus dem Flow gerissen zu werden.

Installation

Claude Code (volle Erfahrung — Hook + MCP + Skill):

/plugin install nalediym/touch-grass

Das war's. Starte eine neue Sitzung – der Hook wird ausgelöst, der Kontext wird eingefügt, dein Agent übernimmt den Rest.

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

Füge dann Folgendes zur MCP-Konfiguration deines Clients hinzu:

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

Du erhältst die vier MCP-Tools, verlierst aber den SessionStart-Hook, der Claude Code-spezifisch ist. Dein Agent wird das Thema „Gras“ nur ansprechen, wenn du explizit danach fragst.

Funktionsweise

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

Beim Start einer Sitzung wird ein Hook-Skript ausgeführt. Es erkennt deinen Standort anhand deiner öffentlichen IP (24 Stunden zwischengespeichert), ruft das aktuelle Wetter und die Sonnenuntergangszeit von open-meteo ab, liest deine lokale Streak-Datei und erstellt einen kurzen Kontextblock für den Agenten. Der Agent liest ihn, behält ihn im Hinterkopf und stupst dich bei einer natürlichen Pause – Feature fertig, Bug behoben, wartet auf Eingabe – dazu an, nach draußen zu gehen, mit einer Sprache, die zu den tatsächlichen Bedingungen passt.

Wenn du bestätigst, dass du draußen warst, ruft der Agent log_touch_grass über den MCP-Server auf, was deinen Streak in der lokalen Statusdatei erhöht.

MCP-Tools

Alle vier sind von jedem MCP-kompatiblen Agenten aufrufbar. In Claude Code nutzt der Agent sie meist über den Kontext, den der Hook einfügt – du musst sie selten manuell aufrufen.

Beispiel-Prompts

Das Plugin arbeitet im Hintergrund, aber diese Formulierungen funktionieren gut, wenn du das Thema selbst ansprechen möchtest:

• "Sollte ich jetzt Gras berühren?"

• "Wie ist mein Streak?"

• "Erinnere mich daran, vor Sonnenuntergang nach draußen zu gehen."

• "Ich war gerade spazieren, protokolliere das."

• "Ist das Wetter schön draußen?"

Datenschutz

Alles ist Local-First.

• Auf deinem Rechner gespeichert: ~/.touch-grass/state.json (Streak, Sitzungsanzahl, Datum des letzten „Touch-Grass“) und ~/.touch-grass/config.json (zwischengespeicherter Standort, Wetterschwellenwert).

• Verlässt deinen Rechner: Deine öffentliche IP wird alle 24 Stunden an ip-api.com gesendet, um die Stadtkoordinaten aufzulösen, und diese Koordinaten werden bei jedem Sitzungsstart an api.open-meteo.com gesendet, um Wetter und Sonnenuntergang abzurufen.

• Verlässt niemals deinen Rechner: Dein Streak, deine Aktivitätsnotizen, dein Coding-Zeitplan, deine Prompts, alles aus deiner Claude Code-Sitzung.

Keine Konten. Keine API-Schlüssel. Keine Telemetrie. Keine Analysen. Keine Authentifizierung. Wenn du den Netzwerkzugriff vollständig deaktivieren möchtest, lege "location" manuell in ~/.touch-grass/config.json fest, dann wird die IP-Abfrage nie ausgelöst.

Konfiguration

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

Fehlerbehebung

Führe den Hook manuell aus, um zu bestätigen, dass er funktioniert:

node plugin/hooks/session-start.mjs

Du solltest ein JSON-Objekt mit hookSpecificOutput.additionalContext sehen, das den Anstupser enthält. Wenn additionalContext ein leerer String ist, konnte der Hook ip-api.com oder open-meteo.com nicht erreichen – prüfe dein Netzwerk. Wenn der Hook in Ordnung ist, aber Claude Code ihn nie aufruft, ist das Plugin nicht korrekt eingebunden – führe /plugin install nalediym/touch-grass in einer neuen Sitzung erneut aus.

Prüfe ~/.touch-grass/state.json. Die Felder sessionStart, lastSessionStart und totalCodingSessions werden jedes Mal aktualisiert, wenn der Hook ausgeführt wird. Wenn sessionStart älter ist als dein letzter claude-Aufruf, läuft der Hook nicht.

Ja. Lege deinen Standort manuell in ~/.touch-grass/config.json fest:

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

Der hohe fetchedAt-Zeitstempel verhindert, dass der 24-Stunden-Cache abläuft, sodass die IP-Abfrage nie ausgelöst wird. Das Wetter wird weiterhin von open-meteo.com abgerufen.

Setze "enabled": false in ~/.touch-grass/config.json. Der Hook schreibt weiterhin Sitzungstelemetrie, gibt aber einen leeren Kontext aus, sodass der Agent keine Gras-Erinnerungen mehr sieht.

Lösche oder bearbeite ~/.touch-grass/state.json. Die Datei wird bei der nächsten Sitzung mit Standardwerten neu erstellt.

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

Das Verzeichnis ~/.touch-grass enthält nur deinen Status und den zwischengespeicherten Standort – es kann sicher gelöscht werden.

Entwicklung

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

Drei bewegliche Teile:

• plugin/hooks/session-start.mjs — Node-Skript ohne Abhängigkeiten. Wird von Claude Code beim Sitzungsstart aufgerufen. Gibt JSON an stdout aus.

• plugin/mcp-server/index.mjs — MCP-Server. Nutzt @modelcontextprotocol/sdk. stdio-Transport.

• plugin/lib/grass.mjs und plugin/lib/nudge.mjs — geteilte Logik (Wetter, Sonnenuntergang, Status, Anstups-Text).

Der Hook und der MCP-Server lesen aus derselben Statusdatei, sodass sie synchron bleiben.

Verwandtes

• Claude Code Plugin-Dokumentation

• Model Context Protocol

• open-meteo.com — kostenlose, schlüssellose Wetter-API

• ip-api.com — kostenlose, schlüssellose IP-Geolokalisierung

Lizenz

MIT · Im Schatten gebaut.

Unterstützung

touch-grass ist kostenlos und MIT-lizenziert. Wenn es dir geholfen hat, dich vom Bildschirm zu entfernen, erwäge eine Unterstützung:

Unterstützen auf Polar → — 9 $ einmalig. Dein Name erscheint in der Unterstützerliste, du erhältst Priorität bei Problemen und schaltest benutzerdefinierte Aktivitätslisten in der Konfiguration frei.

Unterstützer

Sei der Erste. Unterstützen auf Polar →