피드로 돌아가기
Dev.toInfrastructure
원문 읽기
Local Artifacts 모니터링을 통한 AI Agent 상태 감지 및 시각화 시스템 구축
How Agent Island Detects Claude Code and Codex Session State
AI 요약
Context
Claude Code 및 Codex와 같은 CLI 기반 AI Agent의 실행 상태를 실시간으로 파악할 API 부재로 인한 모니터링 공백 발생. 터미널 로그를 직접 확인해야 하는 높은 인지 부하와 세션 프리즈(Freeze) 감지 지연 문제를 해결하기 위한 로컬 신호 체계 필요.
Technical Solution
- 별도 API 없이 ~/.claude 및 ~/.codex 경로의 JSONL Transcript 파일을 직접 읽는 Local-first 상태 감지 아키텍처 설계
- UI 응답성 확보를 위해 메인 액터 외부에서 파일 I/O를 처리하는 비동기 스캐너 구현
- 단순 파일 변경 여부가 아닌 Modification Time, JSONL Event, 관찰 이력을 조합한 상태 분류 모델 적용
- Tail-reading 기법(최근 128KB/200라인 제한)을 통해 대량의 Tool Output 발생 시에도 Completion Marker 유실 방지
- Idle < Working < Your Turn < Stalled 순의 우선순위 기반 상태 Aggregation 로직으로 다중 세션 상태 통합
- Provider Usage Store의 Reset Boundary 변경점을 추적하는 이벤트 기반 Auto-resume 트리거 설계
실천 포인트
1. 외부 의존성 없는 상태 감지를 위해 로컬 로그 파일의 Modification Time 및 Tail 영역 분석 검토
2. UI 프리징 방지를 위해 무거운 File I/O 작업을 메인 스레드에서 분리하여 비동기 처리
3. 단순 상태 변경이 아닌 '관찰된 상태 -> 변화 없음 -> 특정 임계값 도달'의 시퀀스를 통한 Stall 상태 정의로 노이즈 제거
4. 리소스 낭비를 막기 위해 전체 파일이 아닌 최신 버퍼 영역(Tail)만 읽는 최적화 적용