2026-05-08 · ~12분 분량 · ViewWork v0.1.1

내가 이 도구를 만든 이유와 사용 방법

어느 날, AI 에이전트가 내 프로젝트의 어떤 파일을 어떤 순서로 읽고 있는지 도무지 알 수 없는 순간이 왔다. 결과 코드만 보였고, "어떻게" 가 보이지 않았다. 이걸 눈으로 보고 싶었다 — 그래서 ViewWork 가 만들어졌다.

목차
  1. 왜 만들었나
  2. ViewWork 가 보여주는 것
  3. 5분 안에 시작
  4. 뷰포트 — 노드맵 + 캐릭터
  5. AI 에이전트 자동 추적
  6. 외부 활동 (URL · thinking · answer)
  7. MCP + DB 스키마
  8. dev 서버 visitor 추적
  9. 캐릭터 커스터마이즈 (이미지 · GIF · GLB)
  10. 로컬 우선 — 텔레메트리 없음
  11. 앞으로

왜 만들었나

Claude Code · Cursor · Codex 같은 AI 에이전트로 한 번이라도 "한 시간 안에 50 파일이 바뀐" 경험이 있다면 무슨 말인지 안다. 결과는 동작했지만, 어떤 순서로 어떤 파일을 거쳐 그 결과가 나왔는지 — 그 과정이 텍스트 로그 안에 묻혀버린다.

나는 두 가지가 보고 싶었다.

결국 만든 것이 ViewWork — 내 PC 안에서 동작하는 데스크톱 앱이고, 코드 디렉토리 + AI 작업 + dev 서버 트래픽을 한 화면 위에 노드 + 캐릭터로 그려준다.

ViewWork 가 보여주는 것

3D 노드맵에서 AI 에이전트 캐릭터가 파일 노드 위에서 작업
3D 씬 — 캐릭터가 노드 바로 위에서 해당 파일을 read/edit/write 중. 데이터 흐름 입자가 노드 사이를 흐름.

폴더 트리 → 3D 노드 + 엣지로 직접 매핑된다. 좌측 영역엔 폴더, 가운데엔 파일, 우측 외곽 ring 에는 외부 서비스 / MCP / DB 테이블 / visitor 가 탐색 중인 URL 이 가상 노드로 떠 있다.

캐릭터는 살아있다. AI 에이전트가 도구를 호출할 때마다 (Read · Edit · WebFetch · …) 그 호출 대상 노드 위로 캐릭터가 lerp 이동한다. 같은 노드에 여러 캐릭터가 모이면 자동으로 ring 형태로 분산해 겹치지 않는다.

5분 안에 시작

홈페이지의 다운로드 카드에서 본인 OS 의 인스톨러를 받아 설치 → 폴더 하나 선택. 이게 끝. AI 에이전트 hook 은 자동으로 인식된다. 

# 또는 npm 으로 직접 빌드
git clone https://github.com/gugu9999gu/ViewWork.git
cd ViewWork
npm install
npm run dev   # dev 모드 (Hot reload)
# 또는
npm run dist:win   # 인스톨러 빌드

뷰포트 — 노드맵 + 캐릭터

뷰포트는 2D 와 3D 두 모드를 지원한다.

레이아웃은 4가지: horizontal / vertical / radial / volumetric tree. 각 모드 (2D / 3D) 마다 독립된 설정값으로 저장된다 — 2D 에선 가독성 위주로 horizontal, 3D 에선 공간감 위주로 tree, 같은 식으로 따로 둘 수 있다.

2D React Flow 그래프 — MCP / cloud / 외부 활동 가상 노드 통합
2D 모드 — MCP 서버, cloud DB 테이블, 외부 활동 노드까지 한 그래프에 정렬.

AI 에이전트 자동 추적

ViewWork 가 가장 자랑스러워하는 부분이다. 훅 설치 / 패치 / 환경변수 설정 이 모두 필요 없다. 다음 위치의 세션 로그를 자동으로 감시한다:

이 로그를 ViewWork 가 한 줄씩 파싱 → 도구 호출(tool_use) 의 이름과 입력을 action(read · edit · write · bash · task · …) 으로 매핑하고, 매핑된 파일 노드 위로 캐릭터가 부드럽게 이동한다.

"다른 AI 에이전트도 같은 형식으로 emit 하면 즉시 추적된다. 데스크톱 앱의 도움말 → AI 에이전트 활동 업로드 경로 메뉴에 형식 + 예시가 정리되어 있다."
사이드바 — AI 작업 추적 + 라이브 트래픽
좌측 사이드바 — AI 작업 추적 / 라이브 트래픽 / 표시 옵션이 통합된 패널.

연속된 동일 (agent + 파일 + action) 이벤트는 자동으로 한 줄로 통합되고 ×N 카운트만 증가한다. 사이드바가 같은 줄로 도배되는 일이 없다.

외부 활동 (URL · thinking · answer)

AI 가 프로젝트 외부에서 작업할 때도 보고 싶었다.

이 가상 노드는 30분 동안만 살아있다 — 오래된 외부 활동은 자동으로 그래프에서 사라져 노이즈가 쌓이지 않는다.

MCP + DB 스키마

프로젝트에 .mcp.json / .cursor/mcp.json / claude_desktop_config.json 이 있으면 자동으로 모든 MCP 서버를 가상 mcp:<name> 노드로 그린다. 같은 vendor 의 노드가 2개 이상이면 플랫폼 허브 노드를 자동 생성하여 라우팅 — file → hub → 개별 mcp.

DB 스키마는 더 강력하다. Prisma schema.prisma, Drizzle 의 schema/, SQL migrations 모두 자동 파싱하여 테이블 + 컬럼 + 외래키 관계를 cloud 노드에 펼쳐놓는다. 그 위에서 코드의 supabase.from('users').select() 같은 호출이 어떤 테이블로 가는지 엣지로 그어진다.

dev 서버 visitor 추적

내장 reverse proxy 가 dev 서버 (예: localhost:3000) 앞에 붙어 모든 페이지뷰 / API 호출 / 폼 제출을 캡처한다. visitor 마다 안정적 ID 를 쿠키로 발급 (viewwork-visitor-id) — 동일 사용자의 페이지 흐름을 정확히 추적.

그리고 멋진 부분 — proxy 를 0.0.0.0 으로 LAN 공개 모드로 띄우면 같은 네트워크의 폰/태블릿이 그 URL 로 접속할 때 그 visitor 도 캐릭터로 등장한다. QA 시연이 단숨에 시각적으로 변한다.

캐릭터 커스터마이즈 (이미지 · GIF · GLB)

캐릭터는 단순한 파스텔 디스크가 기본이지만, 본인이 이미지를 등록하면 즉시 적용된다. 설정 → 캐릭터 → 폴더 열기로 폴더를 열어 PNG / SVG / GIF / WebP / AVIF / GLB / FBX 파일을 드롭. 명명 규칙은:

이미지만 표시 토글 (설정 → 캐릭터) 을 켜면 원형 배경 / 글로우를 모두 제거하고 사용자 이미지만 노출 — GIF 캐릭터의 표정이 그대로 살아남는다.

로컬 우선 — 텔레메트리 없음

ViewWork 의 모든 분석은 당신 PC 안에서 동작한다.

앞으로

핵심 시각화는 단단해졌다. 이 위에 다음을 쌓고 싶다 — DB 의 INSERT/UPDATE/DELETE 라이브 시각화, 로컬/클라우드 DB 직접 접속, 비정상 패턴 감시 + 알림, 시간축 스크럽으로 과거 재생, 팀 협업 모드. 자세한 목록은 홈페이지의 로드맵 섹션에 있다.

질문 / 버그 / 기능 제안은 데스크톱 앱의 도움말 → 피드백 보내기 (F1) 또는 문의 페이지로. 지금까지 읽어주셔서 감사합니다 — ViewWork 과 함께 코드베이스를 살아있는 무대처럼 보아주세요.

※ 이 문서는 v0.1.0 기준입니다. 최신 패치 노트는 /release/ 에서 확인.