OpenCode Pixel Agents
OpenCode Pixel Agents는 OpenCode 세션을 가상 오피스 내부의 애니메이션 픽셀 캐릭터로 시각화해 주는 VS Code 확장 프로그램(Extension)입니다. 각 세션은 걷기, 책상에 앉기, 상태 말풍선 표시, 작업 진행 상황 등을 실시간으로 반영하는 캐릭터로 렌더링됩니다.
이 프로젝트는 기존의 pixel-agents 프로젝트에서 포크(Fork)되었으며, OpenCode 전용으로 유지 관리 및 개발되고 있습니다.
주요 기능
- OpenCode 전용 런타임 — 로컬 OpenCode 서버 API 및 SSE(Server-Sent Events) 이벤트 스트림을 사용하여 OpenCode 세션을 실행하고 시각화합니다.
- 1세션 1캐릭터 매핑 — 생성된 각각의 기본 OpenCode 세션은 가상 오피스 내의 픽셀 에이전트 캐릭터로 시각화됩니다.
- 서브 에이전트(Sub-agent) 시각화 — OpenCode의 자식 세션 및 하위 태스크(Subtask)들은 임시 서브 에이전트 캐릭터로 나타납니다.
- 실시간 상태 피드백 — 캐릭터가 동작(작업 중, 읽기 중, 대기 중, 권한 요청, 재시도, 완료 등)에 따라 실시간으로 애니메이션과 말풍선을 통해 반응합니다.
- 작업 공간 세션 유지(Persistence) — UI에서 에이전트를 명시적으로 삭제하지 않는 한, 프로젝트를 다시 열 때 기존 세션을 자동으로 복원하여 연결해 줍니다.
- 터미널 통합 — 각 에이전트는 해당하는 VS Code 터미널과 매핑되어 터미널 내부에서
opencode attach 명령어가 실행됩니다.
- VS Code 창(Window)별 로컬 서버 관리 — 개별 VS Code 창마다 고유한 OpenCode 서버 포트를 자동으로 감지/할당하고, API/SSE 통신을 해당 포트로 바인딩합니다.
- 자리 지정 및 오피스 시뮬레이션 — 에이전트를 선택하여 원하는 책상 자리에 배치할 수 있으며, 자리에 배치된 에이전트는 작업 종료 후 자동으로 자신의 책상으로 복귀합니다.
- 오피스 레이아웃 에디터 — 웹뷰 내에서 직접 바닥(floor), 벽(wall), 가구(furniture)를 배치하고 방을 꾸밀 수 있는 레이아웃 에디터를 내장하고 있습니다.
- 레이아웃 가져오기/내보내기 — 오피스 배치 레이아웃을 JSON 파일로 저장하고 공유할 수 있습니다.
- 작업 완료 알림음 — 에이전트의 작업이 완료되었을 때 차임벨 소리를 재생하는 옵션을 제공합니다.
- 카메라 제어 — 마우스 왼쪽 드래그로 화면 이동(Pan), 휠로 확대/축소(Zoom), 마우스 휠 클릭으로 카메라 중앙 정렬을 지원합니다.
요구 사항
- VS Code 1.50.0 이상
- OpenCode CLI가 설치되어 있고
PATH 환경 변수에 등록되어 있어야 합니다.
시작하기
소스 코드로 실행하기
git clone https://github.com/develop-jay/opencode-pixel-agents.git
cd opencode-pixel-agents
npm install
cd webview-ui && npm install && cd ..
npm run build
이후 VS Code에서 F5 키를 누르면 Extension Development Host(확장 개발 호스트) 창이 열립니다.
기본 사용 방법
- VS Code 사이드바 혹은 명령창을 통해 OpenCode Pixel Agents 패널을 엽니다.
- 하단 툴바의 + Agent 버튼을 클릭하여 새로운 OpenCode 세션을 생성합니다.
- 생성된 터미널이나 OpenCode 흐름에서 평소처럼 작업을 수행합니다.
- 가상 오피스 내부에서 세션 및 하위 태스크의 실시간 활동을 감상합니다.
- 에이전트 캐릭터를 클릭하여 포커스(선택)할 수 있습니다.
- 오피스 내 빈 의자나 책상을 클릭하면 선택된 에이전트의 자리가 재지정됩니다.
- 에이전트 캐릭터의 닫기(X) 버튼을 누르면 에이전트가 오피스에서 제거되며, 유지되던 OpenCode 세션도 함께 삭제됩니다.
동작 원리
새로운 에이전트를 생성하면 확장 프로그램은 내부적으로 다음 작업을 수행합니다:
현재 VS Code 창에 할당할 로컬 OpenCode 서버의 상태를 확인합니다.
사용 가능한 로컬 포트를 찾아 해당 창 전용 포트로 결정합니다.
HTTP API를 통해 로컬 서버에 새 OpenCode 세션을 생성합니다.
VS Code 터미널 영역에 세션 이름으로 새 터미널을 개설합니다.
터미널 창에서 다음 명령어를 실행하여 세션을 어태치(Attach)합니다:
opencode attach http://127.0.0.1:<resolved-port> --session <session-id> --dir "<workspace>"
OpenCode의 /global/event SSE(Server-Sent Events) 스트림을 구독합니다.
수신되는 세션/도구(Tool)/하위 태스크(Subtask)/권한 요청 등의 이벤트를 오피스 상태, 오버레이, 캐릭터 애니메이션과 매핑하여 실시간으로 업데이트합니다.
세션 및 터미널의 제목은 다음 형식으로 지정됩니다:
OpenCode Pixel Agent - <project-name>: <index>
동일한 프로젝트(작업 공간)를 다시 열었을 때, 로컬에 세션 정보가 살아있는 경우 이전에 생성했던 에이전트들을 자동으로 복원(Restore)하여 재연결해 줍니다. UI에서 에이전트를 삭제하면 지속성 저장소(Persistence)에서 해당 바인딩 정보가 지워지고 관련된 OpenCode 세션도 서버에서 완전히 삭제됩니다.
레이아웃 에디터 (Layout Editor)
내장된 레이아웃 에디터는 아래 기능들을 지원합니다:
- 바닥 타일 그리기 (Floor Painting)
- 벽 타일 그리기 (Wall Painting)
- 도구 모음: 지우개(Erase), 선택(Select), 스포이드(Pick), 배치(Place)
- 가구 배치: 이동, 회전, 삭제
- 실행 취소(Undo) 및 다시 실행(Redo)
- 레이아웃 파일 가져오기(Import) 및 내보내기(Export)
- 최대 64×64 크기까지 확장 가능한 그리드 편집
오피스 에셋 (Office Assets)
이 프로젝트의 확장 에셋 파이프라인에서 사용하는 기본 타일셋은 Donarg의 Office Interior Tileset (16x16) 에셋을 기반으로 설계되었습니다.
참고: 해당 타일셋 에셋 파일은 본 리포지토리에 기본적으로 포함되어 있지 않습니다.
전체 가구 카탈로그를 로컬 환경에서 그대로 활용하고 싶으시다면, 해당 에셋을 개별 구매하신 뒤 프로젝트 루트에서 아래 명령을 실행하십시오:
npm run import-tileset
에셋 라이선스를 구매하지 않으시더라도, 번들로 기본 제공되는 가구 에셋 및 오피스 레이아웃을 통해 확장 프로그램을 문제없이 바로 사용하실 수 있습니다.
개발 가이드
npm install
cd webview-ui && npm install && cd ..
npm run build
확장 프로그램 패키징(VSCE Package):
npx @vscode/vsce package
현재 범위 및 제약사항
- 런타임 환경은 OpenCode만을 공식 지원합니다.
- 이 프로젝트는 VS Code 웹뷰 상에서 OpenCode 세션을 시각적으로 모니터링하고 가상 오피스 모델로 즐기는 경험에 초점이 맞추어져 있습니다.
- 프로젝트 내부에 이전 버전(
pixel-agents 원형)의 레거시 명칭이나 잔재가 일부 남아있을 수 있으나, 활성화된 모든 런타임 로직은 OpenCode 기반으로 완벽히 마이그레이션되어 있습니다.
개발자 정보
라이선스
본 프로젝트는 MIT 라이선스 하에 배포 및 관리됩니다.
