patoles/agent-flow

Agent Flow – Claude Code 및 Codex 에이전트를 위한 시각적 디버거

소개 – Claude Code 및 Codex AI 에이전트의 숨겨진 내부 작동 방식을 대화형 노드 그래프로 변환하는 실시간 시각화 도구입니다. 에이전트가 문제를 단계별로 분해하고, 도구를 호출하고, 하위 에이전트를 생성하고, 결과를 반환하는 과정을 보여주어 전체 "사고 과정"을 실시간으로 관찰할 수 있습니다.

중요성 – AI 기반 애플리케이션(예: Antics 게임 제작 플랫폼)을 구축할 때 개발자는 종종 LLM 에이전트의 최종 출력만 볼 수 있어 디버깅이 추측에 의존하게 됩니다. Agent Flow는 실행 추적, 도구 호출 체인 및 타이밍 정보를 노출하므로 느리거나 오류가 있는 단계를 정확히 찾아내고, 분기 논리를 이해하며, 프롬프트 엔지니어링을 개선할 수 있습니다.

주요 기능

• 실시간 시각화 – 팬/줌이 가능한 대화형 캔버스; 노드는 추론 단계, 도구 호출 및 하위 에이전트를 나타냅니다.
• 듀얼 런타임 지원 – Claude Code와 Codex를 동시에 지원하며, 나란히 보거나 설정으로 하나만 제한할 수 있습니다.
• 제로 지연 스트리밍 – 경량 HTTP 훅이 Claude Code 이벤트를 직접 수신하며, Codex 이벤트는 롤아웃 JSONL 로그에서 읽어옵니다.
• 멀티 세션 처리 – 여러 동시 에이전트 세션이 탭으로 표시됩니다.
• 타임라인 및 트랜스크립트 패널 – 시간순 보기, 파일 주의 히트맵 및 전체 메시지 트랜스크립트를 확인할 수 있습니다.
• JSONL 재생 – 저장된 이벤트 로그를 로드하여 이전 세션을 재생합니다.
• VS Code 확장 프로그램 – 단일 명령 또는 단축키(Cmd/Ctrl+Alt+A)로 편집기 내에서 시각화 도구를 엽니다.

사용 방법

1. 빠른 시작 – npx agent-flow-app (Node 20+, pnpm)을 실행하면 localhost:3001에서 브라우저 창이 열립니다.
2. 소스에서 실행 – 리포지토리를 복제하고 pnpm i && pnpm run setup && pnpm run dev를 실행합니다. 개발 서버는 Next.js 웹 앱과 UI로 SSE 데이터를 스트리밍하는 이벤트 릴레이를 호스팅합니다.
3. VS Code – 확장 프로그램을 설치한 후 명령 팔레트에서 Agent Flow: Open Agent Flow를 실행합니다.
4. 구성 – agentVisualizer.runtime 설정 또는 AGENT_FLOW_RUNTIME 환경 변수를 사용하여 Claude, Codex 또는 둘 다를 선택합니다. agentVisualizer.eventLogPath를 .jsonl 파일로 지정하여 오프라인 로그를 시각화합니다.

일반적인 워크플로우

• 터미널에서 Claude Code 또는 Codex 세션을 시작합니다.
• Agent Flow가 자동으로 세션을 감지하고 이벤트 스트리밍을 시작합니다.
• 그래프가 성장하는 것을 관찰합니다: 각 노드는 추론 스니펫, 호출된 도구 및 타이밍을 보여줍니다.
• 노드를 클릭하여 세부 정보(프롬프트, 응답, 토큰 수 등)를 검사합니다.
• 타임라인 패널을 사용하여 병목 현상이나 예상치 못한 분기를 찾습니다.

개인정보 보호 – 텔레메트리는 옵트아웃이 가능하며 익명화된 집계 데이터(세션 수, 기간, 모델 ID, OS)만 전송합니다. 프롬프트, 파일 경로 또는 사용자 데이터는 기기 외부로 나가지 않습니다. AGENT_FLOW_TELEMETRY=false 또는 DO_NOT_TRACK=1을 통해 비활성화할 수 있습니다.

개발자 – Simon Patole (Antics AI 기반 게임 제작 플랫폼 제작자).

라이선스 – Apache 2.0.

---

Agent Flow는 LLM 에이전트 런타임을 시각화하고 디버깅하기 위한 순수 오픈 소스 도구이며, AI/에이전트 도구 생태계에 완벽하게 부합합니다.