pixel-agents-hq/pixel-agents

<h1 align="center"> <a href="https://github.com/pixel-agents-hq/pixel-agents/discussions"> <img src="webview-ui/public/banner.png" alt="Pixel Agents"> </a> </h1>

<h2 align="center" style="padding-bottom: 20px;"> AI 에이전트가 실제 작업을 수행하는 게임 인터페이스 </h2>

<div align="center" style="margin-top: 25px;">

</div>

<div align="center"> <a href="https://marketplace.visualstudio.com/items?itemName=pablodelucca.pixel-agents">🛒 VS Code Marketplace</a> • <a href="https://github.com/pixel-agents-hq/pixel-agents/discussions">💬 Discussions</a> • <a href="https://github.com/pixel-agents-hq/pixel-agents/issues">🐛 Issues</a> • <a href="CONTRIBUTING.md">🤝 Contributing</a> • <a href="CHANGELOG.md">📋 Changelog</a> </div>

<br/>

Pixel Agents는 멀티 에이전트 AI 시스템을 실제로 보고 관리할 수 있는 형태로 변환합니다. 각 에이전트는 픽셀 아트 사무실의 캐릭터가 됩니다. 걸어 다니고, 책상에 앉고, 수행 중인 작업을 시각적으로 반영합니다(코드 작성 시 타이핑, 파일 검색 시 읽기, 주의가 필요할 때 대기).

동일한 소스 트리에서 두 가지 형태로 제공됩니다:

• VS Code 확장 — VS Code Marketplace 및 Open VSX에서 pablodelucca.pixel-agents. 에이전트가 VS Code 터미널에 생성되고, 캐릭터는 패널 영역에 렌더링됩니다.
• 독립형 CLI — npx pixel-agents는 로컬 Fastify 서버를 시작하고 브라우저 SPA로 사무실을 제공합니다. tmux 워크플로우, 원격 세션 또는 데스크톱 VS Code가 없는 환경에서 유용합니다.

내부적으로 아키텍처는 완전히 에이전트 및 플랫폼에 독립적입니다. 타입화된 HookProvider 인터페이스가 통합 경계를 정의하므로 새 AI 도구를 추가하는 것은 단일 하위 디렉토리 코드로 가능합니다. 현재 Claude Code가 참조 구현이며, Codex, Gemini, Cursor 등이 로드맵에 있습니다.

!Pixel Agents screenshot

기능

• 에이전트 하나, 캐릭터 하나 — 모든 Claude Code 터미널은 고유한 애니메이션 캐릭터를 가집니다.
• 실시간 활동 추적 — 캐릭터는 에이전트가 실제로 수행하는 작업(코드 작성, 파일 읽기, 명령 실행)에 따라 애니메이션됩니다.
• 사무실 레이아웃 편집기 — 내장 편집기를 사용하여 바닥, 벽, 가구로 사무실을 디자인합니다.
• 말풍선 — 에이전트가 입력을 기다리거나 권한이 필요할 때 시각적 표시.
• 소리 알림 — 에이전트가 작업을 완료하면 선택적 차임.
• 하위 에이전트 시각화 — Task 도구 하위 에이전트가 부모에 연결된 별도 캐릭터로 생성됩니다.
• 지속적 레이아웃 — 사무실 디자인이 저장되어 VS Code 창 간에 공유됩니다.
• 외부 에셋 디렉토리 — 머신의 모든 폴더에서 사용자 정의 또는 타사 가구 팩을 로드합니다.
• 다양한 캐릭터 — 6가지 다양한 캐릭터. JIK-A-4, Metro City의 훌륭한 작업을 기반으로 합니다.

<p align="center"> <img src="webview-ui/public/characters.png" alt="Pixel Agents characters" width="320" height="72" style="image-rendering: pixelated;"> </p>

요구 사항

• VS Code 1.105.0 이상
• Claude Code CLI 설치 및 구성
• 플랫폼: Windows, Linux, macOS 지원

시작하기

Pixel Agents를 사용하려면 가장 쉬운 방법은 VS Code 확장을 다운로드하는 것입니다. 코드를 실험하거나 개발하거나 기여하려면:

소스에서 설치

git clone https://github.com/pixel-agents-hq/pixel-agents.git
cd pixel-agents
npm install      # npm workspaces가 루트 + server + webview-ui를 한 번에 설치
npm run build

그런 다음 VS Code에서 F5를 눌러 Extension Development Host를 실행합니다.

독립형 CLI를 로컬에서 시도하려면:

node dist/cli.js                 # 또는 게시 후 npx pixel-agents [--port 3100]

Fastify 서버를 시작하고 http://localhost:3100에서 웹뷰 SPA를 열며, 동일한 ~/.pixel-agents/ 네임스페이스에서 후크와 레이아웃을 VS Code 확장과 공유합니다(둘 다 실행 중인 경우).

브라우저 미리보기 및 호스팅된 보고서

웹뷰의 브라우저 미리보기 버전은 VS Code 확장 빌드와 별도로 빌드하여 Vercel에 스테이징할 수 있습니다.

npm run test
npm run e2e
npm run e2e -- --attach-videos-on-success
npm run vercel:prepare

npm run test:report를 별도로 실행하면 전체 Vercel 출력을 준비하지 않고 결합된 Allure 보고서를 로컬에서 얻을 수 있습니다.

스테이징된 Vercel 출력은 /webview/에서 독립형 웹뷰를, /reports/allure/에서 Linux Allure 보고서를 제공하며, e2e, server, webview 스위트를 결합합니다. GitHub Actions 배포 작업은 VERCELTOKEN, VERCELORGID, VERCELPROJECT_ID 시크릿을 필요로 합니다.

사용법

1. Pixel Agents 패널을 엽니다(터미널 옆 하단 패널 영역에 나타납니다).
2. + Agent를 클릭하여 새 Claude Code 터미널과 해당 캐릭터를 생성합니다. 마우스 오른쪽 버튼을 클릭하면 --dangerously-skip-permissions(모든 도구 승인 프롬프트 우회)로 실행하는 옵션이 있습니다.
3. Claude로 코딩을 시작하면 캐릭터가 실시간으로 반응하는 것을 볼 수 있습니다.
4. 캐릭터를 클릭하여 선택한 다음 좌석을 클릭하여 재할당합니다.
5. Layout을 클릭하여 사무실 편집기를 열고 공간을 사용자 정의합니다.

레이아웃 편집기

내장 편집기를 사용하여 사무실을 디자인할 수 있습니다:

• 바닥 — 전체 HSB 색상 제어
• 벽 — 색상 사용자 정의가 가능한 자동 타일링 벽
• 도구 — 선택, 페인트, 지우기, 배치, 스포이드, 선택
• 실행 취소/다시 실행 — Ctrl+Z / Ctrl+Y로 50단계
• 내보내기/가져오기 — 설정 모달을 통해 JSON 파일로 레이아웃 공유

그리드는 최대 64×64 타일까지 확장 가능합니다. 현재 그리드 외부의 고스트 테두리를 클릭하여 확장합니다.

사무실 에셋

모든 사무실 에셋(가구, 바닥, 벽)은 이제 완전히 오픈 소스이며 이 저장소의 webview-ui/public/assets/ 아래에 포함되어 있습니다. 외부 구매나 가져오기가 필요 없으며 모든 것이 즉시 작동합니다.

각 가구 항목은 assets/furniture/ 아래에 자체 폴더에 있으며, 스프라이트, 회전 그룹, 상태 그룹(켜기/끄기), 애니메이션 프레임을 선언하는 manifest.json이 포함되어 있습니다. 바닥 타일은 assets/floors/의 개별 PNG이고, 벽 타일 세트는 assets/walls/에 있습니다. 이 모듈식 구조는 코드를 건드리지 않고 에셋을 쉽게 추가, 제거 또는 수정할 수 있게 합니다.

새 가구 항목을 추가하려면 webview-ui/public/assets/furniture/에 PNG 스프라이트와 manifest.json이 있는 폴더를 만든 다음 다시 빌드하세요. 에셋 관리자(scripts/asset-manager.html)는 매니페스트를 만들고 편집하기 위한 시각적 편집기를 제공합니다.

외부 디렉토리의 가구를 사용하려면 설정 → Add Asset Directory를 엽니다. 전체 매니페스트 형식과 타사 에셋 팩 사용 방법은 docs/external-assets.md를 참조하세요.

캐릭터는 JIK-A-4, Metro City의 훌륭한 작업을 기반으로 합니다.

작동 방식

Pixel Agents에는 두 가지 병렬 감지 경로가 있습니다:

• 후크 모드 (권장) — Claude Code의 공식 Hooks API가 이벤트(SessionStart, PreToolUse, Notification, Stop 등)를 로컬 Fastify 서버(POST /api/hooks/:providerId)에 POST합니다. 즉각적이고 안정적입니다. 서버 검색은 ~/.pixel-agents/server.json을 통해 이루어집니다.
• 휴리스틱 모드 (대체) — ~/.claude/projects/<project-hash>/<session-id>.jsonl에서 JSONL 트랜스크립트 파일을 폴링합니다. 후크가 설치되지 않은 경우 사용됩니다.

단일 HookProvider.normalizeHookEvent(raw)가 각 CLI의 후크 페이로드를 표준 AgentEvent로 변환합니다. 공유 AgentRuntime이 AgentEvent.kind에 따라 디스패치하고, AgentStateStore를 변경하며, 브로드캐스트 레이어가 상태 이벤트를 활성 전송을 통해 타입화된 ServerMessage로 변환합니다.

웹뷰는 캔버스 렌더링, BFS 경로 찾기, 캐릭터 상태 머신(대기 → 걷기 → 타이핑/읽기)을 갖춘 경량 게임 루프를 실행합니다. 모든 것은 정수 확대/축소 수준에서 픽셀 단위로 완벽합니다. 게임 상태는 React 외부의 명령형 OfficeState 클래스에 있으며, React 컴포넌트는 렌더링 중에 이를 읽지만 상태를 소유하지 않습니다.

Claude Code에 대한 수정은 필요하지 않습니다. Pixel Agents는 순수하게 관찰적입니다.

기술 스택

4개 패키지 모노레포, npm workspaces:

• core/ — TypeScript 전용 프로토콜 + 인터페이스(AsyncAPI 3.0 계약, HookProvider, MessageTransport, StateAdapter). 런타임 부작용 없음.
• server/ — Fastify v5 (HTTP + WebSocket), Vitest. AgentRuntime, AgentStateStore, SessionRouter, DismissalTracker, 파일 감시, 트랜스크립트 파싱, 프로바이더를 소유합니다. npx pixel-agents CLI를 제공합니다.
• adapters/vscode/ — VS Code Extension API. 데스크톱 표면을 위해 core/ + server/를 구성합니다.
• webview-ui/ — React 19, Vite, Canvas 2D. 전송에 독립적(VS Code에서는 PostMessageTransport, 브라우저에서는 WebSocketTransport).

빌드: esbuild (확장 + CLI + 후크 스크립트), Vite (웹뷰 SPA). 테스트: Vitest (서버 + 웹뷰 단위), Playwright (실제 VS Code 및 독립형 Fastify에 대한 e2e).

알려진 제한 사항

• 에이전트-터미널 동기화 — 에이전트가 Claude Code 터미널 인스턴스에 연결되는 방식이 매우 견고하지 않으며, 특히 터미널이 빠르게 열리고 닫히거나 세션 간에 복원될 때 동기화가 깨지는 경우가 있습니다.
• 휴리스틱 기반 상태 감지 — Claude Code의 JSONL 트랜스크립트 형식은 에이전트가 사용자 입력을 기다리는 중인지 또는 작업을 완료했는지에 대한 명확한 신호를 제공하지 않습니다. 현재 감지는 휴리스틱(유휴 타이머, 작업 지속 시간 이벤트)을 기반으로 하며 종종 잘못 작동합니다. 에이전트가 잠시 잘못된 상태를 표시하거나 전환을 놓칠 수 있습니다.
• Linux/macOS 팁 — 폴더를 열지 않고 VS Code를 실행하는 경우(예: code 명령어만), 에이전트는 홈 디렉토리에서 시작됩니다. 이는 완전히 지원되지만, Claude 세션이 홈 디렉토리를 프로젝트 루트로 사용하여 ~/.claude/projects/ 아래에 추적된다는 점을 인지하세요.

문제 해결

에이전트가 유휴 상태로 멈추거나 생성되지 않는 경우:

1. 디버그 보기 — Pixel Agents 패널에서 톱니바퀴 아이콘(설정)을 클릭한 다음 Debug View를 토글합니다. 에이전트별 연결 진단(JSONL 파일 상태, 파싱된 줄 수, 마지막 데이터 타임스탬프, 파일 경로)을 표시합니다. "JSONL not found"가 표시되면 확장이 세션 파일을 찾을 수 없는 것입니다.
2. 디버그 콘솔 — 소스에서 실행 중인 경우(Extension Development Host via F5), VS Code의 View > Debug Console을 엽니다. [Pixel Agents]를 검색하여 프로젝트 디렉토리 확인, JSONL 폴링 상태, 경로 인코딩 불일치, 인식되지 않은 JSONL 레코드 유형에 대한 자세한 로그를 확인합니다.

향후 방향

장기적인 비전은 AI 에이전트를 관리하는 것이 심즈를 플레이하는 것처럼 느껴지지만 결과는 실제 작업물인 인터페이스입니다.

• 캐릭터로서의 에이전트 — 보고, 할당하고, 모니터링하고, 리디렉션할 수 있으며, 각각 가시적인 역할(디자이너, 코더, 작가, 리뷰어), 통계, 컨텍스트 사용량 및 도구를 가집니다.
• 디렉토리로서의 책상 — 에이전트를 책상으로 드래그하여 프로젝트 또는 작업 디렉토리에 할당합니다.
• 프로젝트로서의 사무실 — 벽에 칸반 보드가 있어 유휴 에이전트가 자율적으로 작업을 선택할 수 있습니다.
• 심층 검사 — 에이전트를 클릭하여 모델, 브랜치, 시스템 프롬프트 및 전체 작업 기록을 확인합니다. 중단, 채팅 또는 리디렉션합니다.
• 토큰 건강 바 — 속도 제한 및 컨텍스트 창을 게임 내 통계로 시각화합니다.
• 완전 사용자 정의 가능 — 자신만의 캐릭터 스프라이트, 테마 및 사무실 에셋을 업로드합니다. 결국 픽셀 아트를 넘어 3D 또는 VR로 이동할 수도 있습니다.

이를 위해 아키텍처는 모든 수준에서 모듈식이어야 합니다:

• 플랫폼 독립적: 오늘날 VS Code 확장, 내일은 Electron 앱, 웹 앱 또는 기타 호스트 환경.
• 에이전트 독립적: 오늘날 Claude Code, 그러나 Codex, OpenCode, Gemini, Cursor, Copilot 등을 구성 가능한 어댑터를 통해 지원하도록 구축됨.
• 테마 독립적: 커뮤니티에서 만든 에셋, 스킨 및 테마.