msd-core/docs/ko-KR/context-monitor.md

컨텍스트 윈도우 모니터

에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅입니다 (Claude Code의 경우 PostToolUse, Gemini CLI의 경우 AfterTool).

문제

상태바(statusline)는 사용자에게 컨텍스트 사용량을 보여주지만 에이전트 자체는 컨텍스트 한계를 인식하지 못합니다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행하며 상태가 저장되지 않은 채 작업 도중에 멈출 수 있습니다.

동작 방식

1. statusline 훅이 컨텍스트 메트릭을 /tmp/claude-ctx-{session_id}.json에 기록합니다.
2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽습니다.
3. 남은 컨텍스트가 임계값 아래로 떨어지면 additionalContext로 경고를 주입합니다.
4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있습니다.

임계값

레벨	남은 비율	에이전트 동작
Normal	> 35%	경고 없음
WARNING	<= 35%	현재 작업 마무리, 새로운 복잡한 작업 시작 금지
CRITICAL	<= 25%	즉시 중단 후 상태 저장 (/gsd-pause-work)

Debounce

에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위한 동작입니다.

• 첫 번째 경고는 항상 즉시 발생합니다.
• 이후 경고는 5번의 도구 사용 간격이 필요합니다.
• 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회합니다.

아키텍처

Statusline Hook (gsd-statusline.js)
    | 기록
    v
/tmp/claude-ctx-{session_id}.json
    ^ 읽기
    |
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
    | 주입
    v
additionalContext -> 에이전트가 경고를 받음

브리지 파일은 단순한 JSON 객체입니다.

{
  "session_id": "abc123",
  "remaining_percentage": 28.5,
  "used_pct": 71,
  "timestamp": 1708200000
}

GSD와의 통합

GSD의 /gsd-pause-work 명령어는 실행 상태를 저장합니다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시합니다.

설정

두 훅 모두 npx @opengsd/get-shit-done-redux 설치 중에 자동으로 등록됩니다.

• Statusline (브리지 파일 기록): settings.json에 statusLine으로 등록
• Context Monitor (브리지 파일 읽기): settings.json에 PostToolUse 훅으로 등록 (Gemini의 경우 AfterTool)

~/.claude/settings.json에 수동으로 등록하는 방법 (Claude Code):

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/hooks/gsd-statusline.js"
  },
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/gsd-context-monitor.js"
          }
        ]
      }
    ]
  }
}

Gemini CLI (~/.gemini/settings.json)의 경우 PostToolUse 대신 AfterTool을 사용합니다.

{
  "hooks": {
    "AfterTool": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.gemini/hooks/gsd-context-monitor.js"
          }
        ]
      }
    ]
  }
}

안전성

• 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료합니다.
• 도구 실행을 절대 차단하지 않습니다. 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않습니다.
• 60초 이상 된 오래된 메트릭은 무시됩니다.
• 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션 등의 경우).