이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.
Mac에서 실행 중인 Claude Code CLI 세션을 공간적 RPG 스타일 시각화 도구로 보여줍니다. 실행 중인 각 claude 프로세스는 30×30 마을을 걷는 스프라이트가 되고, 각 저장소는 건물이 되며, 권한 프롬프트는 정보 데스크에 줄을 서서 대기하고, 도구 호출은 머리 위에 이모지로 표시됩니다.
!Agent World 라이브 데모
Park et al., "Generative Agents: Interactive Simulacra of Human Behavior" (논문 · 원본 저장소)와 claude-control에서 영감을 받았습니다 (발견 모델 — ps + lsof + 훅 파일, 데이터베이스 없음 — 을 차용했습니다).
npm install && npm start만으로 작동하는 마을을 얻을 수 있습니다. 유료 에셋 팩 필요 없음; 선택적 PixyMoon 업그레이드 경로 제공.claude 프로세스가 부드러운 서브타일 보간으로 스프라이트로 렌더링됩니다. 저장소 = 건물; cwd = 책상. SessionEnd 시 출구로 걸어가서 사라집니다.Working → 책상에 앉음; Waiting (권한 프롬프트) → 깜빡이는 호박색 후광과 함께 정보 데스크 줄에 합류; Errored → 선술집으로 이동; Idle → 건물 근처 배회; Finished → 출구로 걸어가서 사라짐.Bash 🖥 · Edit/Write ✏ · Read 📖 · Grep 🔎 · Task 👥 · WebFetch 🌐. 새로운 도구 호출 시마다 떠다니는 팝 이모트가 애니메이션; 기본 아이콘은 아래에서 크로스페이드.. .. ... 순환 — 추가 레이어 없음.demo/demo-social.gif) — 상황 인식 주변 대화, 스테이션 종류 포즈, 이웃 반응, 그룹 장면. 자세한 내용은 아래 표 참조.!소셜 레이어
interactionKind 값에서 클라이언트 파생):| 스테이션 종류 | 포즈 | 지속 이모트 | ||
|---|---|---|---|---|
| desk, archive | 타이핑 (Working) / 기대기 (Idle) | — | ||
| tavern, cafe | 마시기 (1.2초 머그잔 올리기 사이클) | 🍺 | ||
| monitor_wall | 지켜보기 | 📺 | ||
| bed, nap_spot | 잠자기 | 💤 | ||
| break_area | 도착 시 스트레칭 스쿼시 (800ms) | — | ||
| queue_slot | 초조함 — 4초마다 얼굴 방향 좌↔우 전환 | — | ||
| exit | 작별 인사 (1.5초 스케일 + 바운스) — 도착 시 fadeOpacity > 0.85일 때만 재생되어 대부분 사라진 스프라이트가 다시 나타나지 않음 | 👋 | ||
| plaza, lounge | 기대기 | — | ||
| work_outdoor | 타이핑 (채광 / 채집) | — |
| 이벤트 | 근처 에이전트 반응 | 반경 | 쿨다운 | ||
|---|---|---|---|---|---|
| 이웃이 Errored 진입 | 😦 + 소스 방향으로 1틱 고개 돌림 | 4 | 20초 | ||
| 이웃이 생산성 폭발 시작 | ✨ | 4 | 30초 | ||
| 자신 Waiting→Working (승인됨) | 🎉 | — | — | ||
| 이웃이 작별 인사 시작 | 👋 | 3 | 60초 |
첫 틱 페이지 로드 전환은 여러 이미 Errored 상태인 세션이 뷰를 넘치지 않도록 억제됩니다. 전역 제한: 한 번에 최대 3개의 활성 이모트; 가장 먼저 만료되는 것이 먼저 제거되고, 동률 시 에이전트 ID 사전순 (결정적).
!낮 / 밤 !밤
!UX 개요
📜 대화록 탭은 1.5초 폴링으로 JSONL을 테일링; 🎛 라이브 탭은 라이브 PTY를 연결 (병렬 claude --resume 실행 전 이중 언어 논블로킹 확인).assistant.usage를 가져와 모델별 Anthropic 가격 (Opus / Sonnet / Haiku; 입력, 출력, 캐시 쓰기, 캐시 읽기 별도 청구)에 대해 계산. 콜드 스타트는 기록 스캔을 세션당 1.5MB로 제한하여 시작이 절대 지연되지 않음.!💰 비용 배지
npm run install-hooks -- --apply), Claude는 권한 프롬프트에서 차단; Agent World는 훅 플러그인을 통해 요청을 포착하고 브라우저에 허용 / 거부 / 터미널 포커스 토스트를 렌더링합니다. 결정은 <100ms 내에 CLI로 왕복합니다. 탭이 백그라운드에 있을 때 처음으로 데스크톱 알림이 발송 (사용자 제스처 권한 필요). 훅이 없어도 토스트는 읽기 전용 폴백 모드로 계속 표시되어 (세션이 Waiting으로 감지, "터미널 포커스"만 표시) 무엇이 차단되었는지 알 수 있습니다.!🔒 권한 토스트
now, 12s, 3m). 600px 이하 뷰포트에서는 숨겨져 휴대폰에서도 세계를 볼 수 있음.● LIVE / ⏸ PAUSED 배지 표시.Waiting > Errored > 활성 도구 > 최근 어시스턴트 스니펫 > 스테이션 > 비어 있음)를 가지며, 낮은 우선순위 다운그레이드 시 최소 2.5초 유지. 높은 우선순위 이벤트는 즉시 선점. 혼합 이벤트 소스의 "깜빡이는 텍스트" 문제 해결.repoRoot → SAME_REPO 풀 ("{repo} 작업 중이야?")ERROR_COMMISERATE ("또 레드 빌드야?")WAITING_SUPPORT ("승인 막혔어?")RECONNECT ("또 왔네?") — 각 런타임의 chatLastMetAt에 키 지정된 메모리MORNINGGREETINGS / LUNCHGREETINGS / EVENINGGREETINGS / NIGHTGREETINGS) 벽시계 시간에서 선택🧘 차분 / 🎭 보통 / 🎉 활기참) — 상단 바 버튼 또는 D 키. 반응 한도 (1/3/5), 채팅 시작 확률 (0.10/0.30/0.50), 그룹 형성 확률 (0.05/0.20/0.35) 조정. localStorage에 저장.?) — 이중 언어 (영어 + 한국어) 단축키 설명. 오른쪽 상단 버튼, ? 또는 Shift+/로 전환. ESC로 닫기.| 키 | 동작 | ||
|---|---|---|---|
? |
단축키 설명 열기 / 닫기 | ||
1–9 |
세션 #N 포커스 | ||
0 |
세션 패널 닫기 | ||
Esc |
패널 + 모달 닫기 | ||
T |
대화록 뷰어 열기 (세션 선택됨) | ||
L |
Live PTY 탭으로 전환 | ||
N |
영구 이름표 전환 (호버 / 선택 시 항상 이름 표시) | ||
M |
미니멀 모드 미리보기 전환 (팩이 설치되어 있어도 절차적 스프라이트) | ||
← → |
타임라인 ±1초 스크럽 | ||
Space |
타임라인 재생 / 일시정지 | ||
E |
세계 편집기 전환 | ||
D |
드라마 레벨 순환 (차분 / 보통 / 활기참) | ||
Ctrl-Z / Ctrl-S / 화살표 / F |
편집기 실행취소 / 저장 / 이동 / 뒤집기 |
가장 빠른 방법 — 체크아웃 필요 없음, npx를 github 저장소에 직접 지정:
npx -y github:codemoo/agent-world
# → 생성된 API 토큰 출력, http://localhost:3102 부팅
# 데이터는 ~/.agent-world/에 저장되어 npm 캐시가 깨끗하게 유지됨.선택적 플래그:
npx -y github:codemoo/agent-world --port 4000 # 사용자 지정 포트
npx -y github:codemoo/agent-world --token my-token # 토큰 고정
npx -y github:codemoo/agent-world --install-hooks --apply
# PreToolUse 훅 설치또는 개발용 (클론 + 해킹):
# 1) 의존성 설치
npm install
# 2) 서버 시작
export AGENT_WORLD_API_TOKEN=$(openssl rand -hex 16)
npm start
# 3) http://localhost:3102 열기에셋 필요 없음 — 절차적 스프라이트 (폴백 가구, 나무, 꽃, 모자 색상 아바타)로 미니멀 모드로 실행됩니다. 오른쪽 아래 배너에서 업그레이드 방법을 설명합니다.
!미니멀 모드 데모
PixyMoon Cute RPG World를 pixymoon.itch.io에서 구매하고 추출된 팩을 assets/pixymoon/Cute RPG World/ 아래에 넣으세요. 서버는 다음 리로드 시 자동으로 인식 — 미니멀 모드 배너가 사라지고 Assets Manager와 World Editor가 활성화되며 50개 이상의 가구 스프라이트가 픽셀 아트로 렌더링됩니다.
PixyMoon 팩은 이 저장소에 포함되어 있지 않습니다 (라이선스에 따라 직접 구매해야 함). assets/pixymoon/README.md 참조.
서버가 읽는 파일:
~/.claude/sessions/<pid>.json — 라이브 세션 메타데이터~/.claude-control/events/<pid>.json — claude-control이 설치된 경우 훅 이벤트~/.claude/plugins/agent-world/events/<pid>.jsonl — 자체 플러그인의 훅 이벤트 (옵트인)~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl — 필요 시 대화록 테일링claude-control이 없으면 훅을 설치하세요 (추가적이며 ~/.claude/settings.json을 건드리지 않음):
npm run install-hooks # 드라이런, 계획 출력
npm run install-hooks -- --apply # 실제로 플러그인 + 훅 스크립트 작성~/.claude/plugins/agent-world/ 아래에 세 개의 스크립트를 설치합니다:
SessionStart, UserPromptSubmit, Stop, PostToolUse, SessionEnd, SubagentStart, SubagentStop) — 비동기, 스냅샷터가 읽는 JSONL 빵 부스러기 추가.async: false); 보류 중인 도구 호출을 /api/hooks/permission-request에 POST하고 브라우저 클릭을 최대 92초 동안 기다림. allow/deny 시 [...]