Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 19. 02:29

Agent Island가 Claude Code 및 Codex 세션 상태를 감지하는 방법

요약

Agent Island는 Claude Code 및 Codex 세션의 상태를 감지하여 macOS 메뉴 바에 시각적 신호로 제공하는 도구입니다. 로컬 트랜스크립트 파일을 분석하여 작업 중, 사용자 입력 대기, 또는 중단 상태를 실시간으로 알려줍니다.

핵심 포인트

  • Claude Code 및 Codex의 로컬 JSONL 파일을 분석하여 상태 감지
  • macOS 메뉴 바(노치 영역)를 통해 작업 상태를 시각적으로 표시
  • 제3자 서비스 없이 로컬 아티팩트만 사용하여 프라이버시 유지
  • 트랜스크립트 수정 시간과 이벤트를 기반으로 한 상태 모델링

저는 긴 에이전트 기반 코딩 (agentic coding) 실행 중에 고통을 주는 작은 문제, 즉 작업이 항상 명시적으로 실패하지 않는다는 문제 때문에 Agent Island를 구축했습니다.

Claude Code 또는 Codex 세션은 여전히 작동 중일 수도 있고, 완료되어 다음 지시를 기다리고 있을 수도 있으며, 혹은 턴 중간에 멈춰버렸을 수도 있습니다. 만약 당신이 키보드에서 떨어져 있는 동안 이런 일이 발생한다면, 유일하게 확인할 수 있는 신호는 대개 터미널이나 트랜스크립트 (transcript) 파일 속에 파묻혀 있습니다.

Agent Island는 이를 MacBook 노치 (notch) / 메뉴 바 (menu-bar) 영역의 로컬 macOS 신호로 변환합니다:

  • 작동 중 (working): 제공자 로고가 숨을 쉬듯 움직임 (breathes)
  • 당신의 차례 (your turn): 제공자 로고가 회전함 (spins)
  • 정지됨 (stalled): 제공자 로고가 빨간색으로 변하며 짧은 비프음 시퀀스를 재생할 수 있음

런칭 영상: https://github.com/user-attachments/assets/d69b41e0-9298-4f17-b6c9-6014f3bd956b

저장소 (Repo): https://github.com/tristan666666/agent-island

데이터 소스는 로컬에 있습니다

Claude Code 및 Codex CLI 세션을 위한 공유된 라이브 상태 (live-state) API가 없기 때문에, Agent Island는 도구들이 이미 작성하고 있는 동일한 로컬 아티팩트 (artifacts)를 읽습니다.

Claude Code 활동은 다음 경로의 JSONL 트랜스크립트 파일에서 감지됩니다:

~/.claude/projects/*.jsonl

트리거 선택기 (trigger picker)는 더 나은 레이블과 아카이브 필터링을 위해 Claude Desktop의 세션 저장소 (session store)를 사용합니다:

~/Library/Application Support/Claude/claude-code-sessions/local_*.json

Codex 활동은 다음 경로의 최근 JSONL 세션에서 감지됩니다:

~/.codex/sessions/YYYY/MM/DD/*.jsonl

Codex 세션 레이블의 경우, Agent Island는 첫 번째 session_meta JSONL 이벤트를 읽고 그 id와 cwd를 사용합니다.

이를 통해 상태 감지를 로컬로 유지합니다. 앱은 세션이 여전히 진행 중인지 결정하기 위해 제3자 서비스가 필요하지 않습니다.

상태 모델 (The state model)

스캐너는 6초마다 실행되며 각 후보 트랜스크립트를 분류합니다. 파일 I/O는 메인 액터 (main actor) 외부에서 수행되므로 노치 UI가 반응성을 유지합니다.

핵심 입력값은 다음과 같습니다:

  • 트랜스크립트 수정 시간 (transcript modification time)
  • 마지막 몇 개의 JSONL 이벤트 (the last few JSONL events)
  • 이 앱이 출력을 생성하는 파일을 최근에 관찰했는지 여부 (whether this app has recently observed the file producing output)

현재 임계값 (thresholds)은 의도적으로 보수적으로 설정되어 있습니다:

신호 (Signal)임계값 (Threshold)의미 (Meaning)
활성 창 (active window)18초최신 트랜스크립트 쓰기가 발생하면 세션이 작동 중임을 의미합니다.
...

마지막 포인트가 중요합니다. Agent Island는 세션이 작동 중인 것을 먼저 확인한 경우에만 경보를 울립니다. 앱이 실행되었을 때 이미 오래된 트랜스크립트는 갑자기 레드 얼럿 (red alert) 상태가 되어서는 안 됩니다.

"당신의 차례 (your turn)" 감지하기

Agent Island는 트랜스크립트의 마지막 128KB(최대 200행 제한)를 테일링 (tailing) 하므로, 최근의 완료 마커 (completion marker)가 도구 출력 (tool output)의 급증으로 인해 밀려날 가능성이 낮습니다.

Claude Code의 경우, 스캐너는 어시스턴트 턴 (assistant turn)이 완료되었음을 나타내는 중단 사유 (stop reason)를 가진 어시스턴트 이벤트를 찾습니다:

stop_reason: end_turn
stop_reason: stop_sequence
stop_reason: stop

Codex의 경우, 스캐너는 Codex 이벤트 메시지를 찾습니다:

payload.type: task_complete

완료 마커가 나타나기 전에 더 새로운 task_started가 나타나면, Codex는 여전히 작업 중인 것으로 간주됩니다.

정체된 세션 (stalled sessions) 감지하기

정체된 세션은 단순히 "한동안 파일이 변경되지 않은 상태"를 의미하지 않습니다. 그렇게 하면 노이즈가 너무 많을 것입니다.

스캐너는 다음 조건이 모두 충족될 때만 정체 (stalled) 상태를 반환합니다:

  • 트랜스크립트가 최근에 작동 상태 (working state)로 관찰되었음
  • 트랜스크립트 변경이 최소 5분 동안 중단됨
  • 테일 (tail) 부분에서 새로운 턴 완료 (turn-complete) 마커가 보이지 않음
  • 세션이 여전히 15분 정체 제한 (stall cap) 범위 내에 있음

이는 앱이 중요하게 여기는 실패 모드(failure mode), 즉 활발하게 작동하다가 사용자가 보고 있지 않은 사이에 턴 중간에 멈춰버린 장시간 실행 중인 에이전트 (long-running agent)를 포착합니다.

제공자별 집계 (Aggregating per provider)

Claude와 Codex는 각각 여러 개의 후보 트랜스크립트를 가질 수 있습니다. Agent Island는 각 파일을 분류한 다음, 해당 제공자에 대해 가장 긴급한 상태를 취합니다:

유휴 (idle) < 작동 중 (working) < 당신의 차례 (your turn) < 정체 (stalled)

이를 통해 노치 (notch) UI에 하나의 Claude 상태와 하나의 Codex 상태가 표시됩니다.

자동 재개 (Auto-resume)는 상태 감지(state detection)와 별개입니다

시각적 상태 모니터(visual state monitor)는 수동적(passive)입니다. 자동 재개(Auto-resume)는 명시적(explicit)이며 선택 사항(opt-in)입니다.

트리거(trigger)는 다음을 포함합니다:

  • provider: Claude 또는 Codex
  • session id
  • working directory
  • 전송할 메시지 (message to send)
  • trigger mode
  • 활성화 상태 (enabled state)
  • 마지막 실행 시간 (last fired time)

두 가지 트리거 모드가 있습니다:

  • after reset: provider의 실제 리셋 경계(reset boundary)가 전진한 후 한 번 실행
  • every N hours: 고정된 로컬 간격(fixed local interval)으로 실행

리셋 기반 모드는 의도적으로 "지금으로부터 5시간 후"와 같이 작동하지 않습니다. 앱은 provider의 사용 저장소(usage store)를 관찰하며, 변경된 리셋 경계를 리셋 신호로 취급합니다. 이를 통해 재실행(relaunch) 시 즉시 트리거가 발생하는 것을 방지하고, Mac이 잠자기 모드(sleep) 상태여서 실제 롤오버(rollover)를 놓쳤을 경우 앱이 한 번에 따라잡을 수 있도록 합니다.

리스크 경계 (The risk boundary)

트리거가 실행되면, Agent Island는 provider의 재개 명령(resume command)을 사용하여 선택된 CLI 세션을 재개합니다. 이러한 플래그(flags)는 강력합니다. 일반적인 승인 프롬프트(approval prompts)를 우회할 수 있으며 토큰을 소비할 수 있습니다.

이것이 자동 재개가 기본 경험이 아닌 이유입니다. 앱은 README와 UI를 통해 이를 명시합니다: 신뢰할 수 있는 세션에만 트리거를 연결하십시오.

이것이 노치(notch)에 포함되어야 하는 이유

이 기능은 터미널 UI, 대시보드(dashboard) 또는 세션 브라우저(session browser)를 대체하려는 것이 아닙니다. 상세한 정보가 필요할 때는 그러한 도구들이 유용합니다.

노치는 더 좁은 목적을 위해 존재합니다. 다른 작업을 하는 동안 단 하나의 질문에 답해주는, 지속적이고 마찰이 적은(low-friction) 신호입니다:

내 에이전트가 여전히 움직이고 있는가, 나를 기다리고 있는가, 아니면 멈춰 있는가?

그것이 Agent Island가 최적화하는 표면(surface)입니다.

피드백은 언제나 환영합니다. 특히 긴 리팩터링(refactor) 및 유지보수 작업을 위해 Claude Code나 Codex를 실행하는 분들의 의견을 기다립니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0