---
원문 제목: "Agent Flow: Claude Code와 Codex의 에이전트 실행 과정을 실시간 노드 그래프로 보여주는 도구"
창작 제목: "블랙박스를 열다 — AI 에이전트의 생각을 지도로 그리는 Agent Flow"
URL: https://discuss.pytorch.kr/t/agent-flow-claude-code-codex/11767
출처: PyTorchKR (작성자 9bow, 박정환) / 2026-08-31
정리: 다비(davi.kr)
정리일: 2026-09-01
태그: [Agent Flow, Claude Code, Codex, 옵저버빌리티, 에이전트 시각화, VS Code 확장]
---

> **문서의 목적**
> AI 코딩 에이전트의 실행 과정을 실시간 노드 그래프로 시각화하는 오픈소스 도구 **Agent Flow**의 기능·설치법·한계를 중학생 수준의 언어로 정리하고, 곧바로 써볼 수 있는 실행 경로를 제시합니다.

🔗 **원문 링크:** https://discuss.pytorch.kr/t/agent-flow-claude-code-codex/11767
🔗 **GitHub:** https://github.com/patoles/agent-flow (⭐ 990 · 포크 111 · Apache 2.0)

---

## 🧩 쉬운 설명

AI 코딩 도우미(Claude Code, Codex)에게 일을 시키면 화면에는 로그만 빠르게 흘러가고, 손에 남는 건 마지막 결과물뿐입니다. 결과가 틀렸을 때가 문제입니다. 에이전트가 문제를 어떻게 쪼갰는지, 어떤 도구를 어떤 순서로 불렀는지, 어디서 시간과 토큰이 새어 나갔는지를 알려면 수백 줄의 로그를 거슬러 읽어야 합니다.

**Agent Flow**는 이 과정을 **노드 그래프**(동그란 상자와 선으로 그린 흐름도)로 펼쳐 보여주는 도구입니다. 에이전트가 일하는 동안 도구 호출과 갈라짐(분기)이 실시간으로 그려지고, 노드마다 **누적 토큰과 비용**이 붙습니다. 오른쪽 패널은 비용을 에이전트별·도구별로 쪼개 주고, 아래 타임라인은 실행 전체를 시간축에 늘어놓습니다. 파일 주목도 히트맵과 메시지 기록 패널도 함께 제공됩니다. 만든 사람은 **Simon Patole**로, AI 게임 제작 플랫폼 CraftMyGame을 개발하며 직접 쓰던 도구를 공개했습니다.

---

## 🛠 활용 방법

**가장 쉬운 길: 설치 없이 명령어 한 줄로 시작하십시오.**

```bash
npx agent-flow-app
```

- 브라우저가 자동으로 열리고(기본 포트 **3001**), 다른 터미널에서 Claude Code 세션을 시작하면 이벤트가 실시간으로 흘러 들어옵니다.
- 옵션: `--port`(포트 변경), `--no-open`(브라우저 자동 실행 차단), `--verbose`(상세 로그)

**소스로 실행하려면**

```bash
git clone https://github.com/patoles/agent-flow.git
cd agent-flow && pnpm i && pnpm run setup && pnpm run dev
```
`pnpm run setup`은 Claude Code 훅 설정으로 **한 번만** 실행하면 되고, 접속 주소는 `http://localhost:3000`입니다.

**VS Code 확장으로 쓰려면** 확장 설치 후 명령 팔레트에서 `Agent Flow: Open Agent Flow` 실행 → 단축키 **Cmd+Alt+A**(맥) / **Ctrl+Alt+A**(윈도우·리눅스).

**두 런타임의 수집 방식 차이**

| 항목 | Claude Code | Codex |
|---|---|---|
| 수집 방식 | 경량 HTTP 훅 서버가 직접 수신 | 롤아웃 파일을 뒤따라 읽기 |
| 감시 대상 | `~/.claude/projects/` | `~/.codex/sessions/**/rollout-*.jsonl` |
| 지연 | 훅에서 즉시 스트리밍 | 파일 기록 후 |
| 토큰 수 | 실행 이벤트 | Codex가 직접 집계한 값 사용 |

> 감시 대상 제한은 `agentVisualizer.runtime`(VS Code) 또는 `AGENT_FLOW_RUNTIME`(CLI) 값을 `auto`/`claude`/`codex`로 지정합니다. 설정 접두사가 프로젝트명과 다른 **`agentVisualizer`**라는 점을 놓치지 마십시오.

---

## 🎯 전체 내용에 대한 전문가 의견 (사실 기반)

- **차별점은 '진행 중'입니다.** agentsview(사후 검색), CodeBurn(비용 추적 대시보드), Claude HUD(상태 표시줄)와 달리, Agent Flow는 실행이 **진행되는 동안의 구조**를 공간 배치로 드러냅니다. 목록으로는 안 보이던 불필요한 분기와 중복 작업이 눈에 들어옵니다. 반대로 지난 세션을 검색하는 작업이라면 검색 기반 도구가 더 맞습니다.
- **적합한 사용자는 명확합니다.** 하위 에이전트를 여러 개 띄우는 복잡한 워크플로우를 진단해야 하는 경우에 가장 잘 맞습니다. 단일 세션에서 간단한 편집만 맡기는 사용법이라면 그래프가 오히려 번거롭습니다.
- **실행 요건을 먼저 확인하십시오.** Node.js **20 이상**, pnpm, Claude Code CLI가 필요하며 VS Code 확장은 **1.85 이상** 호환 편집기(VS Code, Cursor, Windsurf)를 요구합니다.
- **원격 측정은 설치 방식에 따라 다릅니다.** 익명 통계는 공개된 `npx agent-flow-app`에서만 기본 활성화되고, `pnpm run dev`와 VS Code 확장은 아무것도 보내지 않습니다. 전송 항목은 세션 수·지속 시간·이벤트 수·OS/아키텍처·버전·모델 식별자 종류·오류 클래스명 등 집계값이며, **프롬프트·파일 경로·도구 호출·사용자 정보·환경 변수는 전송하지 않습니다.** 끄려면 `AGENT_FLOW_TELEMETRY=false` 또는 `DO_NOT_TRACK=1`을 설정하십시오.
- **라이선스는 Apache 2.0**으로 상업적 사용이 자유롭지만, "Agent Flow" 이름과 로고는 Simon Patole의 상표이므로 파생 배포 시 `TRADEMARK.md`를 먼저 확인해야 합니다.

---

## ✅ Bottom Line

에이전트 워크플로우를 감으로 튜닝하는 시대는 끝났습니다. 토큰과 비용이 어느 분기에서 새는지 눈으로 확인해야 프롬프트를 고칠 수 있습니다. 지금 터미널을 열고 `npx agent-flow-app` 한 줄을 실행해, 다음 Claude Code 세션부터 곧바로 관찰을 시작하십시오.

---

*본 요약은 **다비(davi.kr)**가 정리했습니다. 원문의 맥락은 상단 링크를 함께 확인해 주세요.*