# DIY Agent Status Pad ## AI 에이전트의 상태를 책상 위 RGB 버튼으로 확인하는 패드 Codex나 Claude에 작업을 맡겨놓고, 끝났는지 확인하려고 창을 계속 열어본 적이 있나요? 이 프로젝트는 에이전트의 상태를 물리 버튼의 색상으로 표시하는 USB 패드를 만드는 구상입니다. 공식 Codex Micro에서 아이디어를 얻었지만, 동일 제품을 복제하는 프로젝트는 아닙니다. 시판 조립용 보드와 자체 연결 프로그램을 사용하며, 공식 앱의 자동 기기 인식을 전제로 하지 않습니다. > **배포 단계: 기획·인터랙티브 시안.** > 이 패키지에는 설명서와 브라우저 데모가 들어 있습니다. 실제 보드용 펌웨어, Mac 연결 프로그램, 에이전트별 상태 수집 코드는 아직 포함되지 않습니다. 부품을 조립한 뒤 파일 하나를 설치하면 완성되는 제작 키트가 아닙니다. 하드웨어 실물 동작도 아직 검증하지 않았습니다. --- ## 1. 무엇을 만들까요? 첫 목표는 USB로 Mac에 연결하는 **4×4 RGB 실리콘 버튼 패드**입니다. - 버튼마다 다른 에이전트 세션의 상태를 표시합니다. - 세션을 선택해 확인할 수 있는 물리 인터페이스로 확장합니다. - 화면·다이얼·무선·배터리·기계식 스위치는 첫 버전에서 제외합니다. - 새 케이스 없이 보드 조립형으로 시작합니다. ### 상태 표시 규칙 - 흰색: 연결된 세션이 대기 중. - 파란색: 작업 중. - 주황색: 사용자의 응답 또는 승인이 필요함. - 초록색: 한 턴이 끝나 확인할 결과가 있음. - 빨간색: 오류. - 꺼짐: 연결된 세션 없음. **초록색은 작업 결과의 정확성이나 테스트 통과를 보증하지 않습니다.** 연결 끊김은 대기·완료와 구분할 별도 패턴이 필요합니다. 현재 데모에는 연결 끊김 상태가 구현되지 않았습니다. ### 예시 배치 - 위쪽 8개: 세션별 상태 표시. - 아래쪽 8개: 사용자 지정 동작용 예비 슬롯. 이는 예시이며, 16개를 모두 상태 표시용으로 사용하는 구성도 향후 가능합니다. 실제 명령 실행 기능은 아직 구현되지 않았습니다. --- ## 2. 배포 파일 - `demo/agent-pad-anatomy.html`: 설치 없이 열 수 있는 자체 포함형 브라우저 데모. - `images/assembled.png`: 조립 상태 시안. - `images/exploded.png`: 분해 구조 시안. - `source/agent-pad-anatomy-source.zip`: 데모 빌드 스크립트·검증 스크립트·Anatomy 핵심 도구·라이선스. - `licenses/ANATOMY-LICENSE.txt`: 사용한 Anatomy 도구의 MIT 라이선스. ### 데모 사용법 1. 배포 ZIP 파일을 압축 해제합니다. 2. `demo/agent-pad-anatomy.html`을 Chrome·Edge·Safari 등 브라우저로 엽니다. 배포 전 실행 검증은 Chromium에서 수행했습니다. 3. 색이 켜진 버튼을 누르거나 세션 선택 메뉴를 사용합니다. 4. ‘데모 상태 변경’에서 상태를 바꿔 버튼 색이 바뀌는지 확인합니다. 5. ‘분해 보기’로 PCB·컨트롤러·고정판·실리콘 버튼의 관계를 확인합니다. 6. ‘라이트 / 다크’로 화면 테마를 바꿉니다. 브라우저 데모는 USB 장치에 연결하지 않으며, 실제 Codex·Claude 요청이나 승인을 보내지 않습니다. 인터넷 연결·API 키·로그인이 필요하지 않습니다. --- ## 3. 필요한 재료 ### 필수 **RGB 버튼 보드 — 1개** - 검색어: `Pimoroni Pico RGB Keypad Base PIM551` - 4×4 실리콘 버튼과 개별 제어 가능한 APA102 RGB LED 16개. - TCA9555 I/O 확장기를 통해 버튼 입력을 읽는 구성. - 제조사 안내 구성: 보드·실리콘 키패드·고정판·볼트/너트·고무발. - Pico 컨트롤러는 별매입니다. - 제품: https://shop.pimoroni.com/products/pico-rgb-keypad-base **컨트롤러 — 1개** - 검색어: `라즈베리파이 Pico H 헤더 납땜 완료` - 핀이 이미 납땜된 Raspberry Pi Pico H를 권장합니다. - 일반 Pico의 헤더 미장착 제품은 납땜이 필요합니다. - 첫 버전에는 Wi-Fi·Bluetooth가 필요하지 않습니다. **USB 데이터 케이블 — 1개** - USB-C 포트가 있는 Mac 기준 검색어: `USB C to Micro B 데이터 케이블` - 연결 방향: Mac의 USB-C → Pico H의 Micro-USB. - 충전 전용이 아니라 데이터 전송을 지원해야 합니다. - 기존 USB 허브와 데이터 케이블이 있다면 재사용할 수 있습니다. **소형 십자드라이버 — 1개** - 검색어: `정밀 십자드라이버 세트` - 고정판 조립용. 기존 도구 재사용 가능. ### 지금은 구매하지 않아도 되는 것 - 별도 RGB LED·저항·점퍼선·브레드보드. - 인두기·납: 헤더 납땜 완료 Pico를 고른 경우. - 기계식 스위치·키캡. - 배터리·무선 모듈. - 케이스·3D 프린터. ### 구매 전 확인 - `Pico RGB Keypad Base`와 Pico 컨트롤러가 모두 필요한지 확인합니다. - Pico의 헤더 핀이 아래쪽으로 장착되어 보드 소켓에 들어가는 구성인지 확인합니다. - 다른 이름이 비슷한 LED 매트릭스·기계식 매크로패드와 혼동하지 않습니다. - 이 보드는 실리콘 버튼이며 일반 기계식 키캡을 바로 교체하는 제품이 아닙니다. - 국내 재고·배송비·세금 포함 실결제액은 별도 확인이 필요합니다. 이 문서는 검증되지 않은 총예산을 제시하지 않습니다. --- ## 4. 동작 구조 ```text Codex / Claude 등 에이전트 │ 시작·완료·오류·입력 요청 이벤트 ▼ 컴퓨터의 연결 프로그램 [미구현] │ 세션 ID → 버튼 번호 → 상태·색상 │ USB 직렬 통신 등 [구현 시 확정] ▼ Pico 펌웨어 [미구현] │ LED 제어 / 버튼 입력 처리 ▼ Pico RGB Keypad Base ``` 브라우저 시안은 이 중 ‘상태를 색으로 보여주는 인터페이스’를 미리 체험하는 도구입니다. 실제 보드 제어를 대신하지 않습니다. ### 에이전트 연동 방식 - Codex에는 공식 Hooks와 App Server 문서가 있습니다. - App Server는 턴 시작·완료·승인 요청 등을 처리할 수 있는 통합 경로입니다. - **직접 연결한 App Server 세션과 이미 실행 중인 데스크톱 앱의 모든 세션을 감시하는 것은 다른 문제입니다.** 후자가 자동으로 가능하다고 가정하지 않습니다. - Claude 등 다른 도구는 해당 도구의 현재 공식 이벤트·훅 지원을 따로 확인해야 합니다. - 첫 검증 대상으로는 직접 실행·관리할 수 있는 Codex 세션 하나를 권장합니다. 공식 문서: - https://developers.openai.com/codex/hooks - https://developers.openai.com/codex/app-server --- ## 5. 실제 제작 순서와 완료 기준 아래는 앞으로 구현할 작업 순서입니다. 바로 실행 가능한 펌웨어 설치 설명서가 아닙니다. ### A. 기구 조립 1. USB 전원을 분리한 상태에서 조립합니다. 2. 제조사 가이드에 따라 고무발·실리콘 키패드·고정판을 장착합니다. 3. Pico의 USB 포트 방향을 보드 표기와 맞춘 뒤 핀을 소켓에 끼웁니다. 4. 볼트를 과하게 조여 실리콘 버튼이 눌리거나 부풀지 않게 합니다. 완료 기준: 핀 휨·역삽입 없이 장착되고 모든 버튼이 자연스럽게 눌립니다. ### B. 보드 단독 테스트 [소프트웨어 구현 필요] 제조사의 MicroPython 또는 C/C++ 지원 자료를 기준으로 개발 환경을 정합니다. 순서대로 LED 한 개 → LED 16개 → 버튼 입력을 시험합니다. 완료 기준: 버튼마다 별도 색을 지정할 수 있고, 각 버튼 번호와 실제 입력이 일치합니다. ### C. 컴퓨터 ↔ Pico 통신 [구현 필요] Mac 연결 프로그램과 Pico 사이에 상태 전송 규약을 구현합니다. 예를 들어 다음은 **제안 메시지 형식**일 뿐, 현재 동작하는 API가 아닙니다. ```json {"version":1,"slot":0,"session_id":"example-session","state":"working"} ``` 구현 시 함께 정할 항목: - 버튼 번호 범위와 세션 매핑. - 허용 상태·잘못된 메시지 처리. - 연결 확인 및 heartbeat 타임아웃. - 재연결·중복 이벤트·지연 이벤트 처리. - 버튼 입력의 컴퓨터 방향 전달 방식. 완료 기준: 컴퓨터에서 상태를 바꾸면 실제 LED가 바뀌고, 연결 끊김을 이전 완료 상태와 구분합니다. ### D. 실제 에이전트 하나 연결 [구현 필요] 시작·응답 필요·완료·오류 이벤트를 공통 상태로 변환합니다. 프로세스가 살아 있다는 사실만으로 ‘작업 중’이라고 판단하지 않습니다. 완료 기준: 실제 세션의 상태 변화와 LED가 대응하고, 세션을 종료하거나 통신이 끊겨도 잘못된 완료 표시가 남지 않습니다. ### E. 여러 세션과 버튼 동작 [추후 확장] 세션별 고정 슬롯을 먼저 구현하고, 버튼 누르기는 ‘해당 세션 열기’부터 검증합니다. 선택한 키와 실제로 열리는 세션의 식별자가 같아야 합니다. **승인·거절·메시지 전송은 첫 버전 범위에서 제외합니다.** 나중에 추가하더라도 대상 세션과 요청 내용을 확인할 수 있어야 하며, 포커스된 창에 무조건 단축키를 보내 승인하는 방식은 피합니다. --- ## 6. 안전·보안 원칙 - 헤더 방향을 확인하고, 전원을 뺀 상태에서 조립합니다. - USB 전원만 사용하는 첫 구성에 외부 전원을 임의로 추가하지 않습니다. - 처음에는 낮은 LED 밝기부터 테스트하고 제조사의 전원 안내를 따릅니다. - 금속 물체로 노출된 핀·보드 뒷면이 단락되지 않게 합니다. - 장치에는 가급적 세션 식별자·상태·버튼 번호만 전달합니다. API 키·프롬프트·소스코드를 보낼 필요는 없습니다. - 승인 요청을 LED로 알리는 것과 실제로 승인하는 것을 분리합니다. - 연결 끊김·미할당·대기·완료를 서로 혼동하지 않게 설계합니다. --- ## 7. 현재 확인된 것 / 아직 확인하지 않은 것 ### 브라우저 데모 검증 완료 - 16개 버튼 렌더링. - 세션 버튼 선택과 상태 변경에 따른 색상 반영. - Enter 키를 통한 버튼 선택. - 조립·분해 보기 전환. - 라이트·다크 전환. - 390px 모바일 화면에서 가로 넘침 없음. - Chromium 실행 중 페이지 오류 없음. ### 미구현·미검증 - 실물 부품 조립 및 버튼·LED 구동. - Pico 펌웨어 및 USB 통신. - Mac 연결 프로그램. - 실제 Codex·Claude 상태 수집. - 세션 창 열기 및 각종 단축키. - 연결 끊김 감지·복구. - 전기적 검증·기구 치수 검증·제작용 CAD. 시안의 내부 위치·부품 높이·분해 간격은 설명용 근사치입니다. 제조사가 안내한 조립 외형은 약 60 × 101 × 16 mm이지만, 그림 자체를 실측 도면으로 사용하면 안 됩니다. --- ## 8. 데모 소스 수정 `source/agent-pad-anatomy-source.zip`을 풀면 다음 구조가 나옵니다. ```text anatomy-agent-pad/ build.mjs verify.py agent-pad-anatomy.html ANATOMY-LICENSE.txt anatomy-source/ LICENSE kit/ iso-kit.mjs ``` Node.js 20.10 이상 환경에서 압축 해제한 루트를 기준으로: ```sh node anatomy-agent-pad/build.mjs ``` 결과는 `anatomy-agent-pad/agent-pad-anatomy.html`에 생성됩니다. 빌드에는 별도 npm 패키지가 필요하지 않습니다. 이 명령은 브라우저 시안을 생성하며 보드 펌웨어를 만들지 않습니다. `verify.py`는 개발용 브라우저 검증 스크립트이며 Python Playwright와 Chromium 환경이 따로 필요합니다. --- ## 9. 출처와 라이선스 - 아이소메트릭 도구: https://github.com/wheresryan22/anatomy - Anatomy 핵심 도구는 MIT 라이선스입니다. 포함한 라이선스와 저작권 고지를 재배포 시 유지하세요. - 이 배포본이 제3자 상표·제품 디자인에 대한 권리를 부여하는 것은 아닙니다. - 보드 사양·조립 안내: https://shop.pimoroni.com/products/pico-rgb-keypad-base - 영감이 된 제품: https://worklouder.cc/creator-micro-2 - 이 프로젝트는 OpenAI·Pimoroni·Work Louder의 공식 제품이나 제휴 프로젝트가 아닙니다. **한 줄 요약:** 시판 RGB 키패드에 에이전트 상태를 연결하는 DIY 프로젝트입니다. 지금은 구매 재료·구현 범위·브라우저 시안을 공유하는 단계이며, 실물 동작은 다음 구현 단계입니다.