Pixel Agents — 개요

Pixel Agents는 터미널에서 실행 중인 AI 코딩 에이전트를 작은 사무실에서 일하는 애니메이션 픽셀 아트 캐릭터로 바꿔주는 도구입니다. 원시 텍스트가 스크롤되는 것을 보는 대신, 작은 캐릭터가 책상으로 걸어가 앉고, 파일을 편집할 때 입력하고, 검색할 때 읽고, 사용자 입력을 기다릴 때 시각적 플래그를 올리는 것을 볼 수 있습니다.

두 가지 실행 방법

동일한 코드베이스가 두 가지 형태로 제공됩니다.

• VS Code 확장 프로그램 — VS Code Marketplace 또는 Open VSX에서 설치할 수 있습니다. 에이전트는 VS Code 터미널에서 시작됩니다. 캐릭터는 터미널 옆 패널에 나타납니다.
• 독립형 CLI — 프로젝트 폴더에서 npx pixel-agents를 실행합니다. 로컬 서버를 시작하고 브라우저에 동일한 사무실을 표시합니다. tmux, 원격 머신 및 VS Code가 아닌 워크플로에 유용합니다.

주요 기능

• 에이전트 하나, 캐릭터 하나 — 각 Claude Code 터미널에는 고유한 애니메이션 캐릭터가 있습니다.
• 실시간 활동 추적 — 캐릭터는 에이전트가 실제로 수행하는 작업(쓰기, 읽기, 명령 실행)에 따라 애니메이션됩니다.
• 사무실 레이아웃 편집기 — 내장 편집기를 사용하여 바닥, 벽, 가구로 사무실을 디자인합니다.
• 말풍선 — 에이전트가 입력이나 권한을 기다릴 때 시각적 표시기.
• 소리 알림 — 에이전트가 턴을 끝내거나 권한을 요청할 때 선택적 차임.
• 하위 에이전트 및 팀 — 임시 하위 에이전트와 영구 Claude 팀원이 팀 역할 및 수명 주기 변경을 포함하여 별도의 캐릭터로 나타납니다.
• 영구 레이아웃 — 사무실 디자인이 저장되고 VS Code 창 간에 공유됩니다.
• 공유 레이아웃 및 자산 — 레이아웃 가져오기/내보내기 및 외부 캐릭터, 애완동물, 가구 팩 로드.
• 영역 — 사무실에 이름이 지정된 영역을 그리고 작업 영역 폴더를 해당 영역에 매핑하면 새 에이전트가 해당 폴더에 매핑된 영역에 앉습니다.
• 다양한 캐릭터 — 6개의 내장 캐릭터(JIK-A-4, Metro City의 무료 캐릭터 팩 기반).

요구 사항

• Claude Code CLI 설치 및 구성(현재 지원되는 유일한 AI 에이전트이며 Codex, Gemini, Cursor 등은 로드맵에 있음).
• VS Code 확장 프로그램: VS Code 1.105.0 이상.
• 독립형 CLI: Node.js 20 이상.
• Windows, Linux 또는 macOS.

작동 방식(간단히)

Pixel Agents는 두 가지 경로를 통해 Claude Code가 무엇을 하고 있는지 감지합니다.

1. 후크 모드(기본값) — 후크 스크립트가 SessionStart, PreToolUse, PermissionRequest, Stop과 같은 Claude 이벤트를 수신한 다음 인증된 이벤트를 활성 Pixel Agents 서버로 보냅니다.
2. 휴리스틱 모드(폴백) — 후크를 사용할 수 없을 때 ~/.claude/projects/ 아래의 Claude JSONL 세션 기록을 스캔하여 에이전트 상태를 추론합니다.

두 소스 모두 공유 이벤트 모델로 정규화되고, 런타임은 중앙 상태 저장소를 업데이트하며, 사무실은 Canvas 2D로 경로 찾기 및 캐릭터 상태 머신을 사용하여 렌더링됩니다.

중요: Pixel Agents는 Claude Code 자체를 수정하지 않습니다. 후크 구성은 ~/.claude/ 아래에 있고, 자체 영구 데이터는 ~/.pixel-agents/ 아래에 있습니다.

아키텍처

코드베이스는 네 가지 주요 부분으로 나뉩니다.

• core/ — 공급자, 어댑터, 전송, 스키마 및 메시지 계약(런타임 부작용 없음).
• server/ — 공유 Fastify 서버, 에이전트 런타임, 영속성, Claude 공급자, 기록 스캔 및 독립형 CLI.
• adapters/vscode/ — VS Code 어댑터: 터미널, 영속성 및 웹뷰 브리지.
• webview-ui/ — React 19, Vite, Canvas 2D 및 VS Code 및 브라우저 WebSocket 클라이언트용 어댑터별 전송.

설계는 에이전트에 구애받지 않고 편집기에 구애받지 않습니다. 유형화된 HookProvider 인터페이스가 통합 경계를 정의하므로 새 AI 도구를 추가하는 것은 코드의 단일 하위 디렉토리입니다.

보안 참고 사항(README에서)

독립형 CLI는 ?token=이 포함된 URL을 출력합니다. 해당 토큰은 보유자 권한입니다. 즉, 토큰을 보유한 사람은 서버에 도달할 수 있는 모든 곳에서 후크 설치를 승인하고 에이전트를 시작할 수 있습니다. URL을 비밀로 취급하세요. 공유 채널에 붙여넣지 말고 브라우저 기록에 남는다는 점에 유의하세요. 기본 바인드 주소는 127.0.0.1입니다. 0.0.0.0에 바인딩하면 UI와 WebSocket이 로컬 네트워크에 노출되므로 신뢰할 수 있는 네트워크에서만 수행해야 합니다.

라이선스

MIT 라이선스.