Pixel Agents

터미널에서 도는 AI 코딩 에이전트(Claude Code 등)를 작은 사무실에서 일하는 픽셀아트 캐릭터로 시각화. VS Code 확장과 npx pixel-agents 독립 CLI 두 형태로 배포되며, agent-agnostic HookProvider 인터페이스로 통합 경계를 정의한다. MIT 라이선스.

개요

Pixel Agents(pixel-agents-hq/pixel-agents)는 구동 중인 AI 코딩 에이전트 각각에 픽셀아트 캐릭터를 할당해, 캐릭터가 책상으로 걸어가 앉고 파일을 편집할 땐 타자를 치고 검색할 땐 책을 읽고 입력을 기다릴 땐 시각적으로 깃발을 드는 식의 애니메이션으로 실제 에이전트 활동을 보여준다. “가장 장난스러운 방식으로 에이전트를 오케스트레이션”한다는 슬로건 아래, 에이전트 관리를 행정 작업이 아니라 놀이처럼 느끼도록 만드는 것이 목표다.

같은 코드베이스에서 두 형태로 배포된다: VS Code 마켓플레이스/오픈 VSX 확장(터미널에서 에이전트를 스폰하고 패널 영역에 캐릭터 렌더), 그리고 npx pixel-agents 독립 CLI(로컬 서버를 띄워 같은 사무실을 브라우저 앱으로 서빙, tmux·원격·비 VS Code 워크플로에 유용). Claude Code가 현재 참조 구현이며, Codex·Gemini·Cursor 등은 로드맵 상에 있다.

핵심 특징

에이전트당 한 캐릭터 — Claude Code 터미널마다 고유 애니메이션 캐릭터
실시간 활동 추적 — 캐릭터가 에이전트의 실제 동작(쓰기·읽기·명령 실행)에 맞춰 애니메이션
사무실 레이아웃 에디터 — 바닥·벽·가구로 사무실을 설계하는 내장 에디터
말풍선 & 소리 알림 — 입력 대기/권한 요청 시각 표시, 에이전트 턴 종료 시 선택적 차임
서브에이전트 & 에이전트 팀 — 임시 서브에이전트와 영구 Claude 팀원을 별도 캐릭터로 표시(역할·라이프사이클 변경 포함)
영구 레이아웃 — 사무실 설계 저장 및 VS Code 창 간 공유
영역(Areas) — 명명된 사무실 구역을 칠하고 워크스페이스 폴더를 매핑해, 폴더별로 해당 영역에 에이전트 착석
외래 자산 지원 — 레이아웃 가져오기/내보내기 및 외부 캐릭터·펫·가구 팩 로드
6종 캐릭터 — JIK-A-4의 Metro City 팩 기반

아키텍처

컴포넌트	역할
`core/`	provider, adapter, transport, schema, AsyncAPI 메시지 계약(런타임 부작용 없음)
`server/`	공유 Fastify 서버, 에이전트 런타임, 영속화, Claude provider, 트랜스크립트 스캔, 독립 CLI
`adapters/vscode/`	VS Code 터미널·영속화·웹뷰 브리지
`webview-ui/`	React 19, Vite, Canvas 2D, 호스트별 전송(VS Code 및 브라우저 WebSocket)

감지 경로 2종: hooks 모드(기본 — SessionStart·PreToolUse·PermissionRequest·Stop 등 Claude 이벤트를 hook 스크립트가 수신해 활성 서버로 인증된 이벤트 전송), 트랜스크립트 모드(폴백 — ~/.claude/projects/의 JSONL 세션 파일을 스캔). 두 소스는 공유 AgentEvent 모델로 정규화되고 AgentRuntime이 중앙 상태 저장소를 갱신하며, 활성 전송이 React 웹뷰로 타입 메시지를 보낸다. 사무실은 Canvas 2D + 패스파인딩 + 캐릭터 상태머신으로 렌더링.
번들/테스트: 확장과 CLI는 esbuild, 웹뷰는 Vite. 단위 테스트 Vitest·Node test runner, 종단간 Playwright(VS Code·독립 모두 대상).
agent-agnostic 통합: 타입된 HookProvider 인터페이스가 통합 경계이므로, 새 AI 도구 추가는 코드 서브디렉터리 하나로 끝난다. Claude Code 외는 아직 미구현(로드맵).

비전 — “play a game, build a product”

에이전트 오케스트레이션을 놀이처럼 느끼도록 만드는 세 단계 로드맵:

어디서든 모든 것과 — 오늘은 VS Code/브라우저의 Claude Code. 앞으로는 어떤 에이전트든, 어디서든. 새 CLI는 재작성이 아니라 서브디렉터리 하나. 현재 도움이 가장 필요한 영역.
진짜 게임으로 — 레이트리밋/토큰 예산용 체력바, 관심 지표 점수, 기능이 있는 가구, 프로젝트별 세이브파일처럼 여는 사무실.
오케스트레이션 프론티어 확장 — 오케스트레이터 캐릭터, 드래그 박스로 팀 구성, 에이전트 간 작업 전달, 보드를 가리키면 작업을 스스로 고르기.

대부분은 아직 로드맵상에 있다.

요구사항

Claude Code CLI 설치·구성
VS Code 확장: VS Code 1.105.0 이상
독립 CLI: Node.js 20 이상
Windows / Linux / macOS

시작하기

VS Code 확장

마켓플레이스/오픈 VSX에서 설치.
터미널 옆 Pixel Agents 패널을 연다.
+ Agent를 눌러 Claude Code 실행(다중 루트 워크스페이스면 폴더 먼저 선택).

--dangerously-skip-permissions를 쓰려면 + Agent 위에 hover해 Skip permissions mode 버튼 사용(보안 의미 수용 시에만). 확장 밖에서 시작한 Claude 세션도 Settings → Watch All Sessions로 감지 가능.

독립 CLI

cd /path/to/your/project
npx pixel-agents          # 빈 로컬 포트 선택 후 URL 출력
# 또는 전역 설치
npm install --global pixel-agents
pixel-agents --port 3100 --host 127.0.0.1

기본 bind 주소는 127.0.0.1. 0.0.0.0 바인드는 UI·WebSocket을 로컬 네트워크에 노출하므로 신뢰할 수 있는 네트워크에서만 사용. 확장과 CLI 동시 구동 지원 — 각 서버는 ~/.pixel-agents/servers/에 개별 등록되고, Claude hook 스크립트가 활성 등록 모두에 이벤트를 보낸다.

운영 위치

사무실 레이아웃은 64×64 타일까지 확장 가능(그리드 바깥 고경계 클릭).
hook 설정은 ~/.claude/에, 영속 데이터는 ~/.pixel-agents/에 저장. Claude Code 자체는 수정하지 않는다.

description	터미널의 AI 코딩 에이전트를 픽셀아트 캐릭터로 시각화해 주는 VS Code 확장·CLI 도구다. 한 사무실에 에이전트를 앉히고 실시간 활동을 애니메이션으로 보여준다.
tags	entity, ai-agents, developer-tools, productivity, open-source
aliases	픽셀 에이전트

LLM Wiki

탐색기