🌿 touch-grass

밖으로 나가라고 알려주는 Claude Code 플러그인.

날씨 인식 · 일몰 인식 · 세션 인식 · 작업 흐름을 방해하지 않습니다.

설치 · 작동 원리 · 도구 · 개인정보 보호 · 사이트

왜 필요한가요?

뽀모도로 타이머는 작업 흐름을 방해합니다. 캘린더 알림은 무시되기 일쑤입니다. 편집기에서 잠시 벗어나기에 가장 좋은 시간은 날씨, 시간대, 연속 기록, 그리고 현재 작업 중인 내용에 따라 달라지는 유동적인 목표입니다. 단순한 간격 타이머는 이런 것을 알지 못합니다.

당신의 AI 코딩 에이전트는 이미 당신이 자연스럽게 멈추는 순간을 알고 있습니다. 기능을 완성했거나, 당신의 답변을 기다리고 있거나, 테스트가 통과했을 때가 바로 그때입니다. 25분마다 딱딱 끊어지는 타이머가 아니라, 바로 그 순간이 권장하기 가장 좋은 때입니다.

touch-grass는 당신의 에이전트를 상황을 인식하는 휴식 파트너로 바꿔줍니다. SessionStart 훅은 매 세션 시작 시 실시간 날씨와 일몰 시간을 에이전트에게 전달합니다. 스킬은 에이전트에게 따뜻하고 구체적이며 잔소리 같지 않은 어조를 가르칩니다. MCP 서버는 당신이 실제로 밖에 나갔을 때 이를 기록할 수 있게 해줍니다. 당신은 작업 흐름을 유지하고, 에이전트는 당신의 건강을 챙겨줍니다.

주요 기능

뽀모도로 타이머와 비슷하지만, 날씨, 일몰 시간, 코딩 연속 기록을 알고 있으며, 당신을 방해하는 대신 AI 에이전트와 대화합니다.

• SessionStart 훅: Claude Code 세션이 시작될 때마다 실시간 날씨, 일몰 시간, 연속 기록 상태를 에이전트의 컨텍스트에 주입합니다.

• MCP 서버: 에이전트(Claude Code, Cursor, Claude Desktop, Codex)가 필요할 때 호출할 수 있는 4가지 도구를 제공합니다.

• 스킬: 에이전트에게 언제 권장하고 언제 조용히 있어야 할지, 어떤 어조(잔소리하지 않는 따뜻한 조언자)를 사용해야 할지 가르칩니다.

이것은 화면을 가리는 타이머로 작업 흐름을 깨는 대신, 코딩 에이전트가 밖으로 나가라고 말해주길 원하는 사람들을 위한 Claude Code 뽀모도로 대체 도구입니다.

설치

Claude Code (전체 기능 — 훅 + MCP + 스킬):

/plugin install nalediym/touch-grass

설치는 끝입니다. 새 세션을 열면 훅이 실행되고 컨텍스트가 전달되며 에이전트가 알아서 처리합니다.

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

그런 다음 클라이언트의 MCP 설정에 추가하세요:

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

4가지 MCP 도구를 사용할 수 있지만, Claude Code 전용인 SessionStart 훅은 사용할 수 없습니다. 에이전트는 당신이 직접 물어볼 때만 잔디(grass)에 대해 언급할 것입니다.

작동 원리

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

세션이 시작되면 훅 스크립트가 실행됩니다. 공용 IP(24시간 캐시)를 통해 위치를 감지하고, open-meteo에서 현재 날씨와 일몰 시간을 가져오며, 로컬 연속 기록 파일을 읽어 에이전트를 위한 짧은 컨텍스트 블록을 생성합니다. 에이전트는 이를 읽고 기억하다가, 기능 구현 완료나 버그 수정 후 입력 대기 중과 같은 자연스러운 휴식 시간에 실제 날씨 상황에 맞는 언어로 밖으로 나가라고 권장합니다.

당신이 밖에 나갔음을 확인하면, 에이전트는 MCP 서버를 통해 log_touch_grass를 호출하여 로컬 상태 파일의 연속 기록을 증가시킵니다.

MCP 도구

4가지 도구 모두 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 조회가 실행되지 않습니다.

설정

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

문제 해결

훅을 직접 실행하여 작동하는지 확인하세요:

node plugin/hooks/session-start.mjs

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에서 위치를 수동으로 고정하세요:

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

fetchedAt 타임스탬프를 높게 설정하면 24시간 캐시가 만료되지 않아 IP 조회가 실행되지 않습니다. 날씨는 여전히 open-meteo.com에서 가져옵니다.

~/.touch-grass/config.json에서 "enabled": false로 설정하세요. 훅은 여전히 세션 원격 측정을 기록하지만 빈 컨텍스트를 출력하므로 에이전트가 잔디 알림을 표시하지 않습니다.

~/.touch-grass/state.json을 삭제하거나 편집하세요. 다음 세션에서 파일이 기본값으로 다시 생성됩니다.

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

~/.touch-grass 디렉토리에는 상태와 캐시된 위치만 저장되어 있으므로 삭제해도 안전합니다.

개발

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

세 가지 구성 요소:

• 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 서버는 동일한 상태 파일을 읽으므로 동기화 상태를 유지합니다.

관련 링크

• Claude Code 플러그인 문서

• Model Context Protocol

• open-meteo.com — 무료, 키 없는 날씨 API

• ip-api.com — 무료, 키 없는 IP 지리적 위치 API

라이선스

MIT · 그늘에서 제작됨.

후원

touch-grass는 무료이며 MIT 라이선스를 따릅니다. 화면에서 잠시 벗어나는 데 도움이 되었다면 후원을 고려해 주세요:

Polar에서 후원하기 → — 9달러 일회성 후원. 후원자 목록에 이름이 올라가며, 이슈 우선 처리 혜택을 받고 설정에서 사용자 지정 활동 목록을 잠금 해제할 수 있습니다.

후원자

첫 번째 후원자가 되어주세요. Polar에서 후원하기 →